MessageQueueBase Class Reference

Defines the interface for sending new shared memory regions between processes. More...

#include <MessageQueue.h>

Inheritance diagram for MessageQueueBase:

Detailed Description

Defines the interface for sending new shared memory regions between processes.

This base class holds all of the template-independent code to allow general operations on MessageQueues. The templated version of MessageQueue provides concrete implementation, which is what you would instantiate.

Each message entails its own shared memory region, as compared to SharedQueue, where a single large buffer is maintained, and all messages are copied into the common buffer. This class is better for large regions since it can avoid copying data around.

See also:: MessageQueue, MessageQueueStatusListener, MessageReceiver

Definition at line 32 of file MessageQueue.h.

List of all members.

Classes
class	MessageFilter
	an interface for filtering (or otherwise monitoring) messages being sent through a MessageQueue, see MessageQueueBase::addMessageFilter() More...
Public Types
enum	OverflowPolicy_t { DROP_OLDEST, DROP_NEWEST, WAIT, THROW_BAD_ALLOC }
	an enumerations of policies for dealing with overflow, pass to setOverflowPolicy() More...
typedef unsigned short	index_t
	The storage type for message entry indicies.
typedef MarkScope	AutoLock
	a typedef to make it easier to obtain a lock on the queue for the extent of a scope
Public Member Functions
	MessageQueueBase ()
	constructor
virtual	~MessageQueueBase ()
	destructor
virtual SemaphoreManager::semid_t	addReceiver () ATTR_must_check=0
	add one to the receiver reference count
virtual void	removeReceiver (SemaphoreManager::semid_t rcvr)=0
	remove one from the receiver reference count
virtual unsigned int	getNumReceivers () const
	return the receiver reference count
virtual SemaphoreManager::semid_t	addReadStatusListener () ATTR_must_check=0
	registers a semaphore which should be raised whenever a message is marked read
virtual void	removeReadStatusListener (SemaphoreManager::semid_t sem)=0
	removes a semaphore from the status listener list
virtual void	sendMessage (RCRegion *rcr, bool autoDereference=false)=0
	post a message into the queue -- a shared reference is added, the caller retains control current reference
virtual RCRegion *	readMessage (index_t msg, SemaphoreManager::semid_t rcvr)=0
	request access to a particular message, increments read counter -- do not call more than once per receiver!
virtual RCRegion *	peekMessage (index_t msg)=0
	request access to a particular message, does not mark message -- call as often as you like
virtual void	markRead (index_t msg, SemaphoreManager::semid_t rcvr)=0
	increments read counter -- do not call more than once per receiver per message!
virtual void	close ()
	do not allow any new messages to be posted
virtual void	setReportDroppings (bool report)
	sets reportDroppings
virtual bool	getReportDroppings () const
	gets reportDroppings
virtual unsigned int	getMessageSN (index_t msg)=0
	Each message gets a unique, monotonically increasing serial number; this function returns that number (MessageQueue::serialNumber).
virtual unsigned int	getMessagesRead ()
	Checks to see how many messages have been processed (read by all receivers and removed from queue).
virtual unsigned int	getMessagesSent ()
	Returns the number of messages which have been sent.
virtual unsigned int	getMessagesUnread ()
	Returns the number of messages which have been sent but not yet read.
MutexLock < ProcessID::NumProcesses > &	getLock () const
	returns a reference to the queue's inter-process lock
virtual index_t	oldest () const =0
	return oldest message still in the queue (may or may not have been read by this process)
virtual index_t	newer (index_t it) const =0
	return the next message in the queue (may or may not have been read by this process)
virtual index_t	older (index_t it) const =0
	return the previous message in the queue (may or may not have been read by this process)
virtual index_t	newest () const =0
	return most recent message added to the queue (may or may not have been read by this process)
virtual bool	isEnd (index_t it) const =0
	returns true if it is the one-past-the-end of the queue
void	setOverflowPolicy (OverflowPolicy_t op)
	allows you to pick how to handle running out of space in the queue, see OverflowPolicy_t
OverflowPolicy_t	getOverflowPolicy () const
	returns the current overflow policy, see OverflowPolicy_t
void	addMessageFilter (MessageFilter &filter)
	once called, any messages put into the queue must pass through filter first (note: there can only be one filter per process!)
void	removeMessageFilter ()
	removes the current filter in place, if any
Static Public Member Functions
static void	setSemaphoreManager (SemaphoreManager *mgr)
	sets semgr
static SemaphoreManager *	getSemaphoreManager ()
	gets semgr
Protected Attributes
MutexLock < ProcessID::NumProcesses >	lock
	a lock to grant serial access to the queue
volatile OverflowPolicy_t	overflowPolicy
	the choice of how to handle message overflow -- see OverflowPolicy_t
bool	isClosed
	if true, new messages will be rejected
bool	reportDroppings
	if true, output will be sent on cerr when overflow occurs
unsigned int	numMessages
	number of messages which have been sent (serial number of next message)
unsigned int	numReceivers
	how many receivers to expect
