mama/queue.h

Classes

Types

Functions

Types Documentation

typedef mamaQueueHighWatermarkExceededCb

typedef void(MAMACALLTYPE * mamaQueueHighWatermarkExceededCb) (mamaQueue queue, size_t size, void *closure);

Parameters:

• queue The mamaQueue for which the size limit has been exceeded. NULL if the queue is the default internal MAMA queue.
• size The current number of events outstanding on the queue (if supported on the underlying middleware)
• closure User 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.

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

typedef mamaQueueLowWatermarkCb

typedef void(MAMACALLTYPE * mamaQueueLowWatermarkCb) (mamaQueue queue, size_t size, void *closure);

Callback invoked when the queue size returns to the lower limit specified. Only Wombat TCP middleware supports low water mark callbacks.

typedef mamaQueueMonitorCallbacks

typedef struct mamaQueueMonitorCallbacks_ mamaQueueMonitorCallbacks;

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

typedef mamaQueueEnqueueCB

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

Parameters:

• queue The mamaQueue on which the function was registered.
• closure The user data supplied in the call to setEnqueueCallback.

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.

typedef mamaQueueEventCB

typedef void(MAMACALLTYPE * mamaQueueEventCB) (mamaQueue queue, void *closure);

Parameters:

• queue The MamaQueue on which the event was enqueued.
• closure The user specified data associated with this event.

Function invoked when a user added event fires. Events are added to a queue using the mamaQuque_enqueueEvent().

Functions Documentation

function mamaQueue_create

MAMAExpDLL mama_status mamaQueue_create(
    mamaQueue * queue,
    mamaBridge bridgeImpl
)

Parameters:

• queue A pointer to the resulting queue.
• bridgeImpl A valid bridge implementation for which this queue is being created.

Return:

• MAMA_STATUS_OK if the call succeeds.
• MAMA_STATUS_NO_BRIDGE_IMPL if the bridgeImpl parameter is not valid.

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.

function mamaQueue_create_usingNative

MAMAExpDLL mama_status mamaQueue_create_usingNative(
    mamaQueue * queue,
    mamaBridge bridgeImpl,
    void * nativeQueue
)

function mamaQueue_canDestroy

MAMAExpDLL mama_status mamaQueue_canDestroy(
    mamaQueue queue
)

Parameters:

• queue The queue.

Return: 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

Check to see if a queue can be destroyed. The queue cannot be destroyed if there are currently open event objects on it.

function mamaQueue_destroy

MAMAExpDLL mama_status mamaQueue_destroy(
    mamaQueue queue
)

Parameters:

• queue The queue.

Return: MAMA_STATUS_OK if the call is successful. MAMA_STATUS_QUEUE_OPEN_OBJECTS if there are still objects open against the 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.

function mamaQueue_destroyWait

MAMAExpDLL mama_status mamaQueue_destroyWait(
    mamaQueue queue
)

Parameters:

• queue The queue.

Return: MAMA_STATUS_OK if the call is successful.

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.

function mamaQueue_destroyTimedWait

MAMAExpDLL mama_status mamaQueue_destroyTimedWait(
    mamaQueue queue,
    long timeout
)

Parameters:

• queue The queue.
• timeout The time to block for in ms.

Return: MAMA_STATUS_OK if the call is successful. MAMA_STATUS_TIMEOUT if the time elapsed.

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.

function mamaQueue_setHighWatermark

MAMAExpDLL mama_status mamaQueue_setHighWatermark(
    mamaQueue queue,
    size_t highWatermark
)

Parameters:

• queue The mamaQueue for which the high watermark is being set.
• highWatermark The size of the queue, beyond which, results in notification of activity.

Return: MAMA_STATUS_OK if the function returns successfully.

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.

function mamaQueue_getHighWatermark

MAMAExpDLL mama_status mamaQueue_getHighWatermark(
    mamaQueue queue,
    size_t * highWatermark
)

Parameters:

• queue The mamaQueue for which the high water mark is being retrieved
• highWatermark Address to which the high water mark will be written.

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.

