Tekkotsu Homepage
Demos
Overview
Downloads
Dev. Resources
Reference
Credits

MessageReceiver Class Reference

#include <MessageReceiver.h>

Inheritance diagram for MessageReceiver:

List of all members.


Detailed Description

Spawns a thread for monitoring a MessageQueue, calls a specified function when new messages are available.

Uses a semaphore which is raised by the MessageQueue itself when a new message is posted. This should have almost no overhead, and fairly low latency (at least, much lower latency than you would get by running multiple busy loops polling for new messages)

Keep in mind that the monitor runs in a separate thread, so you will need to consider mutex issues when the callback is executing.

Definition at line 19 of file MessageReceiver.h.


Public Member Functions

 MessageReceiver (MessageQueueBase &mq, bool(*callback)(RCRegion *)=NULL, bool startThread=true, bool subscribe=true)
 constructor, indicate the message queue, and optional callback function and whether to start the monitor right away
virtual ~MessageReceiver ()
 destructor, stops and joins thread
virtual RCRegionpeekNextMessage ()
 returns the next unread message without marking it read, or NULL if there are currently no more messages. MessageReceiver retains reference.
virtual RCRegiongetNextMessage ()
 returns the next unread message, marking it as read. Caller inherits reference, and should call RemoveReference when done.
void markRead ()
 marks the current message as read, and allows MessageQueue to process next unread message
virtual void stop ()
 thread control -- stop monitoring (can call start() later to resume)
virtual void finish ()
 thread control -- stop(), join(), and process any final messages in the queue; unsubscribes as a listener of the MessageQueue
virtual void setCallback (bool(*callback)(RCRegion *))
 allows you to change the callback function -- should be set before the thread is started (otherwise, why bother starting it?)

Protected Types

typedef MessageQueueBase::index_t index_t
 shorthand for the message id type

Protected Member Functions

virtual void findCurrentMessage ()
 sets curit to the oldest message which hasn't been marked read
virtual bool launched ()
 register as a listener with the queue, if we haven't already (retains listener status between stop/start)
virtual unsigned int runloop ()
 wait for a new message, and then process it
virtual bool waitNextMessage ()
 wait for semid to be raised to indicate a new message is in the queue (or at least, that it needs to be checked); returns false if interrupted
virtual bool processNextMessage ()
 gets the next message and processes it
virtual void markRead (bool checkNext)
 if checksNext is set, raises semid so that if additional messages came in while we were processing the current one, they will be picked up

Protected Attributes

MessageQueueBasequeue
 the MessageQueue being monitored
SemaphoreManager::semid_t semid
 the semaphore raised when the queue should be checked for new messages
unsigned int nextMessage
 the expected serial number of the next message to be sent
unsigned int lastProcessedMessage
 the serial number of the last received message
bool(* process )(RCRegion *)
 the client callback function
index_t curit
 the message id of the last received message (currently being processed)

Private Member Functions

 MessageReceiver (const MessageReceiver &r)
 don't call
MessageReceiveroperator= (const MessageReceiver &r)
 don't call

Member Typedef Documentation

shorthand for the message id type

Definition at line 47 of file MessageReceiver.h.


Constructor & Destructor Documentation

MessageReceiver::MessageReceiver ( MessageQueueBase mq,
bool(*)(RCRegion *)  callback = NULL,
bool  startThread = true,
bool  subscribe = true 
) [explicit]

constructor, indicate the message queue, and optional callback function and whether to start the monitor right away

Parameters:
mq is the message queue that the receiver will register with
callback is the function to call when messages are received
startThread controls whether the thread will be launched by the constructor
subscribe only applies if startThread is false, indicates whether the receiver should register as a listener even though the thread isn't checking (yet) This last parameter allows you to avoid missing messages that come in before you're ready to process them

Definition at line 9 of file MessageReceiver.cc.

MessageReceiver::~MessageReceiver (  )  [virtual]

destructor, stops and joins thread

Definition at line 23 of file MessageReceiver.cc.

MessageReceiver::MessageReceiver ( const MessageReceiver r  )  [private]

don't call


