Time Service, Take 2: The Reactor
APR has all the tools necessary to implement a Reactor. The sample program step2 is a Reactor-based refinement of the time service.
The first thing to notice is that step2 wraps APR sockets in objects to simplify calls. APRSocketConnection and APRSocketListener are simple implementations of client and server sockets, respectively.
The handle in the sample APR-based Reactor is the apr_pollfd_t data type (Listing Three, available electronically). Unlike the traditional UNIX handle (a primitive), apr_pollfd_t is a full-blown structure. The union desc is the low-level descriptor—here, the familiar APR socket type—and desc_type lets other code know whether the descriptor is a socket (APR_POLL_SOCKET) or file (APR_POLL_FILE). Client code sets the reqevents member to express interest in certain types of events (APR_POLLIN) and APR polling routines set the rtnevents member to describe the type of event that was received. The client_data member is of type void*, so client code can attach any pointer to the handle structure.
The Reactor can't watch for events on handles it doesn't know. Client code calls APRReactor's registerHandle() member to register handles with it. In turn, registerHandle() calls apr_pollset_add() to add the handle to its watch list, of type apr_pollset_t; see Listing Four (available electronically).
On each iteration, the Reactor's event loop (Listing Five, available electronically) first calls apr_pollset_poll() to get an array of handles that have waiting events (1). This call blocks until there is activity on at least one of the handles. For each handle in the array, the event loop checks whether the returned event type (apr_pollfd_t.rtnevents) is an error (APR_POLLNVAL or APR_POLLERR). Otherwise, if the requested event type (apr_pollfd_t.reqevents) matches the returned event type, the event loop calls the handler to do some work and moves on to the next handle.
In other Reactor implementations, this is where you'd have to use an std::map<> to track handle-handler associations. The sample code assigns the handler to the handle's client_data member, such that there's no need to keep a separate map. That means getting to the handler is as simple as casting apr_pollfd_t.client_data to the proper type (2).
If the handler call throws an exception or returns False, the Reactor adds its handle to a cleanup list. All handlers in this list are unregistered at the end of an event loop iteration (3). That covers housekeeping.
Like any good framework, the Reactor knows little about a handler's details; it only knows to call member functions on the base Handler type. This Handler interface defines two member functions: getHandle() returns the raw handle that is registered with the Reactor. doRead() is called in response to a read event.
An AcceptorHandler wraps a socket listener. Its constructor (Listing Six, also available electronically) creates an apr_pollfd_t and assigns itself as the client_data member. The socket is the wrapped socket (here, hidden behind the APRSocketListener object). Setting the reqevents member to APR_POLLIN tells the APR polling routines that this descriptor is interested in read events.
To an AcceptorHandler, a read event is a new client connection on its socket listener. That is, a call to accept a client connection won't block. The handler creates a new client socket and wraps it in a client handler, DataHandler. (This was what main() did in step1.) AcceptorHandler's doRead() always returns True. Remember, returning False will force the Reactor to unregister this handler, and there's no need to let one bad client connection shut down the listener.
A DataHandler sees an "in" or read event as an opportunity to read data from a client socket and write a response. DataHandler's doRead() holds a conversation with the remote client, just like step1's handleClient() function. doRead() returns False if the client has requested a disconnect using the time service's quit command.
You don't have to take my word for it: Start the app and connect to it from several telnet windows. You can hold multiple, concurrent conversations with the time service.
Conclusion
Subtle differences between operating systems' network stacks can hinder your efforts to writing portable native-code apps. APR can bring this goal closer to reality, and in a fashion that doesn't litter your code with #IFDEF statements. In this article, I introduced APR's OS-neutral networking and polling APIs. By no means is that the entire APR story; this toolkit also includes OS-neutral abstractions for threading, files, and even process handling.
