---

SmartSockets::TipcDispatcher Class Reference

#include <tdisp.h>

List of all members.

Public Methods
	TipcDispatcher (T_IPC_DISPATCHER dispatcher, bool destroyFlag=false, bool isDetached=false) throw (TipcException)
	TipcDispatcher (bool isDetached=false) throw (TipcException)
virtual	~TipcDispatcher () throw ()
	operator T_IPC_DISPATCHER () const throw ()
bool	dispatch (real8 timeout=T_TIMEOUT_FOREVER) throw (TipcException)
bool	mainLoop (real8 timeout=T_TIMEOUT_FOREVER) throw (TipcException)
void	eventTraverse (TipcDispatcherTraverser *travObj) throw (TipcException)
MessageEvent *	createMsgTypeEvent (const TipcSrv &srv, const TipcMt &mt, MessageEventHandler *handlerObj) throw (TipcException)
MessageEvent *	createMsgSubjEvent (const TipcSrv &srv, const char *subject, MessageEventHandler *handlerObj) throw (TipcException)
TimerEvent *	createTimerEvent (real8 interval, TimerEventHandler *handlerObj) throw (TipcException)
ConnEvent *	createConnEvent (const TipcConn &connection, T_IO_CHECK_MODE checkMode, ConnEventHandler *handlerObj) throw (TipcException)
SocketEvent *	createSocketEvent (sock socketFd, T_IO_CHECK_MODE checkMode, SocketEventHandler *handlerObj) throw (TipcException)
UserEvent *	createUserEvent (void *data, UserEventHandler *handlerObj) throw (TipcException)
void	destroyEvent (TipcEvent *event) throw (TipcException)
void	addInboundConnection (const TipcSrv &srv) throw (TipcException)
void	removeInboundConnection (const TipcSrv &srv) throw (TipcException)

---

Detailed Description

The Dispatcher allows one to create events, and trigger the event handlers associated with them. Currently five types of events are supported:

• Timer events - make the dispatcher invoke TimerEventHandlers at a specific interval. All timers are repeating. To simulate a one-shot timer the associated callback function should be coded to remove the event.

• Socket events - make the dispatcher invoke SocketEventHandlers whenever there's data to be read or written from/to a socket. Socket events give programmers a very similar functionality to the C select() function with an object-oriented abstraction.

• Connection events - make the dispatcher invoke ConnectionEventHandlers for read or write availability on peer-to-peer connections.

• User events - make the dispatcher invoke UserEventHandlers. User events are only useful for dispatchers running in detatched mode. It allows users to invoke methods in the Dispatcher thread. When a user event is added to a dispatcher, it is immediately queued to be invoked. There is not a trigger per se for user events.

• Message events - make the dispatcher invoke MessageEventHandlers either based on a message type or on a subject. Message events provide the same functionality as process callbacks and subject callbacks in the TipcSrv class.

Message events and TipcSrv callbacks, as stated above, have overlap in functionality. Callbacks are useful for applications that only have a single or few connections to RTserver. It's not advisable to mix callbacks with events, as they are different paradigms of programming. If they are mixed, however, the dispatcher will actually invoke all TipcSrv callbacks before invoking the message event handlers associated with a connection.

If a programmer chooses to use callbacks rather than events, the dispatcher is still useful; it can be used to service the callbacks of different connections all within the same thread. In order to achieve this, a call to addInboundConnection() should be made.

Multiple dispatchers are allowed within a process. Any number of connections and events may be added to a dispatcher. A dispatcher is thread-safe and may be operated on from any thread.

---

Constructor & Destructor Documentation

SmartSockets::TipcDispatcher::TipcDispatcher (  T_IPC_DISPATCHER    dispatcher, bool    destroyFlag = false, bool    isDetached = false )  throw (TipcException) [inline]

Constructor compatible with the C API. Parameters: dispatcher  C structure destroyFlag  determines whether or not the destructor destroys the T_IPC_DISPATCHER C structure. isDetached  determines whether or not the dispatcher structure passed in is running in detatched mode. Exceptions: TipcDispatcherException  if the dispatcher structure is NULL.

SmartSockets::TipcDispatcher::TipcDispatcher (  bool    isDetached = false )  throw (TipcException) [inline]

Creates a dispatcher Parameters: detached  - determines whether or not the dispatcher starts processing events in a separate thread Exceptions: TipcDispatcher  exception if an error occurs creating the dispatcher object; it's important to note that an exception with the value T_ERR_VAL_INVALID is thrown if a detached dispatcher is started without calling Utilities::initThreads().

virtual SmartSockets::TipcDispatcher::~TipcDispatcher (    )  throw () [inline, virtual]

Destructor. Note that the destructor will destroy the C dispatcher structure unless the _destroyFlag is set to false.

---

Member Function Documentation

void SmartSockets::TipcDispatcher::addInboundConnection (  const TipcSrv &    srv )  throw (TipcException) [inline]