function mamaQueue_setLowWatermark

MAMAExpDLL mama_status mamaQueue_setLowWatermark(
    mamaQueue queue,
    size_t lowWatermark
)

Parameters:

• queue The queue.
• lowWatermark the low watermark.

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.

function mamaQueue_getLowWatermark

MAMAExpDLL mama_status mamaQueue_getLowWatermark(
    mamaQueue queue,
    size_t * lowWatermark
)

Parameters:

• queue The mamaQueue for which the low water mark is being retrieved.
• lowWatermark Address to which the low water mark will be written.

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.

function mamaQueue_setQueueMonitorCallbacks

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.

function mamaQueue_getEventCount

MAMAExpDLL mama_status mamaQueue_getEventCount(
    mamaQueue queue,
    size_t * count
)

Parameters:

• queue The queue.
• count Address to where the number of events on the queue will be written

Return: MAMA_STATUS_OK if the call is successful.

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

function mamaQueue_setQueueName

MAMAExpDLL mama_status mamaQueue_setQueueName(
    mamaQueue queue,
    const char * name
)

Parameters:

• queue The event queue for which the name is being specified.
• name The string identifier for the queue.

Return:

• 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.

Associate a name identifier with the event queue. This will be used in queue related logging statements. The string is copied by the API.

function mamaQueue_getQueueName

MAMAExpDLL mama_status mamaQueue_getQueueName(
    mamaQueue queue,
    const char ** name
)

Parameters:

• queue The event queue for which the name is being sought.
• name Address to which the name will be written.

Return:

• 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

Get the string name identifier for the specified event queue.

function mamaQueue_getQueueBridgeName

MAMAExpDLL mama_status mamaQueue_getQueueBridgeName(
    mamaQueue queue,
    const char ** name
)

Parameters:

• queue The event queue for which the bridge name is being sought.
• name Address to which the name will be written.

Return:

• MAMA_STATUS_OK The function call succeeded.
• MAMA_STATUS_NULL_ARG The queue parameter was NULL

Get the string name identifier of the bridge for the specified event queue. Name will be either “wmw”, “tibrv”, or “lbm”.

function mamaQueue_dispatch

MAMAExpDLL mama_status mamaQueue_dispatch(
    mamaQueue queue
)

Parameters:

• queue The queue.

Return: MAMA_STATUS_OK if the call is successful.

Dispatch messages from the queue. This call blocks and dispatches until mamaQueue_stopDispatch() is called.

function mamaQueue_timedDispatch

MAMAExpDLL mama_status mamaQueue_timedDispatch(
    mamaQueue queue,
    uint64_t timeout
)

Parameters:

• queue The queue.
• timeout The maximum number of milliseconds to block for before the function returns.

Return: MAMA_STATUS_OK if the call is successful.

Dispatch messages from the queue until timeout has elapsed. Some middleware implementations will always block until timeout (dispatching multiple times), whereas others will always unblock once the first event is dispatched or the timeout has elapsed - whichever comes first.

function mamaQueue_dispatchEvent

MAMAExpDLL mama_status mamaQueue_dispatchEvent(
    mamaQueue queue
)

Parameters:

• queue The queue from which to dispatch the event.

Return: MAMA_STATUS_OK if the function succeeds.

Dispatch a single event from the specified queue. If there is no event on the queue simply return and do nothing.

function mamaQueue_enqueueEvent

MAMAExpDLL mama_status mamaQueue_enqueueEvent(
    mamaQueue queue,
    mamaQueueEventCB callback,
    void * closure
)

Parameters:

• queue The queue to which the event is to be added
• callback The function to be invoked when the event fires.
• closure Optional arbitrary user supplied data. Passed back to callback function.

Return: MAMA_STATUS_OK if the function succeeds.

Add an user event to a queue. Currently only supported using Wombat Middleware.

function mamaQueue_stopDispatch

MAMAExpDLL mama_status mamaQueue_stopDispatch(
    mamaQueue queue
)

