8.1 General Collaborations

The following collaborations occur in the Reactor pattern:

• When an application registers aConcrete Event Handlerwith theInitiation Dispatcherthe application indicates the type of event(s) thisEvent Handlerwants theInitiation Dispatcherto notify it aboutwhen the event(s) occur on the associatedHandle.
• TheInitiation Dispatcherrequests eachEvent Handlerto pass back its internalHandle. ThisHandleidentifies theEvent Handlerto the OS.
• After allEvent Handlersare registered,an application callshandle_eventsto start theInitiation Dispatcher's event loop. At this point,'Courier New'">Initiation Dispatchercombines theHandlefrom each registeredEvent Handlerand uses theSynchronous Event Demultiplexerto wait for events to occur on theseHandles. For instance,the TCP protocol layer uses theselectsynchronous event demultiplexing operation to wait for client logging record events to arrive on connected socketHandles.
• TheInitiation Dispatcherwhen a Handle corresponding to an event source becomes “ready,” e.g.,that a TCP socket is “ready for reading.”
• TheInitiation DispatchertriggersEvent Handlerhook method in response to events on the readyHandles. When events occur,'Courier New'">Initiation Dispatcheruses theHandlesactivated by the event sources as “keys” to locate and dispatch the appropriateEvent Handler's hook method.
• TheInitiation Dispatchercalls back to thehandle_eventhook method of theEvent Handlerto perform application-specific functionality in response to an event. The type of event that occurred can be passed as a parameter to the method and used internally by this method to perform additional servicespecific demultiplexing and dispatching. An alternative dispatching approach is described in Section 9.4.

The following interaction diagram illustrates the collaboration between application code and participants in the Reactor pattern:

8.2 Collaboration Scenarios

The collaborations within the Reactor pattern for the logging server can be illustrated with two scenarios. These scenarios show how a logging server designed using reactive event dispatching handles connection requests and logging data from multiple clients.

9.1 Select the Synchronous Event Demultiplexer Mechanism

TheInitiation Dispatcheruses aSynchronous Event Demultiplexerto wait synchronously until one or more events occur. This is commonly implemented using an OS event demultiplexing system call likeselect. TheHandle(s) are ready to perform I/O operations without blocking the OS process in which the application-specific service handlers reside. In general,'Courier New'">Synchronous Event Demultiplexeris based upon existing OS mechanisms,rather than developed by implementers of the Reactor pattern.

9.2 Develop an Initiation Dispatcher

The following are the steps necessary to develop theInitiation Dispatcher:

Implement the Event Handler table: AInitiation Dispatchermaintains a table ofConcrete Event Handlers. Therefore,'Courier New'">Initiation Dispatcherprovides methods to register and remove the handlers from this table at run-time. This table can be implemented in various ways,e.g.,using hashing,linear search,or direct indexing if handles are represented as a contiguous range of small integral values.

Implement the event loop entry point: The entry point into the event loop of theInitiation Dispatchershould be provided by ahandle_eventsmethod. This method controls the Handle demultiplexing provided by theSynchronous Event Demultiplexer,as well as performingEvent Handlerdispatching. Often,the main event loop of the entire application is controlled by this entry point.

When events occur,'Courier New'">Initiation Dispatcherreturns from the synchronous event demultiplexing call and “reacts” by dispatching theEvent Handler'shandle_eventhook method for each handle that is “ready.” This hook method executes user-defined code and returns control to theInitiation Dispatcherwhen it completes.

The following C++ class illustrates the core methods on theInitiation Dispatcher's public interface:

enum Event_Type
    // = TITLE
    //      Types of events handled by the
//      Initiation_Dispatcher.
//
// = DESCRIPTION
//      These values are powers of two so
//      their bits can be efficiently ‘‘or’d’’
//      together to form composite values.
{
    ACCEPT_EVENT = 01,
    READ_EVENT 02,
    WRITE_EVENT 04,
    TIMEOUT_EVENT 010,
    SIGNAL_EVENT 020,
    CLOSE_EVENT 040
};
class Initiation_Dispatcher
    //      Demultiplex and dispatch Event_Handlers