Member Function Documentation

RCRegion * MessageReceiver::peekNextMessage (  )  [virtual]

returns the next unread message without marking it read, or NULL if there are currently no more messages. MessageReceiver retains reference.

Definition at line 32 of file MessageReceiver.cc.

Referenced by processNextMessage().

RCRegion * MessageReceiver::getNextMessage (  )  [virtual]

returns the next unread message, marking it as read. Caller inherits reference, and should call RemoveReference when done.

Definition at line 40 of file MessageReceiver.cc.

void MessageReceiver::markRead (  )  [inline]

marks the current message as read, and allows MessageQueue to process next unread message

Definition at line 36 of file MessageReceiver.h.

Referenced by processNextMessage().

void MessageReceiver::stop (  )  [virtual]

thread control -- stop monitoring (can call start() later to resume)

Reimplemented from Thread.

Definition at line 50 of file MessageReceiver.cc.

Referenced by finish(), and ~MessageReceiver().

void MessageReceiver::finish (  )  [virtual]

thread control -- stop(), join(), and process any final messages in the queue; unsubscribes as a listener of the MessageQueue

Definition at line 67 of file MessageReceiver.cc.

Referenced by MotionManager::RemoveAccess().

virtual void MessageReceiver::setCallback ( bool(*)(RCRegion *)  callback  )  [inline, virtual]

allows you to change the callback function -- should be set before the thread is started (otherwise, why bother starting it?)

Definition at line 44 of file MessageReceiver.h.

void MessageReceiver::findCurrentMessage (  )  [protected, virtual]

sets curit to the oldest message which hasn't been marked read

Definition at line 55 of file MessageReceiver.cc.

Referenced by getNextMessage(), markRead(), and peekNextMessage().

bool MessageReceiver::launched (  )  [protected, virtual]

register as a listener with the queue, if we haven't already (retains listener status between stop/start)

Reimplemented from Thread.

Definition at line 80 of file MessageReceiver.cc.

unsigned int MessageReceiver::runloop (  )  [protected, virtual]

wait for a new message, and then process it

Reimplemented from Thread.

Definition at line 90 of file MessageReceiver.cc.

bool MessageReceiver::waitNextMessage (  )  [protected, virtual]

wait for semid to be raised to indicate a new message is in the queue (or at least, that it needs to be checked); returns false if interrupted

Definition at line 101 of file MessageReceiver.cc.

Referenced by runloop().

bool MessageReceiver::processNextMessage (  )  [protected, virtual]

gets the next message and processes it

Definition at line 105 of file MessageReceiver.cc.

Referenced by finish(), and runloop().

void MessageReceiver::markRead ( bool  checkNext  )  [protected, virtual]

if checksNext is set, raises semid so that if additional messages came in while we were processing the current one, they will be picked up

Definition at line 126 of file MessageReceiver.cc.

MessageReceiver& MessageReceiver::operator= ( const MessageReceiver r  )  [private]

don't call


Member Data Documentation

the semaphore raised when the queue should be checked for new messages

Definition at line 57 of file MessageReceiver.h.

Referenced by finish(), getNextMessage(), launched(), markRead(), MessageReceiver(), runloop(), stop(), waitNextMessage(), and ~MessageReceiver().

unsigned int MessageReceiver::nextMessage [protected]

the expected serial number of the next message to be sent

Definition at line 58 of file MessageReceiver.h.

Referenced by findCurrentMessage(), getNextMessage(), and markRead().

unsigned int MessageReceiver::lastProcessedMessage [protected]

the serial number of the last received message

Definition at line 59 of file MessageReceiver.h.

Referenced by processNextMessage().

bool(* MessageReceiver::process)(RCRegion *) [protected]

the client callback function

Referenced by processNextMessage(), and setCallback().

the message id of the last received message (currently being processed)

Definition at line 61 of file MessageReceiver.h.

Referenced by findCurrentMessage(), getNextMessage(), markRead(), peekNextMessage(), and processNextMessage().


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

Tekkotsu v4.0
Generated Thu Nov 22 00:58:32 2007 by Doxygen 1.5.4