sipxportlib  Version 3.3
Public Member Functions | List of all members
OsMsgQShared Class Reference

#include <OsMsgQShared.h>

Inheritance diagram for OsMsgQShared:
Inheritance graph
[legend]
Collaboration diagram for OsMsgQShared:
Collaboration graph
[legend]

Public Member Functions

 OsMsgQShared (const int maxMsgs=DEF_MAX_MSGS, const int maxMsgLen=DEF_MAX_MSG_LEN, const int options=Q_PRIORITY, const UtlString &name="")
 Constructor. More...
 
virtual ~OsMsgQShared ()
 Destructor. More...
 
virtual OsStatus send (const OsMsg &rMsg, const OsTime &rTimeout=OsTime::OS_INFINITY)
 Insert a copy of the message at the tail of the queue. More...
 
virtual OsStatus sendNoCopy (OsMsg *pMsg, const OsTime &rTimeout=OsTime::OS_INFINITY)
 Insert an original of the message at the tail of the queue. More...
 
virtual OsStatus sendUrgent (const OsMsg &rMsg, const OsTime &rTimeout=OsTime::OS_INFINITY)
 Insert a copy of the message at the head of the queue. More...
 
virtual OsStatus sendFromISR (OsMsg &rMsg)
 Insert a copy of the message at the tail of the queue with ISR flag. More...
 
virtual OsStatus receive (OsMsg *&rpMsg, const OsTime &rTimeout=OsTime::OS_INFINITY)
 Remove a message from the head of the queue. More...
 
virtual int numMsgs ()
 Return the number of messages in the queue. More...
 
- Public Member Functions inherited from OsMsgQBase
 OsMsgQBase (const UtlString &name)
 Constructor. More...
 
virtual ~OsMsgQBase ()
 Destructor. More...
 
virtual void flush ()
 Delete all messages currently in the queue. More...
 
virtual void setSendHook (OsMsgQSendHookPtr func)
 Set the function that is invoked whenever a msg is sent to the queue. More...
 
virtual void setFlushHook (OsMsgQFlushHookPtr func)
 Set the function that is invoked whenever a msg is flushed from the queue. More...
 
int maxMsgs () const
 Returns the maximum number of messages that can be queued. More...
 
virtual OsMsgQSendHookPtr getSendHook () const
 Return a pointer to the current send hook function. More...
 
virtual UtlBoolean isEmpty ()
 Return TRUE if the message queue is empty, FALSE otherwise. More...
 
const UtlStringgetName () const
 Get the name associated with the queue. More...
 

Additional Inherited Members

- Public Types inherited from OsMsgQBase
enum  Options { Q_FIFO = 0x0, Q_PRIORITY = 0x1 }
 
- Static Public Member Functions inherited from OsMsgQBase
static OsMsgQBasegetMsgQByName (const UtlString &name)
 Return a pointer to the named queue, or NULL if not found. More...
 
- Static Public Attributes inherited from OsMsgQBase
static const int DEF_MAX_MSGS = 100
 Default maximum number of messages. More...
 
static const int DEF_MAX_MSG_LEN = 32
 Default maximum msg length (in bytes) More...
 
static const UtlString MSGQ_PREFIX
 Prefix for OsMsgQ names stored in < the name database. More...
 
- Protected Attributes inherited from OsMsgQBase
OsMsgQSendHookPtr mSendHookFunc
 Method that is invoked whenever a message is sent to the queue. More...
 
OsMsgQFlushHookPtr mFlushHookFunc
 Method that is invoked whenever a message is flushed from the queue. More...
 
int mMaxMsgs
 maximum number of messages the queue can hold More...
 

Detailed Description

Message queue implementation for OS's with no native message queue support

Two kinds of concurrent tasks, called "senders" and "receivers", communicate using a message queue. When the queue is empty, receivers are blocked until there are messages to receive. When the queue is full, senders are blocked until some of the queued messages are received – freeing up space in the queue for more messages.

This implementation is based on the description from the book "Operating Systems Principles" by Per Brinch Hansen, 1973. This solution uses:

  • a counting semaphore (mEmpty) to control the delay of the sender in the following way: initially: the "empty" semaphore count is set to maxMsgs before send: acquire(empty) after receive: release(empty)
  • a counting semaphore (mFull) to control the delay of the receiver in the following way: initially: the "full" semaphore count is set to 0 before receive: acquire(full) after send: release(full)
  • a binary semaphore (mGuard) to ensure against concurrent access to internal object data

Constructor & Destructor Documentation

OsMsgQShared ( const int  maxMsgs = DEF_MAX_MSGS,
const int  maxMsgLen = DEF_MAX_MSG_LEN,
const int  options = Q_PRIORITY,
const UtlString name = "" 
)

Constructor.

If name is specified but is already in use, throw an exception.

Parameters
maxMsgsMax number of messages.
maxMsgLenMax msg length (bytes).
optionsHow to queue blocked tasks.
nameGlobal name for this queue.
~OsMsgQShared ( )
virtual

Destructor.

Member Function Documentation

OsStatus send ( const OsMsg rMsg,
const OsTime rTimeout = OsTime::OS_INFINITY 
)
virtual

Insert a copy of the message at the tail of the queue.

Wait until there is either room on the queue or the timeout expires.

This method creates a copy of the pMsg, before inserting it to the queue.

Implements OsMsgQBase.

OsStatus sendNoCopy ( OsMsg pMsg,
const OsTime rTimeout = OsTime::OS_INFINITY 
)
virtual

Insert an original of the message at the tail of the queue.

Wait until there is either room on the queue or the timeout expires.

This method does not create a copy of the pMsg, inserting it to the queue as is.

Implements OsMsgQBase.

OsStatus sendUrgent ( const OsMsg rMsg,
const OsTime rTimeout = OsTime::OS_INFINITY 
)
virtual

Insert a copy of the message at the head of the queue.

Wait until there is either room on the queue or the timeout expires.

Implements OsMsgQBase.

OsStatus sendFromISR ( OsMsg rMsg)
virtual

Insert a copy of the message at the tail of the queue with ISR flag.

Sending from an ISR has a couple of implications. Since we can't allocate memory within an ISR, we don't create a copy of the message before sending it and the sender and receiver need to agree on a protocol (outside this class) for when the message can be freed. The sentFromISR flag in the OsMsg object will be TRUE for messages sent using this method.

Implements OsMsgQBase.

OsStatus receive ( OsMsg *&  rpMsg,
const OsTime rTimeout = OsTime::OS_INFINITY 
)
virtual

Remove a message from the head of the queue.

Wait until either a message arrives or the timeout expires. Other than for messages sent from an ISR, the receiver is responsible for freeing the received message.

Implements OsMsgQBase.

int numMsgs ( void  )
virtual

Return the number of messages in the queue.

Implements OsMsgQBase.