unsigned int	messagesRead
	number of messages which have been read and removed from queue
MessageFilter *	filters [ProcessID::NumProcesses]
	provides storage of one message filter per process
Static Protected Attributes
static SemaphoreManager *	semgr = NULL
	the global semaphore manager, needs to be set (once, globally) via setSemaphoreManager() before any receivers are added
Private Member Functions
	MessageQueueBase (const MessageQueueBase &)
	this shouldn't be called...
MessageQueueBase &	operator= (const MessageQueueBase &)
	this shouldn't be called...

Member Typedef Documentation

typedef MarkScope MessageQueueBase::AutoLock

a typedef to make it easier to obtain a lock on the queue for the extent of a scope

Definition at line 128 of file MessageQueue.h.

typedef unsigned short MessageQueueBase::index_t

The storage type for message entry indicies.

This index is to be used with accessor functions, but may be recycled for a new message after all receivers have read the previous message. If you wish to have a unique message identifier, see getMessageSN()

Definition at line 60 of file MessageQueue.h.

Member Enumeration Documentation

enum MessageQueueBase::OverflowPolicy_t

an enumerations of policies for dealing with overflow, pass to setOverflowPolicy()

Enumerator:

DROP_OLDEST	the oldest unread message is dropped
DROP_NEWEST	the most recently added message is dropped (i.e. the overflowing message is ignored)
WAIT	the adding process/thread polls until space is available
THROW_BAD_ALLOC	throw a std::bad_alloc exception (falls through to abort() if you don't catch it)

Definition at line 140 of file MessageQueue.h.

Constructor & Destructor Documentation

MessageQueueBase::MessageQueueBase ( )

constructor

Definition at line 45 of file MessageQueue.h.

virtual MessageQueueBase::~MessageQueueBase ( ) [virtual]

destructor

Definition at line 53 of file MessageQueue.h.

MessageQueueBase::MessageQueueBase ( const MessageQueueBase & ) [private]

this shouldn't be called...

Member Function Documentation

void MessageQueueBase::addMessageFilter ( MessageFilter & filter )

once called, any messages put into the queue must pass through filter first (note: there can only be one filter per process!)

if a filter was previously registered, it is replaced with the new filter

Definition at line 158 of file MessageQueue.h.

virtual SemaphoreManager::semid_t MessageQueueBase::addReadStatusListener ( ) [pure virtual]

registers a semaphore which should be raised whenever a message is marked read

The number of these are limited to the MAX_SENDERS template parameter of MessageQueue... returns false if too many are already registered

You probably don't want to call this directly, use a MessageQueueStatusThread

Implemented in MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >.

Referenced by MessageQueueStatusThread::addStatusListener().

virtual SemaphoreManager::semid_t MessageQueueBase::addReceiver ( ) [pure virtual]

add one to the receiver reference count

Implemented in MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >.

Referenced by MessageReceiver::launched(), and MessageReceiver::MessageReceiver().

virtual void MessageQueueBase::close ( ) [virtual]

do not allow any new messages to be posted

Definition at line 107 of file MessageQueue.h.

MutexLock<ProcessID::NumProcesses>& MessageQueueBase::getLock ( ) const

returns a reference to the queue's inter-process lock

Definition at line 130 of file MessageQueue.h.

Referenced by MessageReceiver::getNextMessage(), and MessageReceiver::peekNextMessage().

virtual unsigned int MessageQueueBase::getMessageSN ( index_t msg ) [pure virtual]

Each message gets a unique, monotonically increasing serial number; this function returns that number (MessageQueue::serialNumber).

Implemented in MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >.

Referenced by MessageReceiver::findCurrentMessage(), MessageReceiver::getNextMessage(), MessageReceiver::markRead(), IPCEventTranslator::post(), and MessageReceiver::processNextMessage().

virtual unsigned int MessageQueueBase::getMessagesRead ( ) [virtual]

Checks to see how many messages have been processed (read by all receivers and removed from queue).

Definition at line 119 of file MessageQueue.h.

Referenced by MessageQueueStatusThread::addStatusListener(), getMessagesUnread(), IPCEventTranslator::post(), and MessageQueueStatusThread::run().

virtual unsigned int MessageQueueBase::getMessagesSent ( ) [virtual]

Returns the number of messages which have been sent.

Definition at line 122 of file MessageQueue.h.

Referenced by getMessagesUnread().

virtual unsigned int MessageQueueBase::getMessagesUnread ( ) [virtual]

Returns the number of messages which have been sent but not yet read.

Definition at line 125 of file MessageQueue.h.

virtual unsigned int MessageQueueBase::getNumReceivers ( ) const [virtual]

return the receiver reference count

Definition at line 68 of file MessageQueue.h.

OverflowPolicy_t MessageQueueBase::getOverflowPolicy ( ) const

returns the current overflow policy, see OverflowPolicy_t

Definition at line 149 of file MessageQueue.h.

virtual bool MessageQueueBase::getReportDroppings ( ) const [virtual]

gets reportDroppings

Definition at line 112 of file MessageQueue.h.

static SemaphoreManager* MessageQueueBase::getSemaphoreManager ( ) [static]

gets semgr

Definition at line 154 of file MessageQueue.h.

Referenced by MessageQueueStatusThread::addStatusListener(), MessageQueueStatusThread::cancelled(), MessageReceiver::finish(), MessageReceiver::launched(), MessageReceiver::markRead(), MessageReceiver::MessageReceiver(), MessageQueueStatusThread::run(), MessageReceiver::runloop(), MessageReceiver::stop(), MessageQueueStatusThread::stop(), MessageReceiver::waitNextMessage(), and MessageReceiver::~MessageReceiver().

virtual bool MessageQueueBase::isEnd ( index_t it ) const [pure virtual]

returns true if it is the one-past-the-end of the queue

Implemented in MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >.

Referenced by MessageReceiver::findCurrentMessage(), MessageReceiver::getNextMessage(), MessageReceiver::markRead(), and MessageReceiver::peekNextMessage().

virtual void MessageQueueBase::markRead	(	index_t	msg,
		SemaphoreManager::semid_t	rcvr
	)			`[pure virtual]`

increments read counter -- do not call more than once per receiver per message!

Implemented in MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >.

Referenced by MessageReceiver::markRead().

virtual index_t MessageQueueBase::newer ( index_t it ) const [pure virtual]

return the next message in the queue (may or may not have been read by this process)

Implemented in MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >.

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

virtual index_t MessageQueueBase::newest ( ) const [pure virtual]

return most recent message added to the queue (may or may not have been read by this process)

Implemented in MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >.

Referenced by MessageReceiver::findCurrentMessage(), and IPCEventTranslator::post().

virtual index_t MessageQueueBase::older ( index_t it ) const [pure virtual]

return the previous message in the queue (may or may not have been read by this process)

Implemented in MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >.

Referenced by MessageReceiver::findCurrentMessage().

virtual index_t MessageQueueBase::oldest ( ) const [pure virtual]

return oldest message still in the queue (may or may not have been read by this process)

Implemented in MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >.

MessageQueueBase& MessageQueueBase::operator= ( const MessageQueueBase & ) [private]

this shouldn't be called...

virtual RCRegion* MessageQueueBase::peekMessage ( index_t msg ) [pure virtual]

request access to a particular message, does not mark message -- call as often as you like

The caller inherits a reference to the returned region -- call removeReference when you are done with it

Implemented in MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >.

Referenced by MessageReceiver::peekNextMessage().

virtual RCRegion* MessageQueueBase::readMessage	(	index_t	msg,
		SemaphoreManager::semid_t	rcvr
	)			`[pure virtual]`

request access to a particular message, increments read counter -- do not call more than once per receiver!

The message is marked read and will be popped from the queue if all receivers have read the message as well. The caller inherits a reference to the returned region -- call removeReference when you are done with it

Implemented in MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >.

Referenced by MessageReceiver::getNextMessage().

void MessageQueueBase::removeMessageFilter ( )

removes the current filter in place, if any

Definition at line 162 of file MessageQueue.h.

virtual void MessageQueueBase::removeReadStatusListener ( SemaphoreManager::semid_t sem ) [pure virtual]

removes a semaphore from the status listener list

Implemented in MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >.

Referenced by MessageQueueStatusThread::cancelled().

virtual void MessageQueueBase::removeReceiver ( SemaphoreManager::semid_t rcvr ) [pure virtual]

remove one from the receiver reference count

Implemented in MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >.

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

virtual void MessageQueueBase::sendMessage	(	RCRegion *	rcr,
		bool	autoDereference = `false`
	)			`[pure virtual]`

post a message into the queue -- a shared reference is added, the caller retains control current reference

Thus, if you are sending a region and do not intend to use it again, either pass true for autoDereference or call RCRegion::removeReference() after sending to free the sender's memory.

If no one dereferences the region, you can continue to access the region, even as the receiver accesses it as well. Thus if both sides retain references, you can use the region as a shared memory area for future communication. (beware of race conditions!)

If rcr is NULL, an empty message will be sent (there's still some overhead to this -- may want to consider a semaphore instead of a MessageQueue if all you're going to do is 'ping' another process with empty messages)

Implemented in MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >.

Referenced by MotionManager::doAddMotion(), SoundManager::loadBuffer(), SoundManager::play(), IPCEventTranslator::post(), SoundManager::release(), MotionManager::removeMotion(), and SoundManager::resumePlay().

void MessageQueueBase::setOverflowPolicy ( OverflowPolicy_t op )

allows you to pick how to handle running out of space in the queue, see OverflowPolicy_t

Definition at line 147 of file MessageQueue.h.

virtual void MessageQueueBase::setReportDroppings ( bool report ) [virtual]

sets reportDroppings

Definition at line 110 of file MessageQueue.h.

static void MessageQueueBase::setSemaphoreManager ( SemaphoreManager * mgr ) [static]

sets semgr

Definition at line 152 of file MessageQueue.h.