Tekkotsu Homepage
Demos
Overview
Downloads
Dev. Resources
Reference
Credits

MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS > Class Template Reference

An implementation of MessageQueueBase, which provides mechanisms for sending shared memory regions between processes. More...

#include <MessageQueue.h>

Inheritance diagram for MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >:

Detailed Description

template<unsigned int MAX_UNREAD, unsigned int MAX_RECEIVERS = 10, unsigned int MAX_SENDERS = 10>
class MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >

An implementation of MessageQueueBase, which provides mechanisms for sending shared memory regions between processes.

MAX_UNREAD is assigned to CAPACITY, MAX_RECEIVERS is assigned to RECEIVER_CAPACITY, and MAX_SENDERS is assigned to SENDER_CAPACITY

See also:
MessageQueueBase, MessageQueueStatusListener, MessageReceiver

Definition at line 186 of file MessageQueue.h.

List of all members.

Classes

struct  entry
 data storage needed for each message More...

Public Member Functions

 MessageQueue ()
 constructor
virtual ~MessageQueue ()
 destructor
virtual SemaphoreManager::semid_t addReadStatusListener () ATTR_must_check
 registers a semaphore which should be raised whenever a message is marked read
virtual void removeReadStatusListener (SemaphoreManager::semid_t sem)
 removes a semaphore from the status listener list
virtual SemaphoreManager::semid_t addReceiver () ATTR_must_check
 add one to the receiver reference count
virtual void removeReceiver (SemaphoreManager::semid_t rcvr)
 remove one from the receiver reference count
virtual void sendMessage (RCRegion *rcr, bool autoDereference=false)
 post a message into the queue -- a shared reference is added, the caller retains control current reference
virtual RCRegionreadMessage (index_t msg, SemaphoreManager::semid_t rcvr)
 request access to a particular message, increments read counter -- do not call more than once per receiver!
virtual RCRegionpeekMessage (index_t msg)
 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)
 increments read counter -- do not call more than once per receiver per message!
virtual unsigned int getMessageSN (index_t msg)
 Each message gets a unique, monotonically increasing serial number; this function returns that number (MessageQueue::serialNumber).
virtual index_t oldest () const
 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
 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
 return the previous message in the queue (may or may not have been read by this process)
virtual index_t newest () const
 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
 returns true if it is the one-past-the-end of the queue

Static Public Attributes

static const unsigned int CAPACITY = MAX_UNREAD
 total number of messages which can be backed up in the queue
static const unsigned int RECEIVER_CAPACITY = MAX_RECEIVERS
 total number of receivers which can be registered
static const unsigned int SENDER_CAPACITY = MAX_SENDERS
 total number of senders which can be registered

Protected Types

typedef ListMemBuf< entry,
MAX_UNREAD, index_t
mq_t
 shorthand for the type of data storage of message entries
typedef ListMemBuf
< SemaphoreManager::semid_t,
MAX_RECEIVERS, index_t
rcvrs_t
 shorthand for the type of data storage of message entries
typedef ListMemBuf
< SemaphoreManager::semid_t,
MAX_SENDERS, index_t
sndrs_t
 shorthand for the type of data storage of message entries

Protected Member Functions

rcvrs_t::index_t lookupReceiver (SemaphoreManager::semid_t rcvr) const
 returns the index within rcvrs of the receiver id rcvr

Protected Attributes

mq_t mq
 the data storage of message entries
rcvrs_t rcvrs
 the data storage of receiver semaphores
sndrs_t sndrs
 the data storage of receiver semaphores

Member Typedef Documentation

template<unsigned int MAX_UNREAD, unsigned int MAX_RECEIVERS = 10, unsigned int MAX_SENDERS = 10>
typedef ListMemBuf<entry,MAX_UNREAD,index_t> MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::mq_t [protected]

shorthand for the type of data storage of message entries

Definition at line 236 of file MessageQueue.h.

template<unsigned int MAX_UNREAD, unsigned int MAX_RECEIVERS = 10, unsigned int MAX_SENDERS = 10>
typedef ListMemBuf<SemaphoreManager::semid_t,MAX_RECEIVERS,index_t> MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::rcvrs_t [protected]

shorthand for the type of data storage of message entries

Definition at line 241 of file MessageQueue.h.

template<unsigned int MAX_UNREAD, unsigned int MAX_RECEIVERS = 10, unsigned int MAX_SENDERS = 10>
typedef ListMemBuf<SemaphoreManager::semid_t,MAX_SENDERS,index_t> MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::sndrs_t [protected]

shorthand for the type of data storage of message entries

Definition at line 249 of file MessageQueue.h.


Constructor & Destructor Documentation

template<unsigned int MAX_UNREAD, unsigned int MAX_RECEIVERS = 10, unsigned int MAX_SENDERS = 10>
MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::MessageQueue (  ) 

constructor

Definition at line 199 of file MessageQueue.h.

template<unsigned int MAX_UNREAD, unsigned int MAX_RECEIVERS, unsigned int MAX_SENDERS>
MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::~MessageQueue (  )  [virtual]

destructor

Definition at line 255 of file MessageQueue.h.


Member Function Documentation

