Yate: MessageDispatcher Class Reference

Yate

Public Member Functions | Protected Member Functions | Friends | List of all members
MessageDispatcher Class Reference

A message dispatching hub. More...

`#include <yatengine.h>`

Inheritance diagram for MessageDispatcher:

## Public Member Functions
| MessageDispatcher (const char *trackParam=0)
| ~MessageDispatcher ()
const String & | trackParam () const
bool | install (MessageHandler *handler)
bool | uninstall (MessageHandler *handler)
bool | dispatch (Message &msg)
bool | enqueue (Message *msg)
void | dequeue ()
bool | dequeueOne ()
void | warnTime (u_int64_t usec)
void | traceTime (bool on=false)
void | traceHandlerTime (bool on=false)
void | clear ()
bool | hasMessages () const
bool | hasHandlers () const
bool | hasHooks () const
unsigned int | messageCount ()
unsigned int | handlerCount ()
unsigned int | postHookCount ()
u_int64_t | enqueueCount () const
u_int64_t | dequeueCount () const
u_int64_t | dispatchCount () const
u_int64_t | queuedMax () const
u_int64_t | messageAge (bool usec=false) const
RWLock & | handlersLock ()
void | getStats (u_int64_t &enqueued, u_int64_t &dequeued, u_int64_t &dispatched, u_int64_t &queueMax)
bool | setHook (MessagePostHook *hook, bool remove=false)
unsigned int | fillHandlersInfo (bool matchName, const String &match, String *details=0, unsigned int *total=0)
Public Member Functions inherited from GenObject
| GenObject ()
virtual | ~GenObject ()
virtual bool | alive () const
virtual void | destruct ()
virtual const String & | toString () const
virtual const String & | traceId () const
virtual void * | getObject (const String &name) const
NamedCounter * | getObjCounter () const
NamedCounter * | setObjCounter (NamedCounter *counter)

## Protected Member Functions
void | trackParam (const char *paramName)

## Friends
class | Engine

## Additional Inherited Members
Static Public Member Functions inherited from GenObject
static void * | getObject (const String &name, const GenObject *obj)
static bool | getObjCounting ()
static void | setObjCounting (bool enable)
static NamedCounter * | getObjCounter (const String &name, bool create=true)
static ObjList & | getObjCounters ()

## Detailed Description

A message dispatching hub.

The dispatcher class is a hub that holds a list of handlers to be called for the messages that pass trough the hub. It can also handle a queue of messages that are typically dispatched by a separate thread.

## Constructor & Destructor Documentation

## ◆ MessageDispatcher()

MessageDispatcher | ( | const char * | trackParam = 0 | ) |

Creates a new message dispatcher.

Parameters

  trackParam | Name of the parameter used in tracking handlers

References trackParam().

## ◆ ~MessageDispatcher()

~MessageDispatcher | ( |  | ) |

Destroys the dispatcher and the installed handlers.

## Member Function Documentation

## ◆ clear()

void clear | ( |  | ) |

Clear all the message handlers and post-dispatch hooks

## ◆ dequeue()

void dequeue | ( |  | ) |

Dispatch all messages from the waiting queue

## ◆ dequeueCount()

u_int64_t dequeueCount | ( |  | ) | const
| inline

Get the total number of dequeued messages

Returns
  Count of dequeued messages

## ◆ dequeueOne()

bool dequeueOne | ( |  | ) |

Dispatch one message from the waiting queue

Returns
  True if success, false if the queue is empty

## ◆ dispatch()

bool dispatch | ( | Message & | msg | ) |

Synchronously dispatch a message to the installed handlers. Handlers matching the message name and filter parameter are called in their installed order (based on priority) until one returns true. If the message has the broadcast flag set all matching handlers are called and the return value is true if any handler returned true. Note that in some cases when a handler is removed from the list other handlers with equal priority may be called twice.

Parameters

  msg | The message to dispatch

Returns
  True if one handler accepted it, false if all ignored

## ◆ dispatchCount()

u_int64_t dispatchCount | ( |  | ) | const
| inline

Get the total number of dispatched messages

Returns
  Count of dispatched messages

## ◆ enqueue()

bool enqueue | ( | Message * | msg | ) |

Put a message in the waiting queue for asynchronous dispatching

Parameters

  msg | The message to enqueue, will be destroyed after dispatching

Returns
  True if successfully queued, false otherwise

## ◆ enqueueCount()

u_int64_t enqueueCount | ( |  | ) | const
| inline