//      in response to client requests.
{
public:
    // Register an Event_Handler of a particular
// Event_Type (e.g.,READ_EVENT,ACCEPT_EVENT,// etc.).
    int register_handler (Event_Handler *eh, Event_Type et);

    // Remove an Event_Handler of a particular
// Event_Type.
int remove_handler (Event_Handler // Entry point into the reactive event loop.
int handle_events (Time_Value *timeout = 0);
};

Implement the necessary synchronization mechanisms: If the Reactor pattern is used in an application with only one thread of control it is possible to eliminate all synchronization. In this case,'Courier New'">Initiation Dispatcherserializes theEvent Handlerhandle_eventhooks within the application’s process.

However,'Courier New'">Initiation Dispatchercan also serve as a central event dispatcher in multi-threaded applications. In this case,critical sections within theInitiation Dispatchermust be serialized to prevent race conditions when modifying or activating shared state variables (such as the table holding theEvent Handlers). A common technique for preventing race conditions uses mutual exclusion mechanisms like semaphores or mutex variables.

To prevent self-deadlock,mutual exclusion mechanisms can use recursive locks[4]. Recursive locks hold prevent deadlock when locks are held by the same thread acrossEvent Handlerhook methods within theInitiation Dispatcher. A recursive lock may be re-acquired by the thread that owns the lock without blocking the thread. This property is important since the Reactor’shandle_eventsmethod calls back on application-specificEvent Handlers. Application hook method code may subsequently re-enter theInitiation Dispatchervia itsregister_handlerandremove_handlermethods.

9.3 Determine the Type of the Dispatching Target

Two different types ofEvent Handlerscan be associated with aHandleto serve as the target of anInitiation Dispatcher's dispatching logic. Implementations of the Reactor pattern can choose either one or both of the following dispatching alternatives:

Event Handler objects: A common way to associate anEvent Handlerwith aHandleis to make theEvent Handleran object. For instance,the Reactor pattern implementation shown in Section 7 registersEvent Handlersubclass objects with anInitiation Dispatcher. Using an object as the dispatching target makes it convenient to subclassEvent Handlersin order to reuse and extend existing components. In addition,objects integrate the state and methods of a service into a single component.

Event Handler functions: Another way to associate anHandleis to register a function with theInitiation Dispatcher. Using functions as the dispatching target makes it convenient to register callbacks without having to define a new class that inherits fromEvent Handler.

The Adapter pattern[5]be employed to support both objects and functions simultaneously. For instance,an adapter could be defined using an event handler object that holds a pointer to an event handler function. When thehandle_eventmethod was invoked on the event handler adapter object,it could automatically forward the call to the event handler function that it holds.

9.4 Define the Event Handling Interface

Assuming that we useEvent Handlerobjects rather than functions,the next step is to define the interface of theEvent Handler. There are two approaches:

A single-method interface: The OMT diagram in Section 7 illustrates an implementation of theEvent Handlerbase class interface that contains a single method,calledhandle_event,which is used by theInitiation Dispatcherto dispatch events. In this case,the type of the event that has occurred is passed as a parameter to the method.

The following C++ abstract base class illustrates the single-method interface:

Event_Handler
    //      Abstract base class that serves as the
//      target of the Initiation_Dispatcher.
// Hook method that is called back by the
// Initiation_Dispatcher to handle events.
    virtual int handle_event (Event_Type et) 0;

    // Hook method that returns the underlying
// I/O Handle.
virtual Handle get_handle (void) const 0;
};

The advantage of the single-method interface is that it is possible to add new types of events without changing the interface. However,this approach encourages the use of switch statements in the subclass’shandle_eventmethod,which limits its extensibility.

A multi-method interface: Another way to implement theEvent Handlerinterface is to define separate virtual hook methods for each type of event (such ashandle_input,handle_output,orhandle_timeout).

