dispatcher

The class os_dispatcher builds upon the os_io_multiplexer class by implementing an event dispatching mechanism. An os_io_multiplexer object signals the handles that have a pending condition or an event (read, write, except, timeout). The os_dispatcher object demultiplexes these events to associated event handlers. The os_dispatcher class contains an event_t enumerator type which has four enumerators - read_event , write_event , except_event , and timeout_event for specifying handles to be monitored for read, write, exceptional, and timeout conditions. To monitor an event on a particular handle, a service handler is registered with the dispatcher object. The type of the service handler and its callback function can be specified to the register_handler() method.

The ServiceHandler , the first parameter, should be a class that has following public interface (not required but strongly suggested so that it can be used with the os_tcp_acceptor and os_tcp_connector classes).

• os_tcp_socket& tcp_socket() -Used by the os_tcp_connector object to establish a communication endpoint with the server application.
• void* run() -Called by the Executor object to initiate service requests for the server application.

Alternately, the ServiceHandler object could inherit from os_handler_stream class for the os_tcp_socket member data and os_tcp_socket& tcp_socket() member function, thereby not requiring to implement that functionality directly in its own class. The ServiceHandler object should delete itself in the callback function after it is done receiving the request from the server.

The handle event callback function, the third parameter, requires the following public interface.

• void (ServiceHandler::*)( os_sock_t ) -Invoked for the event notification.

Upon signaling of the event on the particular handle, the associated service handler's callback function is called to notify the occurrence of the event. The callback function should process the event and return control quickly. Since dispatching and event handling happens in a single thread of control time consuming event handler functions should be executed in a separate thread. Usually, a single instance of the os_dispatcher object can serve as a central event dispatcher for an application. The instance() static method creates a singleton dispatcher which gets deleted when the process ends.

The os_io_multiplexer class uses the select() library function to monitor the handles for events. Since the os_dispatcher class uses the os_io_multiplexer class in its implementation, only handles that are accepted by select() library function are allowed to be registered for event notification.

The os_tcp_acceptor , os_tcp_connector , and os_dispatcher classes can be collectively used to synchronously or asynchronously establish connections and perform service processing at the two connection endpoints.

This class is implemented based on the Reactor pattern described in the paper - "Reactor - An Object Behavioral Pattern for Demultiplexing and Dispatching Handles for Synchronous Events by Douglas C. Schmidt published in the book "Pattern Languages of Program Design", Addison-Wesley 1995.

Use of member template feature in the register handler method gives the flexibility of not having the handler classes to inherit from a specific interface class. Therefore, the compiler must be able to support member templates and OS_ENABLE_MEMBER_TEMPLATE_FEATURES must be defined to use this class.

Library

Framework<ToolKit>

Declaration

#include <ospace/framework/dispatcher.h>

class os_dispatcher

Enums

enum os_dispatcher::event_t
  {
  read_event,
  write_event,
  except_event,
  timeout_event,
  };

Typedefs

typedef map< os_sock_t, os_event_handler*, less< os_sock_t > > os_event_handler_map;

Interface

Throws: os_network_toolkit_error

Throws: os_network_toolkit_error