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

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