Parameters:

• queue The queue.

Return: MAMA_STATUS_OK if the call is successful.

Unblock the queue as soon as possible. This will cause mamaDispatchers to exit. Creating a new dispatcher will resume dispatching events.

function mamaQueue_setEnqueueCallback

MAMAExpDLL mama_status mamaQueue_setEnqueueCallback(
    mamaQueue queue,
    mamaQueueEnqueueCB callback,
    void * closure
)

Parameters:

• queue The mamaQueue on which the callback should be registered.
• callback The function which should be invoked for each enqueue operation
• closure Optional arbitrary user supplied data. Passed back to callback function.

Return: MAMA_STATUS_OK if the call is successful.

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

function mamaQueue_removeEnqueueCallback

MAMAExpDLL mama_status mamaQueue_removeEnqueueCallback(
    mamaQueue queue
)

Parameters:

• queue The mamaQueue for which the callback function should be removed.

Return: MAMA_STATUS_OK if the call is successful.

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.

function mamaQueue_getNativeHandle

MAMAExpDLL mama_status mamaQueue_getNativeHandle(
    mamaQueue queue,
    void ** nativeHandle
)

Parameters:

• queue The mamaQueue for which the native handle is requested.
• nativeHandle The resulting native handle.

Return: MAMA_STATUS_OK if the call is successful.

Get the native middleware implementation queue handle (if applicable for the implementation). This function is for internal use only.

function mamaDispatcher_create

MAMAExpDLL mama_status mamaDispatcher_create(
    mamaDispatcher * result,
    mamaQueue queue
)

Parameters:

• result A pointer to the resulting mamaDispatcher.
• queue The queue.

Return: MAMA_STATUS_OK if the call is successful.

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.

function mamaDispatcher_getQueue

MAMAExpDLL mama_status mamaDispatcher_getQueue(
    mamaDispatcher dispatcher,
    mamaQueue * result
)

Parameters:

• dispatcher The dispatcher.
• result The queue.

Return: MAMA_STATUS_OK if the call is successful.

Return the queue associated with the dispatcher.

function mamaQueue_enableStats

MAMAExpDLL mama_status mamaQueue_enableStats(
    mamaQueue queue
)

Parameters:

• queue The queue.

Return: MAMA_STATUS_OK if the call is successful.

Enable stats logging on queue

function mamaDispatcher_destroy

MAMAExpDLL mama_status mamaDispatcher_destroy(
    mamaDispatcher dispatcher
)

Parameters:

• dispatcher The dispatcher.

Return: MAMA_STATUS_OK if the call is successful.

Destroy the dispatcher and stop dispatching events. If mamaDispatcher_createQueue() was used then the underlying queue will be destroyed as well.

function mamaQueue_getClosure

MAMAExpDLL mama_status mamaQueue_getClosure(
    mamaQueue queue,
    void ** closure
)

function mamaQueue_setClosure

MAMAExpDLL mama_status mamaQueue_setClosure(
    mamaQueue queue,
    void * closure
)

Source code

/* $Id$
 *
 * OpenMAMA: The open middleware agnostic messaging API
 * Copyright (C) 2011 NYSE Technologies, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 * 02110-1301 USA
 */

#ifndef MamaQueueH__
#define MamaQueueH__

#include <mama/mama.h>
#include <mama/types.h>
#include <mama/status.h>