template<unsigned int MAX_UNREAD, unsigned int MAX_RECEIVERS, unsigned int MAX_SENDERS>
SemaphoreManager::semid_t MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::addReadStatusListener (  )  [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

Implements MessageQueueBase.

Definition at line 268 of file MessageQueue.h.

template<unsigned int MAX_UNREAD, unsigned int MAX_RECEIVERS, unsigned int MAX_SENDERS>
SemaphoreManager::semid_t MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::addReceiver (  )  [virtual]

add one to the receiver reference count

Implements MessageQueueBase.

Definition at line 295 of file MessageQueue.h.

template<unsigned int MAX_UNREAD, unsigned int MAX_RECEIVERS = 10, unsigned int MAX_SENDERS = 10>
virtual unsigned int MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::getMessageSN ( index_t  msg  )  [virtual]

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

Implements MessageQueueBase.

Definition at line 215 of file MessageQueue.h.

template<unsigned int MAX_UNREAD, unsigned int MAX_RECEIVERS = 10, unsigned int MAX_SENDERS = 10>
virtual bool MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::isEnd ( index_t  it  )  const [virtual]

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

Implements MessageQueueBase.

Definition at line 221 of file MessageQueue.h.

template<unsigned int MAX_UNREAD, unsigned int MAX_RECEIVERS, unsigned int MAX_SENDERS>
MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::rcvrs_t::index_t MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::lookupReceiver ( SemaphoreManager::semid_t  rcvr  )  const [protected]
template<unsigned int MAX_UNREAD, unsigned int MAX_RECEIVERS, unsigned int MAX_SENDERS>
void MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::markRead ( index_t  msg,
SemaphoreManager::semid_t  rcvr 
) [virtual]

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

Implements MessageQueueBase.

Definition at line 459 of file MessageQueue.h.

template<unsigned int MAX_UNREAD, unsigned int MAX_RECEIVERS = 10, unsigned int MAX_SENDERS = 10>
virtual index_t MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::newer ( index_t  it  )  const [virtual]

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

Implements MessageQueueBase.

Definition at line 218 of file MessageQueue.h.

template<unsigned int MAX_UNREAD, unsigned int MAX_RECEIVERS = 10, unsigned int MAX_SENDERS = 10>
virtual index_t MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::newest (  )  const [virtual]

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

Implements MessageQueueBase.

Definition at line 220 of file MessageQueue.h.

template<unsigned int MAX_UNREAD, unsigned int MAX_RECEIVERS = 10, unsigned int MAX_SENDERS = 10>
virtual index_t MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::older ( index_t  it  )  const [virtual]

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

Implements MessageQueueBase.

Definition at line 219 of file MessageQueue.h.

template<unsigned int MAX_UNREAD, unsigned int MAX_RECEIVERS = 10, unsigned int MAX_SENDERS = 10>
virtual index_t MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::oldest (  )  const [virtual]

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

Implements MessageQueueBase.

Definition at line 217 of file MessageQueue.h.

template<unsigned int MAX_UNREAD, unsigned int MAX_RECEIVERS, unsigned int MAX_SENDERS>
RCRegion * MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::peekMessage ( index_t  msg  )  [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

Implements MessageQueueBase.

Definition at line 453 of file MessageQueue.h.

template<unsigned int MAX_UNREAD, unsigned int MAX_RECEIVERS, unsigned int MAX_SENDERS>
RCRegion * MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::readMessage ( index_t  msg,
SemaphoreManager::semid_t  rcvr 
) [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

Implements MessageQueueBase.

Definition at line 429 of file MessageQueue.h.

template<unsigned int MAX_UNREAD, unsigned int MAX_RECEIVERS, unsigned int MAX_SENDERS>
void MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::removeReadStatusListener ( SemaphoreManager::semid_t  sem  )  [virtual]

removes a semaphore from the status listener list

Implements MessageQueueBase.

Definition at line 284 of file MessageQueue.h.

template<unsigned int MAX_UNREAD, unsigned int MAX_RECEIVERS, unsigned int MAX_SENDERS>
void MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::removeReceiver ( SemaphoreManager::semid_t  rcvr  )  [virtual]

remove one from the receiver reference count

Implements MessageQueueBase.

Definition at line 312 of file MessageQueue.h.

template<unsigned int MAX_UNREAD, unsigned int MAX_RECEIVERS, unsigned int MAX_SENDERS>
void MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::sendMessage ( RCRegion rcr,
bool  autoDereference = false 
) [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)

Implements MessageQueueBase.

Definition at line 345 of file MessageQueue.h.


Member Data Documentation

template<unsigned int MAX_UNREAD, unsigned int MAX_RECEIVERS = 10, unsigned int MAX_SENDERS = 10>
const unsigned int MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::CAPACITY = MAX_UNREAD [static]

total number of messages which can be backed up in the queue

Definition at line 189 of file MessageQueue.h.

template<unsigned int MAX_UNREAD, unsigned int MAX_RECEIVERS = 10, unsigned int MAX_SENDERS = 10>
const unsigned int MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::RECEIVER_CAPACITY = MAX_RECEIVERS [static]

total number of receivers which can be registered

Definition at line 191 of file MessageQueue.h.

template<unsigned int MAX_UNREAD, unsigned int MAX_RECEIVERS = 10, unsigned int MAX_SENDERS = 10>
const unsigned int MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::SENDER_CAPACITY = MAX_SENDERS [static]

total number of senders which can be registered

More specifically, this is the maximum number of StatusListeners -- anyone can call sendMessage(), but only this number can get direct notification when messages are received.

Definition at line 196 of file MessageQueue.h.


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

Tekkotsu v5.1CVS
Generated Mon May 9 04:59:13 2016 by Doxygen 1.6.3