OpenMAMA C++ API
Wombat::MamaQueue Class Reference

Queue allows applications to dispatch events in order with multiple threads using a single MamaDispatcher for each queue. More...

#include <MamaQueue.h>

Public Member Functions

 MamaQueue (void)
 
 MamaQueue (mamaQueue cQueue)
 
virtual ~MamaQueue (void)
 
virtual void create (mamaBridge bridgeImpl)
 Create a queue. More...
 
virtual void create (mamaBridge bridgeImpl, void *nativeQueue)
 
virtual void dispatch ()
 Dispatch message. More...
 
virtual void timedDispatch (uint64_t timeout)
 Dispatch messages until timeout (see release notes for details) More...
 
virtual void dispatchEvent ()
 Dispatch a single event from the specified queue. More...
 
virtual void enqueueEvent (MamaQueueEventCallback *callback, void *closure)
 Add a user event to a queue. More...
 
virtual void enqueueEvent (MamaQueueEventCallback &callback, void *closure)
 
virtual void stopDispatch ()
 stopDispatch the queue. More...
 
virtual size_t getEventCount ()
 Returns the number of events currently on the queue. More...
 
virtual void setEnqueueCallback (MamaQueueEnqueueCallback *cb, void *closure)
 Set a callback which will be invoked as each event is added to the underlying event queue. More...
 
virtual void setQueueMonitorCallback (MamaQueueMonitorCallback *cb, void *closure)
 Register an object to receive callbacks for monitoring the behaviour of the MamaQueue. More...
 
virtual void setHighWatermark (size_t highWatermark)
 Specify a high watermark for events on the queue. More...
 
virtual size_t getHighWatermark (void) const
 Return the high water mark as set via setHighWaterMark() More...
 
virtual void setLowWatermark (size_t lowWatermark)
 Set the low watermark. More...
 
virtual size_t getLowWatermark (void) const
 Return the low water mark as set via setLowWaterMark() More...
 
virtual void setQueueName (const char *name)
 Associate a name identifier with the event queue. More...
 
virtual const char * getQueueName () const
 Retrieve the string name identifier for the queue as specified from a call to setQueueName(). More...
 
virtual const char * getQueueBridgeName () const
 Retrieve the string name identifier for the queue's bridge. More...
 
virtual void destroy ()
 Destroy a queue. More...
 
virtual void setClosure (void *closure)
 
virtual void * getClosure ()
 
virtual void destroyTimedWait (long timeout)
 Destroy a queue. More...
 
virtual void destroyWait ()
 Destroy a queue. More...
 
mamaQueue getCValue ()
 Access to C types for implementation of related classes. More...
 
const mamaQueue getCValue () const
 
void setCValue (mamaQueue cQueue)
 This can only be set once and only if the c value is not already set - E.g. More...
 

Public Attributes

MamaQueueImpl * mPimpl
 

Detailed Description

Queue allows applications to dispatch events in order with multiple threads using a single MamaDispatcher for each queue.

Constructor & Destructor Documentation

§ MamaQueue() [1/2]

Wombat::MamaQueue::MamaQueue ( void  )

§ MamaQueue() [2/2]

Wombat::MamaQueue::MamaQueue ( mamaQueue  cQueue)

§ ~MamaQueue()

virtual Wombat::MamaQueue::~MamaQueue ( void  )
virtual

Member Function Documentation

§ create() [1/2]

virtual void Wombat::MamaQueue::create ( mamaBridge  bridgeImpl)
virtual

Create a queue.

Queues allow applications to dispatch events in order with multiple threads using a single mamaDispatcher for each queue.

Callers should call delete queue when done.

Returns
a pointer the queue.

§ create() [2/2]

virtual void Wombat::MamaQueue::create ( mamaBridge  bridgeImpl,
void *  nativeQueue 
)
virtual

§ dispatch()

virtual void Wombat::MamaQueue::dispatch ( )
virtual

Dispatch message.

Blocks and dispatches messages until unblock is called.

§ timedDispatch()

virtual void Wombat::MamaQueue::timedDispatch ( uint64_t  timeout)
virtual

Dispatch messages until timeout (see release notes for details)

§ dispatchEvent()

virtual void Wombat::MamaQueue::dispatchEvent ( )
virtual

Dispatch a single event from the specified queue.

If there is no event on the queue simply return and do nothing

§ enqueueEvent() [1/2]

virtual void Wombat::MamaQueue::enqueueEvent ( MamaQueueEventCallback callback,
void *  closure 
)
virtual

Add a user event to a queue.

Parameters
callbackInstance of the MamaQueueEventCallback interface. MamaQueueEventCallback.onEvent() will be invoked when the event fires.
closureOptional user supplied arbitrary closure data which will be passed back in the MamaQueueEventCallback.onEvent) callback
Exceptions
MamaExceptionNot currently implemented for pure Java API.

§ enqueueEvent() [2/2]

virtual void Wombat::MamaQueue::enqueueEvent ( MamaQueueEventCallback callback,
void *  closure 
)
virtual

§ stopDispatch()

virtual void Wombat::MamaQueue::stopDispatch ( )
virtual

stopDispatch the queue.

§ getEventCount()

