This file is indexed.

/usr/include/mama/queue.h is in libmama-dev 2.2.2.1-11.1ubuntu1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
/* $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

/**
 * Callback invoked if an upper size limit has been specified for a queue and
 * that limit has been exceeded.
 *
 * @param queue The mamaQueue for which the size limit has been exceeded. NULL
 * if the queue is the default internal MAMA queue.
 * @param size  The current number of events outstanding on the queue (if
 * supported on the underlying middleware)
 * @param 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.
 */
typedef void (MAMACALLTYPE *mamaQueueHighWatermarkExceededCb) (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 void (MAMACALLTYPE *mamaQueueLowWatermarkCb) (mamaQueue queue,
                                                      size_t    size,
                                                      void*     closure);

/**
 * callbacks which may be invoked in response to certain conditions on
 * the specified queue being met.
 */
typedef struct mamaQueueMonitorCallbacks_
{
    mamaQueueHighWatermarkExceededCb onQueueHighWatermarkExceeded;
    mamaQueueLowWatermarkCb          onQueueLowWatermark;
} mamaQueueMonitorCallbacks;

/**
 * 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.
 *
 * @param queue The mamaQueue on which the function was registered.
 * @param closure The user data supplied in the call to setEnqueueCallback.
 */
typedef void (MAMACALLTYPE *mamaQueueEnqueueCB)(mamaQueue queue, void* closure);

/** Function invoked when a user added event fires. Events are added
 * to a queue using the <code>mamaQuque_enqueueEvent()</code>.
 * @param queue The MamaQueue on which the event was enqueued.
 * @param closure  The user specified data associated with this event.
 */
typedef void (MAMACALLTYPE *mamaQueueEventCB)(mamaQueue queue, void* closure);

/**
 * 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.
 *
 * @param queue A pointer to the resulting queue.
 * @param bridgeImpl A valid bridge implementation for which this queue is
 * being created.
 * @return MAMA_STATUS_OK if the call succeeds.
 * @return MAMA_STATUS_NO_BRIDGE_IMPL if the bridgeImpl parameter is not
 * valid.
 */
MAMAExpDLL
extern mama_status
mamaQueue_create (mamaQueue* queue, mamaBridge bridgeImpl);


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

/**
 * Check to see if a queue can be destroyed. The queue cannot be destroyed if there are
 * currently open event objects on it.
 *
 * @param 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
 */
MAMAExpDLL
extern mama_status
mamaQueue_canDestroy(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.
 *
 * @param 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.
 */
MAMAExpDLL
extern 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. This function will block until
 * all of the objects have been destroyed and will then destroy the queue.
 *
 * @param queue The queue.
 * @return MAMA_STATUS_OK if the call is successful.
 */
MAMAExpDLL
extern 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 for the
 * specified time or until all of the objects have been destroyed and will then destroy the queue.
 *
 * @param queue The queue.
 * @param timeout The time to block for in ms.
 * @return MAMA_STATUS_OK if the call is successful.
 *         MAMA_STATUS_TIMEOUT if the time elapsed.
 */
MAMAExpDLL
extern mama_status
mamaQueue_destroyTimedWait(mamaQueue queue, long timeout);

/**
 * 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.
 *
 * @param queue The mamaQueue for which the high watermark is being set.
 * @param highWatermark The size of the queue, beyond which, results in
 * notification of activity.
 * @return MAMA_STATUS_OK if the function returns successfully.
 */
MAMAExpDLL
extern mama_status
mamaQueue_setHighWatermark (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.
*
* @param queue The mamaQueue for which the high water mark is being retrieved
* @param highWatermark Address to which the high water mark will be written.
*/
MAMAExpDLL
extern mama_status
mamaQueue_getHighWatermark (mamaQueue queue,
                            size_t*   highWatermark);

/**
 * 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.
 *
 * @param queue The queue.
 * @param lowWatermark the low watermark.
 */
MAMAExpDLL
extern mama_status
mamaQueue_setLowWatermark (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.
*
* @param queue The mamaQueue for which the low water mark is being retrieved.
* @param lowWatermark Address to which the low water mark will be written.
*/
MAMAExpDLL
extern mama_status
mamaQueue_getLowWatermark (mamaQueue queue,
                           size_t*   lowWatermark);

/**
 * 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
extern mama_status
mamaQueue_setQueueMonitorCallbacks (
                        mamaQueue                   queue,
                        mamaQueueMonitorCallbacks*  queueMonitorCallbacks,
                        void*                       closure);

/**
 * Writes the number of events currently on the specified queue to
 * the address specified by count.
 *
 * @param queue The queue.
 * @param count Address to where the number of events on the queue will be
 *              written
 * @return MAMA_STATUS_OK if the call is successful.
 */
MAMAExpDLL
extern mama_status
mamaQueue_getEventCount (mamaQueue queue, size_t* count);

/**
* Associate a name identifier with the event queue. This will be used in
* queue related logging statements.
* The string is copied by the API.
*
* @param queue The event queue for which the name is being specified.
* @param name The string identifier for the queue.
* @return MAMA_STATUS_OK The function call succeeded.
* @return MAMA_STATUS_NULL_ARG The queue parameter is NULL
* @return MAMA_STATUS_INVALID_ARG The name parameter is NULL
* @return MAMA_STATUS_NO_MEM  The name could not be copied.
*/
MAMAExpDLL
extern mama_status
mamaQueue_setQueueName (mamaQueue queue, const char* name);

/**
* Get the string name identifier for the specified event queue.
*
* @param queue The event queue for which the name is being sought.
* @param name Address to which the name will be written.
* @return MAMA_STATUS_OK The function call succeeded.
* @return MAMA_STATUS_NULL_ARG The queue parameter was NULL
* @return MAMA_STATUS_INVALID_ARG The name parameter was NULL
*/
MAMAExpDLL
extern mama_status
mamaQueue_getQueueName (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".
*
* @param queue The event queue for which the bridge name is
*              being sought.
* @param name  Address to which the name will be written.
* @return MAMA_STATUS_OK The function call succeeded.
* @return MAMA_STATUS_NULL_ARG The queue parameter was NULL
*/
MAMAExpDLL
extern mama_status
mamaQueue_getQueueBridgeName (mamaQueue queue, const char** name);


/**
 * Dispatch messages from the queue. This call blocks and dispatches
 * until mamaQueue_stopDispatch() is called.
 *
 * @param queue The queue.
 * @return MAMA_STATUS_OK if the call is successful.
 */
MAMAExpDLL
extern mama_status
mamaQueue_dispatch (mamaQueue queue);

/**
 * Dispatch messages from the queue. This call blocks and dispatches
 * until timeout has elapsed.
 *
 * @param queue     The queue.
 * @param timeout   The number of milliseconds to block for before the function returns.
 * @return MAMA_STATUS_OK if the call is successful.
 */
MAMAExpDLL
extern mama_status
mamaQueue_timedDispatch (mamaQueue queue, uint64_t timeout);

/**
 * Dispatch a single event from the specified queue. If there is no event on
 * the queue simply return and do nothing.
 *
 * @param queue The queue from which to dispatch the event.
 * @return MAMA_STATUS_OK if the function succeeds.
 */
MAMAExpDLL
extern mama_status
mamaQueue_dispatchEvent (mamaQueue queue);


/** Add an user event to a queue. Currently only supported using Wombat
 * Middleware.
 *
 * @param queue The queue to which the event is to be added
 * @param callback The function to be invoked when the event fires.
 * @param closure Optional arbitrary user supplied data. Passed back to
 * callback function.
 * @return MAMA_STATUS_OK if the function succeeds.
 */
MAMAExpDLL
extern mama_status
mamaQueue_enqueueEvent  (mamaQueue          queue,
                         mamaQueueEventCB   callback,
                         void*              closure);

/**
 * Unblock the queue as soon as possible. This will cause mamaDispatchers to
 * exit. Creating a new dispatcher will resume dispatching events.
 *
 * @param queue The queue.
 * @return MAMA_STATUS_OK if the call is successful.
 */
MAMAExpDLL
extern mama_status
mamaQueue_stopDispatch (mamaQueue queue);

/**
 * Register the specified callback function to receive a callback
 * each time an event is enqueued on the specified mamaQueue
 *
 * @param queue The mamaQueue on which the callback should be registered.
 * @param callback The function which should be invoked for each enqueue
 * operation
 * @param closure Optional arbitrary user supplied data. Passed back to
 * callback function.
 *
 * @return MAMA_STATUS_OK if the call is successful.
 */
MAMAExpDLL
extern mama_status
mamaQueue_setEnqueueCallback (mamaQueue          queue,
                              mamaQueueEnqueueCB callback,
                              void*              closure);

/**
 * 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.
 *
 * @param queue The mamaQueue for which the callback function should be
 * removed.
 * @return MAMA_STATUS_OK if the call is successful.
 */
MAMAExpDLL
extern mama_status
mamaQueue_removeEnqueueCallback (mamaQueue queue);

/**
 * Get the native middleware implementation queue handle (if
 * applicable for the implementation).  This function is for internal
 * use only.
 *
 * @param queue The mamaQueue for which the native handle is requested.
 * @param nativeHandle The resulting native handle.
 * @return MAMA_STATUS_OK if the call is successful.
 */
MAMAExpDLL
extern mama_status
mamaQueue_getNativeHandle (mamaQueue queue,
                           void**    nativeHandle);

/**
 * 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.
 *
 * @param result A pointer to the resulting mamaDispatcher.
 * @param queue The queue.
 * @return MAMA_STATUS_OK if the call is successful.
 */
MAMAExpDLL
extern mama_status
mamaDispatcher_create (mamaDispatcher* result, mamaQueue queue);

/**
 * Return the queue associated with the dispatcher.
 *
 * @param dispatcher The dispatcher.
 * @param result The queue.
 * @return MAMA_STATUS_OK if the call is successful.
 */
MAMAExpDLL
extern mama_status
mamaDispatcher_getQueue (mamaDispatcher dispatcher, mamaQueue* result);

/**
 * Enable stats logging on queue
 *
 * @param queue The queue.
 * @return MAMA_STATUS_OK if the call is successful.
 */
MAMAExpDLL
extern mama_status
mamaQueue_enableStats(mamaQueue queue);


/**
 * Destroy the dispatcher and stop dispatching events. If
 * mamaDispatcher_createQueue() was used then the underlying queue will be
 * destroyed as well.
 *
 * @param dispatcher The dispatcher.
 * @return MAMA_STATUS_OK if the call is successful.
 */
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__*/