# class MessageDispatcher | A message dispatching hub. More...
Full name | `TelEngine::MessageDispatcher`
Definition | `#include <yatengine.h>`
Inherits | TelEngine::GenObject [public ], TelEngine::Mutex [public ]
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

#### Public Methods

- MessageDispatcher (const char* trackParam = 0)
- ~MessageDispatcher ()
- inline const String& trackParam () const
- bool install (MessageHandler* handler)
- bool uninstall (MessageHandler* handler)
- bool dispatch (Message& msg)
- bool enqueue (Message* msg)
- void dequeue ()
- bool dequeueOne ()
- inline void warnTime (u_int64_t usec)
- inline void clear ()
- unsigned int messageCount ()
- unsigned int handlerCount ()
- void setHook (MessagePostHook* hook, bool remove = false)

#### Protected Methods

- inline void trackParam (const char* paramName)

## Detailed Description

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.

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

Creates a new message dispatcher.

Parameters:

trackParam | Name of the parameter used in tracking handlers

~MessageDispatcher () | ### ~MessageDispatcher

Destroys the dispatcher and the installed handlers.

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

[const]

Retrieve the tracker parameter name

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

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

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

Uninstalls a handler from the dispatcher.

Parameters:

handler | A pointer to the handler to uninstall

Returns: True on success, false on failure

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

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

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

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

void dequeue () | ### dequeue

Dispatch all messages from the waiting queue

bool dequeueOne () | ### dequeueOne

Dispatch one message from the waiting queue

Returns: True if success, false if the queue is empty

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

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

Parameters:

usec | Warning time limit in microseconds, zero to disable

inline void clear () | ### clear

Clear all the message handlers and post-dispatch hooks

unsigned int messageCount () | ### messageCount

Get the number of messages waiting in the queue

Returns: Count of messages in the queue

unsigned int handlerCount () | ### handlerCount

Get the number of handlers in this dispatcher

Returns: Count of handlers

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

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

inline void trackParam (const char* paramName) | ### trackParam

[protected]

Set the tracked parameter name

Parameters:

paramName | Name of the parameter used in tracking handlers

Generated by: paulc on bussard on Fri Dec 21 16:28:34 2012, using kdoc 2.0a54.