Yate
MessageDispatcher Class Reference

A message dispatching hub. More...

#include <yatengine.h>

Inheritance diagram for MessageDispatcher:
GenObject

Public Member Functions

 MessageDispatcher (const char *trackParam=0)
 
 ~MessageDispatcher ()
 
const StringtrackParam () 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
 
RWLockhandlersLock ()
 
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 StringtoString () const
 
virtual const StringtraceId () const
 
virtual void * getObject (const String &name) const
 
NamedCountergetObjCounter () const
 
NamedCountersetObjCounter (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 NamedCountergetObjCounter (const String &name, bool create=true)
 
static ObjListgetObjCounters ()
 

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
trackParamName of the parameter used in tracking handlers

◆ ~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
msgThe 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
msgThe 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
matchNameTrue to match message name, false to match handler trackname
matchValue to match. May be a regular expression
detailsOptional pointer to string to be filled with details
totalOptional 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
enqueuedReturns count of enqueued messages
dequeuedReturns count of dequeued messages
dispatchedReturns count of all dispatched messages, including dequeued ones
queueMaxReturns queued high watermark

Referenced by Engine::getStats().

◆ handlerCount()

unsigned int handlerCount ( )

Get the number of handlers in this dispatcher

Returns
Count of handlers

Referenced by Engine::handlerCount().

◆ 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

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

◆ hasHooks()

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().

◆ 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

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

◆ 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
handlerA 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
usecTrue to return microseconds instead of milliseconds
Returns
Average age of dequeued messages

Referenced by Engine::messageAge().

◆ messageCount()

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().

◆ postHookCount()

unsigned int postHookCount ( )

Get the number of post-handling hooks in this dispatcher

Returns
Count of hooks

Referenced by Engine::postHookCount().

◆ 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
hookPointer to a post-dispatching message hook
removeSet to True to remove the hook instead of adding
Returns
True on success, false on failure (may fail if already found in the list)

Referenced by Engine::setHook().

◆ traceHandlerTime()

void traceHandlerTime ( bool on = false)
inline

Enable or disable message handler duration

Parameters
onTrue to enable, false to disable

◆ traceTime()

void traceTime ( bool on = false)
inline

Enable or disable message events time (queued / dispatch)

Parameters
onTrue 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 Engine::trackParam().

◆ trackParam() [2/2]

void trackParam ( const char * paramName)
inlineprotected

Set the tracked parameter name

Parameters
paramNameName of the parameter used in tracking handlers

◆ uninstall()

bool uninstall ( MessageHandler * handler)

Uninstalls a handler from the dispatcher.

Parameters
handlerA 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
usecWarning time limit in microseconds, zero to disable

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