Adds a connection to the dispatcher. The connection added will behave as a source for messages. Messages coming from this connection will be read and processed by invoking the approriate connection callback (e.g. a ProcessCallback, a SubjectCallback, etc. Note that currently there's a limitation in the C API that enforces the fact that one connection can only belong to one dispatcher. Parameters: srv  TipcSrv connection object to be added. Exceptions: TipcDispatcherException  if the connection is already present or if there's a failure adding it to the dispatcher.

ConnEvent* SmartSockets::TipcDispatcher::createConnEvent (  const TipcConn &    connection, T_IO_CHECK_MODE    checkMode, ConnEventHandler *    handlerObj )  throw (TipcException) [inline]

Creates an event that will be triggered whenever there's data ready to be read or written to a TipcConn object. Note that unlike the Message events, there's no need to add a peer to peer connection to the dispatcher. Parameters: connection  the peer-to-peer object to be monitored for read or write events. checkMode  if set to T_IO_CHECK_READ, triggers the ConnEventHandler object if data is ready to be read from the connection; if set to T_IO_CHECK_WRITE, triggers the ConnEventHandler object if data is ready to be written to the connection. handlerObj  instance of a child class implementing a conn event handler method. See also: ConnEventHandler::Handler for more details on the signature of the conn event handler method.

MessageEvent* SmartSockets::TipcDispatcher::createMsgSubjEvent (  const TipcSrv &    srv, const char *    subject, MessageEventHandler *    handlerObj )  throw (TipcException) [inline]

Creates an event that will be triggered if a message that matches the given subject (wildcards will also work) reaches the given server connection. Note that in order for this event to be triggered, at least one Dispatcher in the process should have added the server connection to it; this can be done by calling the addInboundConnection() method. Note that there's currently a limitation in the C API that mandates that a server connection must be added to at most one dispatcher in the process. Parameters: srv  the server connection that will be receiving data. handlerObj  instance of a child class implementing a message handler method. See also: MessageEventHandler::Handler for more details on the signature of the message handler method.

MessageEvent* SmartSockets::TipcDispatcher::createMsgTypeEvent (  const TipcSrv &    srv, const TipcMt &    mt, MessageEventHandler *    handlerObj )  throw (TipcException) [inline]

Creates an event that will be triggered if a message matching the given type reaches the given server connection. Note that in order for this event to be triggered, at least one Dispatcher in the process should have added the server connection to it; this can be done by calling the addInboundConnection() method. Note that there's currently a limitation in the C API that mandates that a server connection must be added to at most one dispatcher in the process. Parameters: srv  the server connection that will be receiving data. mt  the message type selector that will determine when the event handler will be triggered. handlerObj  instance of a child class implementing a message handler method. handler; defaults to the MessageEventHandler::onMessage() method. See also: MessageEventHandler::Handler for more details on the signature of the message handler method.

SocketEvent* SmartSockets::TipcDispatcher::createSocketEvent (  sock    socketFd, T_IO_CHECK_MODE    checkMode, SocketEventHandler *    handlerObj )  throw (TipcException) [inline]

Creates an event that will be triggered whenever there's data ready to be read or written to a Socket. Note that unlike the Message events, there's no need to add a socket to the dispatcher. Parameters: socketFd  the file descriptor of the socket to be monitored for read or write events. checkMode  if set to T_IO_CHECK_READ, triggers the ConnEventHandler object if data is ready to be read from the socket; if set to T_IO_CHECK_WRITE, triggers the ConnEventHandler object if data is ready to be written to the socket. handlerObj  instance of a child class implementing a socket event handler method. See also: SocketEventHandler::Handler for more details on the signature of the socket event handler method.

TimerEvent* SmartSockets::TipcDispatcher::createTimerEvent (  real8    interval, TimerEventHandler *    handlerObj )  throw (TipcException) [inline]

Creates an event that will be periodically triggered every interval. number of seconds. To simulate a one time event, call the TipcEvent::destroy() method once the event has been triggered once. Parameters: interval  the number of seconds between events. handlerObj  instance of a child class implementing a timer event handler method. handlerMethod  method matching the function signature of the timer event handler; defaults to the TimerEventHandler::onTimer() method.

UserEvent* SmartSockets::TipcDispatcher::createUserEvent (  void *    data, UserEventHandler *    handlerObj )  throw (TipcException) [inline]

Creates an event that will be triggered immediately. User events are only useful for dispatchers running in detatched mode. It allows users to invoke methods in the Dispatcher thread. When a user event is added to a dispatcher, it is immediately queued to be invoked. There is not a trigger per se for user events. Parameters: data  to be retrieved in the UserEventHandler::Handler method. handlerObj  instance of a child class implementing a socket event handler method.

void SmartSockets::TipcDispatcher::destroyEvent (  TipcEvent *    event )  throw (TipcException) [inline]

Unregisters and destroys a event created by one the create methods.

bool SmartSockets::TipcDispatcher::dispatch (  real8    timeout = T_TIMEOUT_FOREVER )  throw (TipcException)

Dispatches one event if there aren't any events available, it waits timeout number of seconds for one. Parameters: timeout  number of seconds to wait for an event to be dispatched.

void SmartSockets::TipcDispatcher::eventTraverse (  TipcDispatcherTraverser *    travObj )  throw (TipcException)

Traverse the events waiting to be dispatched by the dispatcher. Parameters: travObj  traversal object derived from the TipcDispatcherTraverse parent class. Exceptions: TipcDispatcherException  if a NULL travObj is passed, or if an error occurs during the traversal process.

bool SmartSockets::TipcDispatcher::mainLoop (  real8    timeout = T_TIMEOUT_FOREVER )  throw (TipcException)

Dispatch events continuously for timeout seconds. Parameters: timeout  number of seconds to dispatch (defaults to infinite) Exceptions: TipcDispatcherException  if an error occurred dispatching an event.

SmartSockets::TipcDispatcher::operator T_IPC_DISPATCHER (    )  const throw () [inline]

Extracts underlying T_IPC_DISPATCHER handle.

void SmartSockets::TipcDispatcher::removeInboundConnection (  const TipcSrv &    srv )  throw (TipcException) [inline]

Removes a connection from the dispatcher. Parameters: srv  reference to the TipcSrv connection object to be removed. Exceptions: TipcDispatcher  exception if the server connection is not registered with this dispatcher, or if there's a failure in removing the connection.

---

The documentation for this class was generated from the following file:

• tdisp.h

---