OpenMAMA
queue.h File Reference
#include <mama/mama.h>
#include <mama/types.h>
#include <mama/status.h>

Go to the source code of this file.

Data Structures

struct  mamaQueueMonitorCallbacks_
 callbacks which may be invoked in response to certain conditions on the specified queue being met. More...
 

Typedefs

typedef size_t size
 
typedef size_t voidclosure
 
typedef struct mamaQueueMonitorCallbacks_ mamaQueueMonitorCallbacks
 callbacks which may be invoked in response to certain conditions on the specified queue being met. More...
 
typedef void(MAMACALLTYPE * mamaQueueEnqueueCB) (mamaQueue queue, void *closure)
 Function invoked when an event is enqueued on the queue for which this function was registered. More...
 
typedef void(MAMACALLTYPE * mamaQueueEventCB) (mamaQueue queue, void *closure)
 Function invoked when a user added event fires. More...
 

Functions

typedef void (MAMACALLTYPE *mamaQueueHighWatermarkExceededCb)(mamaQueue queue
 Callback invoked if an upper size limit has been specified for a queue and that limit has been exceeded. More...
 
MAMAExpDLL mama_status mamaQueue_create (mamaQueue *queue, mamaBridge bridgeImpl)
 Create a queue. More...
 
MAMAExpDLL mama_status mamaQueue_create_usingNative (mamaQueue *queue, mamaBridge bridgeImpl, void *nativeQueue)
 
MAMAExpDLL mama_status mamaQueue_canDestroy (mamaQueue queue)
 Check to see if a queue can be destroyed. More...
 
MAMAExpDLL mama_status mamaQueue_destroy (mamaQueue queue)
 Destroy a queue. More...
 
MAMAExpDLL mama_status mamaQueue_destroyWait (mamaQueue queue)
 Destroy a queue. More...
 
MAMAExpDLL mama_status mamaQueue_destroyTimedWait (mamaQueue queue, long timeout)
 Destroy a queue. More...
 
MAMAExpDLL mama_status mamaQueue_setHighWatermark (mamaQueue queue, size_t highWatermark)
 Specify a high watermark for events on the queue. More...
 
MAMAExpDLL mama_status mamaQueue_getHighWatermark (mamaQueue queue, size_t *highWatermark)
 Get the value of the high water mark for the specified queue. More...
 
MAMAExpDLL mama_status mamaQueue_setLowWatermark (mamaQueue queue, size_t lowWatermark)
 Set the low water mark for the queue. More...
 
MAMAExpDLL mama_status mamaQueue_getLowWatermark (mamaQueue queue, size_t *lowWatermark)
 Get the value of the low water mark for the specified queue. More...
 
MAMAExpDLL mama_status mamaQueue_setQueueMonitorCallbacks (mamaQueue queue, mamaQueueMonitorCallbacks *queueMonitorCallbacks, void *closure)
 Specify a set of callbacks which may be invoked in response to certain conditions arising on the queue. More...
 
MAMAExpDLL mama_status mamaQueue_getEventCount (mamaQueue queue, size_t *count)
 Writes the number of events currently on the specified queue to the address specified by count. More...
 
MAMAExpDLL mama_status mamaQueue_setQueueName (mamaQueue queue, const char *name)
 Associate a name identifier with the event queue. More...
 
MAMAExpDLL mama_status mamaQueue_getQueueName (mamaQueue queue, const char **name)
 Get the string name identifier for the specified event queue. More...
 
MAMAExpDLL mama_status mamaQueue_getQueueBridgeName (mamaQueue queue, const char **name)
 Get the string name identifier of the bridge for the specified event queue. More...
 
MAMAExpDLL mama_status mamaQueue_dispatch (mamaQueue queue)
 Dispatch messages from the queue. More...
 
MAMAExpDLL mama_status mamaQueue_timedDispatch (mamaQueue queue, uint64_t timeout)
 Dispatch messages from the queue. More...
 
MAMAExpDLL mama_status mamaQueue_dispatchEvent (mamaQueue queue)
 Dispatch a single event from the specified queue. More...
 
MAMAExpDLL mama_status mamaQueue_enqueueEvent (mamaQueue queue, mamaQueueEventCB callback, void *closure)
 Add an user event to a queue. More...
 
MAMAExpDLL mama_status mamaQueue_stopDispatch (mamaQueue queue)
 Unblock the queue as soon as possible. More...
 
MAMAExpDLL mama_status mamaQueue_setEnqueueCallback (mamaQueue queue, mamaQueueEnqueueCB callback, void *closure)
 Register the specified callback function to receive a callback each time an event is enqueued on the specified mamaQueue. More...
 
MAMAExpDLL mama_status mamaQueue_removeEnqueueCallback (mamaQueue queue)
 If the specified queue has a registered enqueue callback it is unregistered and the previously supplied callback function will no longer receive callbacks for enqueue events. More...
 
MAMAExpDLL mama_status mamaQueue_getNativeHandle (mamaQueue queue, void **nativeHandle)
 Get the native middleware implementation queue handle (if applicable for the implementation). More...
 
MAMAExpDLL mama_status mamaDispatcher_create (mamaDispatcher *result, mamaQueue queue)
 Create a mamaDispatcher. More...
 
MAMAExpDLL mama_status mamaDispatcher_getQueue (mamaDispatcher dispatcher, mamaQueue *result)
 Return the queue associated with the dispatcher. More...
 
MAMAExpDLL mama_status mamaQueue_enableStats (mamaQueue queue)
 Enable stats logging on queue. More...
 
MAMAExpDLL mama_status mamaDispatcher_destroy (mamaDispatcher dispatcher)
 Destroy the dispatcher and stop dispatching events. More...
 
MAMAExpDLL mama_status mamaQueue_getClosure (mamaQueue queue, void **closure)
 
MAMAExpDLL mama_status mamaQueue_setClosure (mamaQueue queue, void *closure)
 

Typedef Documentation

typedef size_t size
typedef size_t void* closure

callbacks which may be invoked in response to certain conditions on the specified queue being met.

typedef void(MAMACALLTYPE * mamaQueueEnqueueCB) (mamaQueue queue, void *closure)

Function invoked when an event is enqueued on the queue for which this function was registered.

LBM Bridge: NB! Users may not dispatch events from this function when using with mamaQueue_setEnqueueCallback() The function is invoked from an LBM internal thread. Attempts to dispatch from here will result in a deadlock.

Parameters
queueThe mamaQueue on which the function was registered.
closureThe user data supplied in the call to setEnqueueCallback.
typedef void(MAMACALLTYPE * mamaQueueEventCB) (mamaQueue queue, void *closure)

Function invoked when a user added event fires.

Events are added to a queue using the mamaQuque_enqueueEvent().

Parameters
queueThe MamaQueue on which the event was enqueued.
closureThe user specified data associated with this event.

Function Documentation

typedef void ( MAMACALLTYPE *  mamaQueueLowWatermarkCb)

Callback invoked if an upper size limit has been specified for a queue and that limit has been exceeded.

Callback invoked when the queue size returns to the lower limit specified.

Parameters
queueThe mamaQueue for which the size limit has been exceeded. NULL if the queue is the default internal MAMA queue.
sizeThe current number of events outstanding on the queue (if supported on the underlying middleware)
closureUser supplied data set when the callback was registered. NULL in the case of the default MAMA queue as no closure can be specified when registering the data quality callbacks.

Only Wombat TCP middleware supports low water mark callbacks.

MAMAExpDLL mama_status mamaQueue_create ( mamaQueue queue,
mamaBridge  bridgeImpl 
)

Create a queue.

Queues allow applications to dispatch events in order with multiple threads using a single mamaDispatcher for each queue. A queue must be associated with a particular middleware.

Parameters
queueA pointer to the resulting queue.
bridgeImplA valid bridge implementation for which this queue is being created.
Returns
MAMA_STATUS_OK if the call succeeds.
MAMA_STATUS_NO_BRIDGE_IMPL if the bridgeImpl parameter is not valid.
MAMAExpDLL mama_status mamaQueue_create_usingNative ( mamaQueue queue,
mamaBridge  bridgeImpl,
void nativeQueue 
)
MAMAExpDLL mama_status mamaQueue_canDestroy ( mamaQueue  queue)

Check to see if a queue can be destroyed.

The queue cannot be destroyed if there are currently open event objects on it.

Parameters
queueThe queue.
Returns
MAMA_STATUS_OK if the queue can be destroyed. MAMA_STATUS_QUEUE_OPEN_OBJECTS if there are still objects open against the queue. MAMA_STATUS_NULL_ARG
MAMAExpDLL mama_status mamaQueue_destroy ( mamaQueue  queue)

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.
Returns
MAMA_STATUS_OK if the call is successful. MAMA_STATUS_QUEUE_OPEN_OBJECTS if there are still objects open against the queue.
MAMAExpDLL mama_status mamaQueue_destroyWait ( mamaQueue  queue)

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.

Parameters
queueThe queue.
Returns
MAMA_STATUS_OK if the call is successful.
MAMAExpDLL mama_status mamaQueue_destroyTimedWait ( mamaQueue  queue,
long  timeout 
)

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
queueThe queue.
timeoutThe time to block for in ms.
Returns
MAMA_STATUS_OK if the call is successful. MAMA_STATUS_TIMEOUT if the time elapsed.
MAMAExpDLL mama_status mamaQueue_setHighWatermark ( mamaQueue  queue,
size_t  highWatermark 
)

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 at runtime. Callbacks can be disabled by setting this value to 0, effectively disabling high watermark checking.

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.

Parameters
queueThe mamaQueue for which the high watermark is being set.
highWatermarkThe size of the queue, beyond which, results in notification of activity.
Returns
MAMA_STATUS_OK if the function returns successfully.
MAMAExpDLL mama_status mamaQueue_getHighWatermark ( mamaQueue  queue,
size_t *  highWatermark 
)

Get the value of the high water mark for the specified queue.

A value of 0 will be returned if no high water mark was previously specified.

Parameters
queueThe mamaQueue for which the high water mark is being retrieved
highWatermarkAddress to which the high water mark will be written.
MAMAExpDLL mama_status mamaQueue_setLowWatermark ( mamaQueue  queue,
size_t  lowWatermark 
)

Set the low water mark for the queue.

Only supported by Wombat TCP middleware.

The low watermark must be >1 and < highWaterMark otherwise this method returns MAMA_STATUS_INVALID_ARG. For this reason the high water mark must be set before invoking this method.

Parameters
queueThe queue.
lowWatermarkthe low watermark.
MAMAExpDLL mama_status mamaQueue_getLowWatermark ( mamaQueue  queue,
size_t *  lowWatermark 
)

Get the value of the low water mark for the specified queue.

A value of 1 will be returned if no low water mark was previously specified.

Parameters
queueThe mamaQueue for which the low water mark is being retrieved.
lowWatermarkAddress to which the low water mark will be written.
MAMAExpDLL mama_status mamaQueue_setQueueMonitorCallbacks ( mamaQueue  queue,
mamaQueueMonitorCallbacks queueMonitorCallbacks,
void closure 
)

Specify a set of callbacks which may be invoked in response to certain conditions arising on the queue.

The behaviour here is middleware specific as not all will support all callbacks.

LBM: When the high watermark is exceeded the mamaQueueHighWatermarkExceededCb callback will invoked each time an event on the queue is dispatched until such time as the number of events on the queue falls below the high watermark.

MAMAExpDLL mama_status mamaQueue_getEventCount ( mamaQueue  queue,
size_t *  count 
)

Writes the number of events currently on the specified queue to the address specified by count.

Parameters
queueThe queue.
countAddress to where the number of events on the queue will be written
Returns
MAMA_STATUS_OK if the call is successful.
MAMAExpDLL mama_status mamaQueue_setQueueName ( mamaQueue  queue,
const char *  name 
)

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
queueThe event queue for which the name is being specified.
nameThe string identifier for the queue.
Returns
MAMA_STATUS_OK The function call succeeded.
MAMA_STATUS_NULL_ARG The queue parameter is NULL
MAMA_STATUS_INVALID_ARG The name parameter is NULL
MAMA_STATUS_NO_MEM The name could not be copied.
MAMAExpDLL mama_status mamaQueue_getQueueName ( mamaQueue  queue,
const char **  name 
)

Get the string name identifier for the specified event queue.

Parameters
queueThe event queue for which the name is being sought.
nameAddress to which the name will be written.
Returns
MAMA_STATUS_OK The function call succeeded.
MAMA_STATUS_NULL_ARG The queue parameter was NULL
MAMA_STATUS_INVALID_ARG The name parameter was NULL
MAMAExpDLL mama_status mamaQueue_getQueueBridgeName ( mamaQueue  queue,
const char **  name 
)

Get the string name identifier of the bridge for the specified event queue.

Name will be either "wmw", "tibrv", or "lbm".

Parameters
queueThe event queue for which the bridge name is being sought.
nameAddress to which the name will be written.
Returns
MAMA_STATUS_OK The function call succeeded.
MAMA_STATUS_NULL_ARG The queue parameter was NULL
MAMAExpDLL mama_status mamaQueue_dispatch ( mamaQueue  queue)

Dispatch messages from the queue.

This call blocks and dispatches until mamaQueue_stopDispatch() is called.

Parameters
queueThe queue.
Returns
MAMA_STATUS_OK if the call is successful.
MAMAExpDLL mama_status mamaQueue_timedDispatch ( mamaQueue  queue,
uint64_t  timeout 
)

Dispatch messages from the queue.

This call blocks and dispatches until timeout has elapsed.

Parameters
queueThe queue.
timeoutThe number of milliseconds to block for before the function returns.
Returns
MAMA_STATUS_OK if the call is successful.
MAMAExpDLL mama_status mamaQueue_dispatchEvent ( mamaQueue  queue)

Dispatch a single event from the specified queue.

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

Parameters
queueThe queue from which to dispatch the event.
Returns
MAMA_STATUS_OK if the function succeeds.
MAMAExpDLL mama_status mamaQueue_enqueueEvent ( mamaQueue  queue,
mamaQueueEventCB  callback,
void closure 
)

Add an user event to a queue.

Currently only supported using Wombat Middleware.

Parameters
queueThe queue to which the event is to be added
callbackThe function to be invoked when the event fires.
closureOptional arbitrary user supplied data. Passed back to callback function.
Returns
MAMA_STATUS_OK if the function succeeds.
MAMAExpDLL mama_status mamaQueue_stopDispatch ( mamaQueue  queue)

Unblock the queue as soon as possible.

This will cause mamaDispatchers to exit. Creating a new dispatcher will resume dispatching events.

Parameters
queueThe queue.
Returns
MAMA_STATUS_OK if the call is successful.
MAMAExpDLL mama_status mamaQueue_setEnqueueCallback ( mamaQueue  queue,
mamaQueueEnqueueCB  callback,
void closure 
)

Register the specified callback function to receive a callback each time an event is enqueued on the specified mamaQueue.

Parameters
queueThe mamaQueue on which the callback should be registered.
callbackThe function which should be invoked for each enqueue operation
closureOptional arbitrary user supplied data. Passed back to callback function.
Returns
MAMA_STATUS_OK if the call is successful.
MAMAExpDLL mama_status mamaQueue_removeEnqueueCallback ( mamaQueue  queue)

If the specified queue has a registered enqueue callback it is unregistered and the previously supplied callback function will no longer receive callbacks for enqueue events.

Parameters
queueThe mamaQueue for which the callback function should be removed.
Returns
MAMA_STATUS_OK if the call is successful.
MAMAExpDLL mama_status mamaQueue_getNativeHandle ( mamaQueue  queue,
void **  nativeHandle 
)

Get the native middleware implementation queue handle (if applicable for the implementation).

This function is for internal use only.

Parameters
queueThe mamaQueue for which the native handle is requested.
nativeHandleThe resulting native handle.
Returns
MAMA_STATUS_OK if the call is successful.
MAMAExpDLL mama_status mamaDispatcher_create ( mamaDispatcher result,
mamaQueue  queue 
)

Create a mamaDispatcher.

The dispatcher spawns a thread to dispatch events from a queue. It will continue to dispatch events until it is destroyed or mamaQueue_stopDispatch is called.

Only a single dispatcher can be created for a given queue. Attempting to create multiple dispatchers for a queue will result in and error. Dispatching message from a single queue with multiple threads results in messages arriving out of order and sequence number gaps for market data subscriptions.

Parameters
resultA pointer to the resulting mamaDispatcher.
queueThe queue.
Returns
MAMA_STATUS_OK if the call is successful.
MAMAExpDLL mama_status mamaDispatcher_getQueue ( mamaDispatcher  dispatcher,
mamaQueue result 
)

Return the queue associated with the dispatcher.

Parameters
dispatcherThe dispatcher.
resultThe queue.
Returns
MAMA_STATUS_OK if the call is successful.
MAMAExpDLL mama_status mamaQueue_enableStats ( mamaQueue  queue)

Enable stats logging on queue.

Parameters
queueThe queue.
Returns
MAMA_STATUS_OK if the call is successful.
MAMAExpDLL mama_status mamaDispatcher_destroy ( mamaDispatcher  dispatcher)

Destroy the dispatcher and stop dispatching events.

If mamaDispatcher_createQueue() was used then the underlying queue will be destroyed as well.

Parameters
dispatcherThe dispatcher.
Returns
MAMA_STATUS_OK if the call is successful.
MAMAExpDLL mama_status mamaQueue_getClosure ( mamaQueue  queue,
void **  closure 
)
MAMAExpDLL mama_status mamaQueue_setClosure ( mamaQueue  queue,
void closure 
)


© 2012 Linux Foundation