Yate: MessageDispatcher Class Reference

Yate

- Main Page
- Namespaces
- Classes
- Files

- Class List
- Class Hierarchy
- Class Members

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 | 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
void | getStats (u_int64_t &enqueued, u_int64_t &dequeued, u_int64_t &dispatched, u_int64_t &queueMax)
void | setHook (MessagePostHook *hook, bool remove=false)
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)
Public Member Functions inherited from Mutex
| Mutex (bool recursive=false, const char *name=0)
| Mutex (const Mutex &original)
| ~Mutex ()
Mutex & | operator= (const Mutex &original)
virtual bool | lock (long maxwait=-1)
virtual bool | unlock ()
virtual bool | locked () const
const char * | owner () const
bool | recursive () const
Public Member Functions inherited from Lockable
virtual | ~Lockable ()
virtual bool | check (long maxwait=-1)
virtual bool | unlockAll ()

## 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 ()
Static Public Member Functions inherited from Mutex
static int | count ()
static int | locks ()
static bool | efficientTimedLock ()
Static Public Member Functions inherited from Lockable
static void | wait (unsigned long maxwait)
static unsigned long | wait ()
static void | startUsingNow ()
static void | enableSafety (bool safe=true)
static bool | safety ()

## 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 | ( | const char * | trackParam = `0` | ) |

Creates a new message dispatcher.

Parameters

  trackParam | Name of the parameter used in tracking handlers

~MessageDispatcher | ( |  | ) |

Destroys the dispatcher and the installed handlers.

## Member Function Documentation

void clear | ( |  | ) |
| inline

Clear all the message handlers and post-dispatch hooks

References ObjList::clear().

void dequeue | ( |  | ) |

Dispatch all messages from the waiting queue

u_int64_t dequeueCount | ( |  | ) | const
| inline

Get the total number of dequeued messages

Returns
  Count of dequeued messages

bool dequeueOne | ( |  | ) |

Dispatch one message from the waiting queue

Returns
  True if success, false if the queue is empty

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

u_int64_t dispatchCount | ( |  | ) | const
| inline

Get the total number of dispatched messages

Returns
  Count of dispatched messages

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

u_int64_t enqueueCount | ( |  | ) | const
| inline

Get the total number of enqueued messages

Returns
  Count of enqueued messages

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

Referenced by Engine::getStats().

unsigned int handlerCount | ( |  | ) |

Get the number of handlers in this dispatcher

Returns
  Count of handlers

Referenced by Engine::handlerCount().

bool hasHandlers | ( |  | ) | const
| inline

Check if there is at least one handler installed

Returns
  True if at least one handler is installed

References ObjList::get(), and ObjList::next().

bool hasHooks | ( |  | ) | const
| inline

Check if there is at least one message hook installed

Returns
  True if at least one hook is installed

References ObjList::get(), and ObjList::next().

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

References ObjList::get(), and ObjList::next().

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

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

Referenced by Engine::messageAge().

unsigned int messageCount | ( |  | ) |

Get the number of messages waiting in the queue

Returns
  Count of messages in the queue

Referenced by Engine::messageCount(), and Engine::resetMax().

unsigned int postHookCount | ( |  | ) |

Get the number of post-handling hooks in this dispatcher

Returns
  Count of hooks

Referenced by Engine::postHookCount().

u_int64_t queuedMax | ( |  | ) | const
| inline

Get the queued messages high watermark

Returns
  Highest number of messages in queue

void 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

Referenced by Engine::setHook().

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

Retrieve the tracker parameter name

Returns
  Name of the parameter used to track message dispatching

Referenced by Engine::trackParam().

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

Set the tracked parameter name

Parameters

  paramName | Name of the parameter used in tracking handlers

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

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