virtual size_t Wombat::MamaQueue::getEventCount ( )
virtual

Returns the number of events currently on the queue.

Returns
size_t The number of the events on the queue.

§ setEnqueueCallback()

virtual void Wombat::MamaQueue::setEnqueueCallback ( MamaQueueEnqueueCallback cb,
void *  closure 
)
virtual

Set a callback which will be invoked as each event is added to the underlying event queue.

Parameters
cbPointer to an instance of MamaQueueEnqueueCallback
closureArbitrary user supplied data. Passed back to onEventEnqueue() for each event enqueued.

§ setQueueMonitorCallback()

virtual void Wombat::MamaQueue::setQueueMonitorCallback ( MamaQueueMonitorCallback cb,
void *  closure 
)
virtual

Register an object to receive callbacks for monitoring the behaviour of the MamaQueue.

Parameters
cbReference to the object which will receive callbacks.
closureUser supplied data which will be returned as the callbacks are invoked.

§ setHighWatermark()

virtual void Wombat::MamaQueue::setHighWatermark ( size_t  highWatermark)
virtual

Specify a high watermark for events on the queue.

The behaviour for setting this value varies depending on the underlying middleware.

LBM: LBM uses an unbounded event queue. Setting this values allows users of the API to receive a callback if the value is exceeded. (See mamaQueue_setQueueMonitorCallback() for setting queue related callbacks) the default behaviour is for the queue to grow unbounded without notifications. The high watermark for LBM can be set for all queues at once by setting the mama.lbm.eventqueuemonitor.queue_size_warning property for the API. Calls to this function will override the value specified in mama.properties.

RV: This will set a queue limit policy of TIBRVQUEUE_DISCARD_FIRST whereby the oldest events in the queue are discarded first. The discard amount will be set with a value of 1. i.e. events will be dropped from the queue one at a time. The default behaviour is an unlimited queue which does not discard events.

§ getHighWatermark()

virtual size_t Wombat::MamaQueue::getHighWatermark ( void  ) const
virtual

Return the high water mark as set via setHighWaterMark()

§ setLowWatermark()

virtual void Wombat::MamaQueue::setLowWatermark ( size_t  lowWatermark)
virtual

Set the low watermark.

Only supported for Wombat TCP middleware.

Parameters
lowWatermarkThe low water mark.

§ getLowWatermark()

virtual size_t Wombat::MamaQueue::getLowWatermark ( void  ) const
virtual

Return the low water mark as set via setLowWaterMark()

§ setQueueName()

virtual void Wombat::MamaQueue::setQueueName ( const char *  name)
virtual

Associate a name identifier with the event queue.

This will be used in queue related logging statements. The string is copied by the API.

Parameters
nameThe string name identifier for the queue.

§ getQueueName()

virtual const char* Wombat::MamaQueue::getQueueName ( ) const
virtual

Retrieve the string name identifier for the queue as specified from a call to setQueueName().

If a name has not been specified via a call tosetQueueName() the queue will assume a default name of "NO_NAME"

Returns
The name identifier for the MamaQueue.

§ getQueueBridgeName()

virtual const char* Wombat::MamaQueue::getQueueBridgeName ( ) const
virtual

Retrieve the string name identifier for the queue's bridge.

Returns
The name identifier for the bridge: "wmw", "lbm", or "tibrv".

§ destroy()

virtual void Wombat::MamaQueue::destroy ( )
virtual

Destroy a queue.

Note that the queue can only be destroyed if all of the objects created on it, (timers, subscriptions etc), have been destroyed.

Parameters
queueThe queue.
Exceptions
MamaStatuswith a code of MAMA_STATUS_QUEUE_OPEN_OBJECTS if there are still objects open against the queue.

§ setClosure()

virtual void Wombat::MamaQueue::setClosure ( void *  closure)
virtual

§ getClosure()

virtual void* Wombat::MamaQueue::getClosure ( )
virtual

§ destroyTimedWait()

virtual void Wombat::MamaQueue::destroyTimedWait ( long  timeout)
virtual

Destroy a queue.

Note that the queue can only be destroyed if all of the objects created on it, (timers, subscriptions etc), have been destroyed. This function will block for the specified time or until all of the objects have been destroyed and will then destroy the queue.

Parameters
timeoutThe time to block for in ms.
Exceptions
MamaStatuswith a code of MAMA_STATUS_TIMEOUT if the time elapsed.

§ destroyWait()

virtual void Wombat::MamaQueue::destroyWait ( )
virtual

Destroy a queue.

Note that the queue can only be destroyed if all of the objects created on it, (timers, subscriptions etc), have been destroyed. This function will block until all of the objects have been destroyed and will then destroy the queue.

§ getCValue() [1/2]

mamaQueue Wombat::MamaQueue::getCValue ( )

Access to C types for implementation of related classes.

§ getCValue() [2/2]

const mamaQueue Wombat::MamaQueue::getCValue ( ) const

§ setCValue()

void Wombat::MamaQueue::setCValue ( mamaQueue  cQueue)

This can only be set once and only if the c value is not already set - E.g.

from calling create()

Member Data Documentation

§ mPimpl

MamaQueueImpl* Wombat::MamaQueue::mPimpl