#if defined(__cplusplus)
extern "C" {
#endif

typedef void (MAMACALLTYPE *mamaQueueHighWatermarkExceededCb) (mamaQueue queue,
                                                               size_t    size,
                                                               void*     closure);

typedef void (MAMACALLTYPE *mamaQueueLowWatermarkCb) (mamaQueue queue,
                                                      size_t    size,
                                                      void*     closure);

typedef struct mamaQueueMonitorCallbacks_
{
    mamaQueueHighWatermarkExceededCb onQueueHighWatermarkExceeded;
    mamaQueueLowWatermarkCb          onQueueLowWatermark;
} mamaQueueMonitorCallbacks;

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

typedef void (MAMACALLTYPE *mamaQueueEventCB)(mamaQueue queue, void* closure);

MAMAExpDLL
extern mama_status
mamaQueue_create (mamaQueue* queue, mamaBridge bridgeImpl);


MAMAExpDLL
extern mama_status
mamaQueue_create_usingNative (mamaQueue* queue, mamaBridge bridgeImpl, void* nativeQueue);

MAMAExpDLL
extern mama_status
mamaQueue_canDestroy(mamaQueue queue);

MAMAExpDLL
extern mama_status
mamaQueue_destroy (mamaQueue queue);

MAMAExpDLL
extern mama_status
mamaQueue_destroyWait(mamaQueue queue);

MAMAExpDLL
extern mama_status
mamaQueue_destroyTimedWait(mamaQueue queue, long timeout);

MAMAExpDLL
extern mama_status
mamaQueue_setHighWatermark (mamaQueue queue,
                            size_t highWatermark);

MAMAExpDLL
extern mama_status
mamaQueue_getHighWatermark (mamaQueue queue,
                            size_t*   highWatermark);

MAMAExpDLL
extern mama_status
mamaQueue_setLowWatermark (mamaQueue queue,
                           size_t lowWatermark);

MAMAExpDLL
extern mama_status
mamaQueue_getLowWatermark (mamaQueue queue,
                           size_t*   lowWatermark);

MAMAExpDLL
extern mama_status
mamaQueue_setQueueMonitorCallbacks (
                        mamaQueue                   queue,
                        mamaQueueMonitorCallbacks*  queueMonitorCallbacks,
                        void*                       closure);

MAMAExpDLL
extern mama_status
mamaQueue_getEventCount (mamaQueue queue, size_t* count);

MAMAExpDLL
extern mama_status
mamaQueue_setQueueName (mamaQueue queue, const char* name);

MAMAExpDLL
extern mama_status
mamaQueue_getQueueName (mamaQueue queue, const char** name);

MAMAExpDLL
extern mama_status
mamaQueue_getQueueBridgeName (mamaQueue queue, const char** name);


MAMAExpDLL
extern mama_status
mamaQueue_dispatch (mamaQueue queue);

MAMAExpDLL
extern mama_status
mamaQueue_timedDispatch (mamaQueue queue, uint64_t timeout);

MAMAExpDLL
extern mama_status
mamaQueue_dispatchEvent (mamaQueue queue);


MAMAExpDLL
extern mama_status
mamaQueue_enqueueEvent  (mamaQueue          queue,
                         mamaQueueEventCB   callback,
                         void*              closure);

MAMAExpDLL
extern mama_status
mamaQueue_stopDispatch (mamaQueue queue);

MAMAExpDLL
extern mama_status
mamaQueue_setEnqueueCallback (mamaQueue          queue,
                              mamaQueueEnqueueCB callback,
                              void*              closure);

MAMAExpDLL
extern mama_status
mamaQueue_removeEnqueueCallback (mamaQueue queue);

MAMAExpDLL
extern mama_status
mamaQueue_getNativeHandle (mamaQueue queue,
                           void**    nativeHandle);

MAMAExpDLL
extern mama_status
mamaDispatcher_create (mamaDispatcher* result, mamaQueue queue);

MAMAExpDLL
extern mama_status
mamaDispatcher_getQueue (mamaDispatcher dispatcher, mamaQueue* result);

MAMAExpDLL
extern mama_status
mamaQueue_enableStats(mamaQueue queue);


MAMAExpDLL
extern mama_status
mamaDispatcher_destroy (mamaDispatcher dispatcher);

MAMAExpDLL
extern mama_status
mamaQueue_getClosure (mamaQueue queue, void** closure);

MAMAExpDLL
extern mama_status
mamaQueue_setClosure (mamaQueue queue, void* closure);
#if defined(__cplusplus)
}
#endif

#endif /*MamaQueueH__*/

Updated on 2023-03-31 at 15:29:16 +0100