The following C++ abstract base class illustrates the single-method interface:

Event_Handler
{
// Hook methods that are called back by
// the Initiation_Dispatcher to handle
// particular types of events.
int handle_accept (void) 0;
    int handle_input (int handle_output (int handle_timeout (int handle_close (0;
};

The benefit of the multi-method interface is that it is easy to selectively override methods in the base class and avoid further demultiplexing,viaswitchor if statements,in the hook method. However,it requires the framework developer to anticipate the set ofEvent Handlermethods in advance. For instance,the varioushandle_*methods in theEvent_Handlerinterface above are tailored for I/O events available through the UNIXselectmechanism. However,this interface is not broad enough to encompass all the types of events handled via the Win32WaitForMultipleObjectsmechanism[6].

Both approaches described above are examples of the hook method pattern described in[3]and the Factory Callback pattern described in[7]. The intent of these patterns is to provide well-defined hooks that can be specialized by applications and called back by lower-level dispatching code.

9.5 Determine the Number of Initiation Dispatchers in an Application

Many applications can be structured using just one instance of the Reactor pattern. In this case,'Courier New'">Initiation Dispatchercan be implemented as a Singleton[5]. This design is useful for centralizing event demultiplexing and dispatching into a single location within an application.

However,some operating systems limit the number of Handles that can be waited for within a single thread of control. For instance,Win32 allowsselectandWaitForMultipleObjectsto wait for no more than 64Handlesin a single thread. In this case,it may be necessary to create multiple threads,each of which runs its own instance of the Reactor pattern.

Note thatEvent Handlersare only serialized within an instance of the Reactor pattern. Therefore,multipleEvent Handlersin multiple threads can run in parallel. This configurationmay necessitate the use of additional synchronization mechanisms ifEvent Handlersin different threads access shared state.

9.6 Implement the Concrete Event Handlers

The concrete event handlers are typically created by application developers to perform specific services in response to particular events. The developers must determine what processing to perform when the corresponding hook method is invoked by the initiation dispatcher.

The following code implements theConcrete Event Handlersfor the logging server described in Section 3. These handlers provide passive connection establishment (Logging Acceptor) and data reception (Logging Handler).

The Logging Acceptor class: This class is an example of theAcceptorcomponent of the Acceptor-Connector pattern[8]. The Acceptor-Connector pattern decouples the task of service initialization from the tasks performed after a service is initialized. This pattern enables the applicationspecific portion of a service,such as theLogging Handler,to vary independently of the mechanism used to establish the connection.

ALogging Acceptorpassively accepts connections from client applications and creates client-specificLogging Handlerobjects,which receive and process logging records from clients. The key methods and data members in theLogging Acceptorclass are defined below:

Logging_Acceptor : public Event_Handler
    //      Handles client connection requests.
// Initialize the acceptor_ endpoint and
// register with the Initiation Dispatcher.
    Logging_Acceptor (const INET_Addr &addr);

    // Factory method that accepts a new
// SOCK_Stream connection and creates a
// Logging_Handler object to handle logging
// records sent using the connection.
void handle_event (Event_Type et);

    // Get the I/O Handle (called by the
// Initiation Dispatcher when
// Logging_Acceptor is registered).
virtual HANDLE get_handle (const
    {
        return acceptor_.get_handle ();
    }

private// Socket factory that accepts client
// connections.
    SOCK_Acceptor acceptor_;
};

TheLogging Acceptorclass inherits from theEvent Handlerbase class. This enables an application to register theLogging Acceptorwith anInitiation Dispatcher.

TheLogging Acceptoralso contains an instance ofSOCK Acceptor. This is a concrete factory that enables theLogging Acceptorto accept connection requests on a passive mode socket that is listening to a communication port. When a connection arrives from a client,'Courier New'">SOCK Acceptoraccepts the connection and produces aSOCK Streamobject. Henceforth,'Courier New'">SOCK Streamobject is used to transfer data reliably between the client and the logging server.

TheSOCK AcceptorandSOCK Streamclasses used to implement the logging server are part of the C++ socket wrapper library provided by ACE[9]. These socket wrappers encapsulate theSOCK Streamsemantics of the socket interface within a portable and type-secure object-oriented interface. In the Internet domain,'Courier New'">SOCK Streamsockets are implemented using TCP.

The constructor for theLogging Acceptorregisters itself with theInitiation DispatcherSingleton[5]forACCEPTevents,as follows:

Logging_Acceptor::Logging_Acceptor (&addr)
    : acceptor_ (addr)
{
    // Register acceptor with the Initiation
// Dispatcher,which "double dispatches"
// the Logging_Acceptor::get_handle() method
// to obtain the HANDLE.
    Initiation_Dispatcher::instance ()->
        register_handler (this, ACCEPT_EVENT);
}

Henceforth,whenever a client connection arrives,'Courier New'">Logging Acceptor'svoid Logging_Acceptor::handle_event (Event_Type et) { // Can only be called for an ACCEPT event. assert (et == ACCEPT_EVENT); SOCK_Stream new_connection; // Accept the connection. acceptor_.accept (new_connection); // Create a new Logging Handler. Logging_Handler *handler = new Logging_Handler (new_connection); }

Thehandle_eventmethod invokes theacceptmethod of theSOCK Acceptorto passively establish aSOCK Stream. Once theSOCK Streamis connected with the new client,aLogging Handleris allocated dynamically to process the logging requests. As shown below,'Courier New'">Logging Handlerregisters itself with theThe Logging Handler class: The logging server uses theLogging Handlerclass shown below to receive logging records sent by client applications:

Logging_Handler //      Receive and process logging records
//      sent by a client application.
// Initialize the client stream.
    Logging_Handler (SOCK_Stream &cs);

    // Hook method that handles the reception
// of logging records from clients.
// Logging_Handler is registered).
return peer_stream_.get_handle ();
    }

// Receives logging records from a client.
    SOCK_Stream peer_stream_;
};

Once it’s created,'Courier New'">Logging Handlerregisters itself forREADevents with theInitiation DispatcherSingleton. Henceforth,when a logging record arrives,'Courier New'">Initiation Dispatcherautomatically dispatches thehandle_eventmethod of the associatedvoid Logging_Handler::handle_event (Event_Type et) { if (et == READ_EVENT) { Log_Record log_record; peer_stream_.recv ((void *) log_record, sizeof log_record); // Write logging record to standard output. log_record.write (STDOUT); } else == CLOSE_EVENT) { peer_stream_.close (); delete (*) this; } }

When aREADevent occurs on a socketHandle,'Courier New'">handle_eventmethod of theLogging Handler. This method receives,processes,and writes the logging record to the standard output (STDOUT). Likewise,when the client closes down the connection theInitiation Dispatcherpasses aCLOSEevent,which informs theLogging Handlerto shut down itsSOCK Streamand delete itself.

9.7 Implement the Server

The logging server contains a singlemainfunction.

The logging server main function: This function implements a single-threaded,concurrent logging server that waits in theInitiation Dispatcher'shandle_eventsevent loop. As requests arrive from clients,'Courier New'">Initiation Dispatcherinvokes the appropriateConcrete Event Handlerhook methods,which accept connections and receive and process logging records. The main entry point into the logging server is defined as follows:

// Server port number.
const u_short PORT 10000;

int
main (void)
{
    // Logging server port number.
    INET_Addr server_addr (PORT);

    // Initialize logging server endpoint and
// register with the Initiation_Dispatcher.
    Logging_Acceptor la (server_addr);

    // Main event loop that handles client
// logging records and connection requests.
for (;;)
        Initiation_Dispatcher->handle_events ();

    /* NOTREACHED */
    return 0;
}

The main program creates aLogging Acceptor,whose constructor initializes it with the port number of the logging server. The program then enters its main event-loop. Subsequently,'Courier New'">Initiation DispatcherSingleton uses theselectevent demultiplexing system call to synchronously wait for connection requests and logging records to arrive from clients.

The following interaction diagram illustrates the collaboration between the objects participating in the logging server example:

Once theInitiation Dispatcherobject is initialized,it becomes the primary focus of the control flow within the logging server. All subsequent activity is triggered by hook methods on theLogging AcceptorandLogging Handlerobjects registered with,and controlled by,'Courier New'">Initiation Dispatcher.

When a connection request arrives on the network connection,'Courier New'">Initiation Dispatchercalls back theLogging Handler. ThisLogging Handlerthen registers with theInitiation DispatcherforREADevents. Thus,when a client sends a logging record,'Courier New'">Initiation Dispatchercalls back to the client’sLogging Handlerto process the incoming record from that client connection in the logging server’s single thread of control.

11.1 Benefits

The Reactor pattern offers the following benefits:

Separation of concerns: The Reactor pattern decouples application-independent demultiplexing and dispatching mechanisms from application-specific hook method functionality. The application-independent mechanisms become reusable components that know how to demultiplex events and dispatch the appropriate hook methods defined byEvent Handlers. In contrast,the application-specific functionality in a hook method knows how to perform a particular type of service.

Improve modularity,reusability,and configurability of event-driven applications: The pattern decouples application functionality into separate classes. For instance,there are two separate classes in the logging server: one for establishing connections and another for receiving and processing logging records. This decoupling enables the reuse of the connection establishment class for different types of connection-oriented services (such as file transfer,remote login,and video-on-demand). Therefore,modifying or extending the functionality of the logging server only affects the implementation of the logging handler class.

Improves application portability: TheInitiation Dispatcher's interface can be reused independently of the OS system calls that perform event demultiplexing. These system calls detect and report the occurrence of one or more events that may occur simultaneously on multiple sources of events. Common sources of events may include I/O handles,and synchronization objects. On UNIX platforms,the event demultiplexing system calls are calledpoll[1]. In the Win32 API[16],'Courier New'">WaitForMultipleObjectssystem call performs event demultiplexing.

Provides coarse-grained concurrency control: The Reactor pattern serializes the invocation of event handlers at the level of event demultiplexing and dispatching within a process or thread. Serialization at theInitiation Dispatcherlevel often eliminates the need for more complicated synchronization or locking within an application process.

11.2 Liabilities

The Reactor pattern has the following liabilities:

Restricted applicability: The Reactor pattern can only be applied efficiently if the OS supportsHandles. It is possible to emulate the semantics of the Reactor pattern using multiple threads within theHandle. Whenever there are events available on a handle,its associated thread will read the event and place it on a queue that is processed sequentially by the initiation dispatcher. However,this design is typically very inefficient since it serializes allEvent Handlers,thereby increasing synchronization and context switching overhead without enhancing parallelism.

Non-preemptive: In a single-threaded application process,'Courier New'">Event Handlersare not preempted while they are executing. This implies that anEvent Handlershould not perform blocking I/O on an individualHandlesince this will block the entire process and impede the responsiveness for clients connected to otherHandles. Therefore,for long-duration operations,such as transferring multimegabyte medical images[15],the Active Object pattern[17]may be more effective. An Active Object uses multithreading or multi-processing to complete its tasks in parallel with theInitiation Dispatcher's main event-loop.

Hard to debug: Applications written with the Reactor pattern can be hard to debug since the inverted flow of control oscillates between the framework infrastructure and the method callbacks on application-specific handlers. This increases the difficulty of “single-stepping” through the runtime behavior of a framework within a debugger since application developers may not understand or have access to the framework code. This is similar to the problems encountered trying to debug a compiler lexical analyzer and parser written withLEXandYACC. In these applications,debugging is straightforward when the thread of control is within the user-defined action routines. Once the thread of control returns to the generated Deterministic Finite Automata (DFA) skeleton,it is hard to follow the program logic.