Get the total number of enqueued messages

Returns
  Count of enqueued messages

## ◆ fillHandlersInfo()

unsigned int fillHandlersInfo | ( | bool | matchName,
|  | const String & | match,
|  | String * | details = 0,
|  | unsigned int * | total = 0 )

Fill handlers status info

Parameters

  matchName | True to match message name, false to match handler trackname
  match | Value to match. May be a regular expression
  details | Optional pointer to string to be filled with details
  total | Optional pointer to data to be filled with total number of handlers

Returns
  The number of matched handlers

## ◆ getStats()

void getStats | ( | u_int64_t & | enqueued,
|  | u_int64_t & | dequeued,
|  | u_int64_t & | dispatched,
|  | u_int64_t & | queueMax )

Retrieve all statistics counters

Parameters

  enqueued | Returns count of enqueued messages
  dequeued | Returns count of dequeued messages
  dispatched | Returns count of all dispatched messages, including dequeued ones
  queueMax | Returns queued high watermark

## ◆ handlerCount()

unsigned int handlerCount | ( |  | ) |

Get the number of handlers in this dispatcher

Returns
  Count of handlers

## ◆ handlersLock()

RWLock & handlersLock | ( |  | ) |
| inline

Retrieve the handlers list lock object

Returns
  Handlers list lock object reference

## ◆ hasHandlers()

bool hasHandlers | ( |  | ) | const
| inline

Check if there is at least one handler installed

Returns
  True if at least one handler is installed

## ◆ hasHooks()

bool hasHooks | ( |  | ) | const
| inline

Check if there is at least one message hook installed

Returns
  True if at least one hook is installed

## ◆ hasMessages()

bool hasMessages | ( |  | ) | const
| inline

Check if there is at least one message in the queue

Returns
  True if the queue holds at least one message

## ◆ install()

bool install | ( | MessageHandler * | handler | ) |

Installs a handler in the dispatcher. The handlers are installed in ascending order of their priorities. There is NO GUARANTEE on the order of handlers with equal priorities although for avoiding uncertainity such handlers are sorted by address.

Parameters

  handler | A pointer to the handler to install

Returns
  True on success, false on failure

## ◆ messageAge()

u_int64_t messageAge | ( | bool | usec = false | ) | const
| inline

Get the average dequeued message age in milliseconds or microseconds

Parameters

  usec | True to return microseconds instead of milliseconds

Returns
  Average age of dequeued messages

## ◆ messageCount()

unsigned int messageCount | ( |  | ) |

Get the number of messages waiting in the queue

Returns
  Count of messages in the queue

## ◆ postHookCount()

unsigned int postHookCount | ( |  | ) |

Get the number of post-handling hooks in this dispatcher

Returns
  Count of hooks

## ◆ queuedMax()

u_int64_t queuedMax | ( |  | ) | const
| inline

Get the queued messages high watermark

Returns
  Highest number of messages in queue

## ◆ setHook()

bool setHook | ( | MessagePostHook * | hook,
|  | bool | remove = false )

Install or remove a hook to catch messages after being dispatched

Parameters

  hook | Pointer to a post-dispatching message hook
  remove | Set to True to remove the hook instead of adding

Returns
  True on success, false on failure (may fail if already found in the list)

## ◆ traceHandlerTime()

void traceHandlerTime | ( | bool | on = false | ) |
| inline

Enable or disable message handler duration

Parameters

  on | True to enable, false to disable

## ◆ traceTime()

void traceTime | ( | bool | on = false | ) |
| inline

Enable or disable message events time (queued / dispatch)

Parameters

  on | True to enable, false to disable

## ◆ trackParam() [1/2]

const String & trackParam | ( |  | ) | const
| inline

Retrieve the tracker parameter name

Returns
  Name of the parameter used to track message dispatching

Referenced by MessageDispatcher().

## ◆ trackParam() [2/2]

void trackParam | ( | const char * | paramName | ) |
| inlineprotected

Set the tracked parameter name

Parameters

  paramName | Name of the parameter used in tracking handlers

## ◆ uninstall()

bool uninstall | ( | MessageHandler * | handler | ) |

Uninstalls a handler from the dispatcher.

Parameters

  handler | A pointer to the handler to uninstall

Returns
  True on success, false on failure

## ◆ warnTime()

void warnTime | ( | u_int64_t | usec | ) |
| inline

Set a limit to generate warning when a message took too long to dispatch

Parameters

  usec | Warning time limit in microseconds, zero to disable

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

- yatengine.h