|
TIBCO FTL®
|
Event queue objects hold message and timer events until callbacks can process them. More...
Macros | |
Dispatch Timeout Constants | |
These constants are special timeout values for dispatching a queue. | |
| #define | TIB_TIMEOUT_WAIT_FOREVER ((tibdouble_t) -1.0) |
| Wait indefinitely for an event. More... | |
| #define | TIB_TIMEOUT_NO_WAIT ((tibdouble_t) 0.0) |
| Do not wait for an event. More... | |
Queue Properties | |
These string constants are the valid property names for creating a queue. | |
| #define | TIB_EVENTQUEUE_PROPERTY_BOOL_INLINE_MODE "com.tibco.ftl.client.inline" |
| Inline mode (low-latency); boolean. More... | |
| #define | TIB_EVENTQUEUE_PROPERTY_INT_DISCARD_POLICY "com.tibco.ftl.client.discard.policy" |
| Discard policy; integer. More... | |
| #define | TIB_EVENTQUEUE_PROPERTY_INT_DISCARD_POLICY_MAX_EVENTS "com.tibco.ftl.client.discard.max_events" |
| Max events; integer. More... | |
| #define | TIB_EVENTQUEUE_PROPERTY_INT_DISCARD_POLICY_DISCARD_AMOUNT "com.tibco.ftl.client.discard.amount" |
| Discard amount; integer. More... | |
| #define | TIB_EVENTQUEUE_PROPERTY_STRING_NAME "com.tibco.ftl.client.queue.name" |
| Queue name; string. More... | |
Typedefs | |
| typedef void(* | tibEventQueueComplete )(tibEx e, tibEventQueue queue) |
| Event queue completion callback. More... | |
| typedef void(* | tibEventQueueCompleteEx )(tibEx e, tibEventQueue queue, void *closure) |
| Event queue completion callback. More... | |
| typedef void(* | tibMsgCallback )(tibEx e, tibEventQueue queue, tibint32_t msgCount, tibMessage *msgs, void **closures) |
| Message dispatch callback. More... | |
| typedef void(* | tibSubscriberComplete )(tibEx e, tibSubscriber subscriber, void *closure) |
| Subscriber completion callback. More... | |
| typedef struct __tibTimerId * | tibTimer |
| A timer object queues an event when its interval elapses. More... | |
| typedef void(* | tibTimerCallback )(tibEx e, tibEventQueue queue, tibTimer timer, void *closure) |
| Event timer callback. More... | |
| typedef void(* | tibTimerComplete )(tibEx e, tibTimer timer, void *closure) |
Enumerations | |
| enum | tibEventQueue_DiscardPolicy { TIB_EVENTQUEUE_DISCARD_NONE = 0, TIB_EVENTQUEUE_DISCARD_OLD = 1, TIB_EVENTQUEUE_DISCARD_NEW = 2 } |
| Instructions for discarding events when a queue overflows. More... | |
Functions | |
| TIB_API void | tibEventQueue_AddSubscriber (tibEx e, tibEventQueue queue, tibSubscriber subscriber, tibMsgCallback callback, void *closure) |
| Add a subscriber to a queue. More... | |
| TIB_API tibEventQueue | tibEventQueue_Create (tibEx e, tibRealm realm, tibProperties props) |
| Create an event queue. More... | |
| TIB_API tibTimer | tibEventQueue_CreateTimer (tibEx e, tibEventQueue queue, tibdouble_t interval, tibTimerCallback callback, void *closure) |
| Create and start a timer. More... | |
| TIB_API void | tibEventQueue_Destroy (tibEx e, tibEventQueue queue, tibEventQueueComplete completeCb) |
| Destroy an event queue. More... | |
| TIB_API void | tibEventQueue_DestroyEx (tibEx e, tibEventQueue queue, tibEventQueueCompleteEx completeCb, void *closure) |
| Destroy an event queue. More... | |
| TIB_API void | tibEventQueue_DestroyTimer (tibEx e, tibEventQueue queue, tibTimer timer, tibTimerComplete completeCb) |
| Stop and destroy a timer. More... | |
| TIB_API void | tibEventQueue_Dispatch (tibEx e, tibEventQueue queue, tibdouble_t timeout) |
| Dispatch events. More... | |
| TIB_API tibint64_t | tibEventQueue_GetCount (tibEx e, tibEventQueue id) |
| Get the number of events in the queue. More... | |
| TIB_API tibint32_t | tibEventQueue_GetName (tibEx e, tibEventQueue id, char *buf, tibint32_t size) |
| Return the name of the event queue. More... | |
| TIB_API void | tibEventQueue_RemoveSubscriber (tibEx e, tibEventQueue queue, tibSubscriber subscriber, tibSubscriberComplete completeCb) |
| Remove a subscriber from a queue. More... | |
| TIB_API void | tibEventQueue_RunDispatch (tibEx e, tibEventQueue queue, tibProperties props) |
| Start a thread to dispatch events. More... | |
Event queue objects hold message and timer events until callbacks can process them.
This file defines queues, callback types, calls that funnel events to queues, and a call that dispatches events to callbacks.
This file also defines timer events, and calls that manipulate them.
| #define TIB_EVENTQUEUE_PROPERTY_BOOL_INLINE_MODE "com.tibco.ftl.client.inline" |
Inline mode (low-latency); boolean.
Programs that receive time-sensitive messages can use inline mode to favor low latency over high throughput. Inline mode reduces inbound message latency using inline transport I/O in the same thread as the message callback.
Inline mode requires that callbacks always return quickly; otherwise, long callbacks can delay message I/O (defeating the purpose of inline mode).
Inline mode could reduce the average number of messages in the vectors that the callback receives.
It is good practice to dispatch an inline queue from only one thread. Dispatching an inline-mode queue from several threads could result in actual wait times that are longer than the dispatch timeout arguments.
For example, if thread A dispatches with timeout 10 seconds, and thread B dispatches with timeout 15 seconds, then the timer for thread B does not start until after the dispatch call returns in thread A. The apparent timeout for thread B could be as long as 25 seconds.
When specifying inline mode, programmers must coordinate with administrators to avoid illegal state exceptions.
To enable inline mode, pass this property to tibEventQueue_Create with value tibtrue.
Otherwise, the default behavior disables inline mode.
| #define TIB_EVENTQUEUE_PROPERTY_INT_DISCARD_POLICY "com.tibco.ftl.client.discard.policy" |
Discard policy; integer.
This property determines the behavior of the queue on overflow (too many events). For legal values, see tibEventQueue_DiscardPolicy.
To enable discard on overflow, pass this property to tibEventQueue_Create with a value from tibEventQueue_DiscardPolicy.
Otherwise, the default behavior disables discard.
| #define TIB_EVENTQUEUE_PROPERTY_INT_DISCARD_POLICY_DISCARD_AMOUNT "com.tibco.ftl.client.discard.amount" |
Discard amount; integer.
When a queue overflows, this property determines the number of events to discard.
If you specify TIB_EVENTQUEUE_DISCARD_OLD, you may also specify this value. The value must be less than TIB_EVENTQUEUE_PROPERTY_INT_DISCARD_POLICY_MAX_EVENTS. When absent, the default value is 1.
If you specify TIB_EVENTQUEUE_DISCARD_NEW, then tibEventQueue_Create ignores this value. Discarding new events always discards exactly enough events so that the rest fit on the queue.
| #define TIB_EVENTQUEUE_PROPERTY_INT_DISCARD_POLICY_MAX_EVENTS "com.tibco.ftl.client.discard.max_events" |
Max events; integer.
When distributing an event to the queue would overflow this limit, the queue discards events.
If you specify a discard policy that could actually discard events, then you must also specify a value for this maximum.
| #define TIB_EVENTQUEUE_PROPERTY_STRING_NAME "com.tibco.ftl.client.queue.name" |
Queue name; string.
It is good practice to assign a unique name to each event queue (that is, unique within the program). If the queue discards events, the advisory message identifies the queue using this name, which can help diagnose the issue.
| #define TIB_TIMEOUT_NO_WAIT ((tibdouble_t) 0.0) |
Do not wait for an event.
When the queue is empty, the dispatch call returns immediately.
| #define TIB_TIMEOUT_WAIT_FOREVER ((tibdouble_t) -1.0) |
Wait indefinitely for an event.
When the queue is empty, the dispatch call waits for an event.
| typedef void(* tibEventQueueComplete)(tibEx e, tibEventQueue queue) |
Event queue completion callback.
When tibEventQueue_Destroy destroys a queue, the queue and the events in it might still be in use within callbacks or FTL library calls. Programs can define a completion callback of this type for cleanup operations that must wait until after all callbacks have completed.
The FTL library calls this completion callback when the queue is no longer needed. The completion callback could run in the thread that destroys the queue, or asynchronously in another (FTL internal) thread.
Programs must not dispatch any event queue from within any callback.
| e | FTL supplies callbacks with a clear exception object; your callback code may use it in its FTL API calls. When the completion callback returns, FTL does not examine the exception object for errors, nor does FTL return that exception to your program code. |
| queue | The event queue that was destroyed. |
| typedef void(* tibEventQueueCompleteEx)(tibEx e, tibEventQueue queue, void *closure) |
Event queue completion callback.
When tibEventQueue_Destroy destroys a queue, the queue and the events in it might still be in use within callbacks or FTL library calls. Programs can define a completion callback of this type for cleanup operations that must wait until after all callbacks have completed.
The FTL library calls this completion callback when the queue is no longer needed. The completion callback could run in the thread that destroys the queue, or asynchronously in another (FTL internal) thread.
Programs must not dispatch any event queue from within any callback.
| e | FTL supplies callbacks with a clear exception object; your callback code may use it in its FTL API calls. When the completion callback returns, FTL does not examine the exception object for errors, nor does FTL return that exception to your program code. |
| queue | The event queue that was destroyed. |
| closure | The closure supplied to tibEventQueue_DestroyEx. |
| typedef void(* tibMsgCallback)(tibEx e, tibEventQueue queue, tibint32_t msgCount, tibMessage *msgs, void **closures) |
Message dispatch callback.
Programs define callbacks of this type to process inbound messages. tibEventQueue_Dispatch invokes the callback, passing an array of messages paired with a parallel array of closure objects.
The messages can arrive through different subscribers. The only aspect they necessarily share is that they require the same callback to process them.
Programs must not dispatch any event queue from within any callback.
For more information about closure objects, see tibEventQueue_AddSubscriber.
Inbound messages in callbacks belong to the FTL library; programs must not destroy them.
| e | FTL supplies callbacks with a clear exception object; your callback code may use it in its FTL API calls. When the completion callback returns, FTL does not examine the exception object for errors, nor does FTL return that exception to your program code. |
| queue | The callback is processing messages from this queue. |
| msgCount | The number of messages in the array. |
| msgs | The array of messages to process. |
| closures | The array of subscriber-specific data. Each item corresponds to one message (with the same array index). |
| typedef void(* tibSubscriberComplete)(tibEx e, tibSubscriber subscriber, void *closure) |
Subscriber completion callback.
When tibEventQueue_RemoveSubscriber removes a subscriber from an event queue, the subscriber object might still be in use within a callback or an FTL library call. Similarly, a closure object might still be in use within a callback. Programs can define a completion callback of this type for cleanup operations that must wait until after a subscriber and closure are no longer needed (for example, closing a subscriber or freeing a closure).
The FTL library calls this completion callback when the subscriber and closure are no longer needed. The completion callback could run in the thread that removes the subscriber, or asynchronously in another (FTL internal) thread.
Programs must not dispatch any event queue from within any callback.
| e | FTL supplies callbacks with a clear exception object; your callback code may use it in its FTL API calls. When the completion callback returns, FTL does not examine the exception object for errors, nor does FTL return that exception to your program code. |
| subscriber | The subscriber that was removed. |
| closure | The closure associated with the subscriber. |
| typedef struct __tibTimerId* tibTimer |
A timer object queues an event when its interval elapses.
The interval repeats indefinitely; to stop it, the program must explicitly destroy the timer.
| typedef void(* tibTimerCallback)(tibEx e, tibEventQueue queue, tibTimer timer, void *closure) |
Event timer callback.
Programs define callbacks of this type to process timer events. tibEventQueue_Dispatch invokes the callback, passing the timer object and a closure object (see tibEventQueue_CreateTimer).
Programs must not dispatch any event queue from within any callback.
| e | FTL supplies callbacks with a clear exception object; your callback code may use it in its FTL API calls. When the completion callback returns, FTL does not examine the exception object for errors, nor does FTL return that exception to your program code. |
| queue | The callback is processing a timer event from this queue. |
| timer | The timer object that triggered the event. |
| closure | Timer-specific data. |
Timer completion callback.
When tibEventQueue_DestroyTimer removes a timer from an event queue, the timer object might still be in use within a callback or an FTL library call. Similarly, a closure object might still be in use within a callback. Programs can define a completion callback of this type for cleanup operations that must wait until after a timer and closure are no longer needed (for example, freeing a closure).
The FTL library calls this completion callback when the timer and closure are no longer needed. The completion callback could run in the thread that stops the timer, or asynchronously in another (FTL internal) thread.
Programs must not dispatch any event queue from within any callback.
| e | FTL supplies callbacks with a clear exception object; your callback code may use it in its FTL API calls. When the completion callback returns, FTL does not examine the exception object for errors, nor does FTL return that exception to your program code. |
| timer | The timer that was stopped. |
| closure | The closure associated with the timer. |
| TIB_API void tibEventQueue_AddSubscriber | ( | tibEx | e, |
| tibEventQueue | queue, | ||
| tibSubscriber | subscriber, | ||
| tibMsgCallback | callback, | ||
| void * | closure | ||
| ) |
Add a subscriber to a queue.
Adding a subscriber to a queue associates the two objects, which yields the following behavior: Each time the subscriber receives a message, it distributes an event to the queue. The event includes the inbound message, the callback, and the closure.
You can add a subscriber to at most one queue. If you have already added a subscriber to a queue, and you attempt to add it to another queue, this call throws an exception.
If you add several subscribers to the same queue, the queue merges their message streams.
| e | The exception object captures information about failures. |
| queue | The call adds the subscriber to this queue. |
| subscriber | The call adds this subscriber to the queue. |
| callback | Dispatching a message event invokes this callback. |
| closure | Dispatch passes this closure to the callback. |
| TIB_API tibEventQueue tibEventQueue_Create | ( | tibEx | e, |
| tibRealm | realm, | ||
| tibProperties | props | ||
| ) |
Create an event queue.
| e | The exception object captures information about failures. |
| realm | The realm object is the source of configuration information about the application, endpoints, transports and formats. |
| props | Optional. To omit, supply NULL.Properties configure event queue behavior. |
| TIB_API tibTimer tibEventQueue_CreateTimer | ( | tibEx | e, |
| tibEventQueue | queue, | ||
| tibdouble_t | interval, | ||
| tibTimerCallback | callback, | ||
| void * | closure | ||
| ) |
Create and start a timer.
This call creates a timer object and associates it with a queue. The timer places a timer event on the queue every interval seconds.
The interval repeats indefinitely; to stop it, the program must explicitly destroy the timer object.
Each time tibEventQueue_Dispatch dispatches a timer event, the callback processes the event.
| e | The exception object captures information about failures. |
| queue | The call associates the new timer with this queue. |
| interval | The timer places events on the queue at this repeating interval (in seconds). |
| callback | Dispatching a timer event invokes this callback. |
| closure | Dispatch passes this closure to the callback. |
| TIB_API void tibEventQueue_Destroy | ( | tibEx | e, |
| tibEventQueue | queue, | ||
| tibEventQueueComplete | completeCb | ||
| ) |
Destroy an event queue.
Destroying a queue object frees all the resources associated with the queue. (However, this call does not implicitly close subscribers associated with the queue.)
Best practice is to remove all subscribers before destroying the event queue. However, when this practice is not possible, you can still destroy the subscriber's closure in the event queue destroy completion callback.
| e | The exception object captures information about failures. |
| queue | The call destroys this queue. |
| completeCb | Optional. This completion callback runs after all running event callbacks have returned. NULL indicates no completion callback. |
| TIB_API void tibEventQueue_DestroyEx | ( | tibEx | e, |
| tibEventQueue | queue, | ||
| tibEventQueueCompleteEx | completeCb, | ||
| void * | closure | ||
| ) |
Destroy an event queue.
Destroying a queue object frees all the resources associated with the queue. (However, this call does not implicitly close subscribers associated with the queue.)
Best practice is to remove all subscribers before destroying the event queue. However, when this practice is not possible, you can still destroy the subscriber's closure in the event queue destroy completion callback.
| e | The exception object captures information about failures. |
| queue | The call destroys this queue. |
| completeCb | Optional. This completion callback runs after all running event callbacks have returned. NULL indicates no completion callback. |
| closure | The library passes this closure to the callback. |
| TIB_API void tibEventQueue_DestroyTimer | ( | tibEx | e, |
| tibEventQueue | queue, | ||
| tibTimer | timer, | ||
| tibTimerComplete | completeCb | ||
| ) |
Stop and destroy a timer.
This call stops a timer so it does not place additional timer events on the queue. It also attempts to remove from the queue any timer events (associated with the stopped timer) that have fired but are not yet processed. After the completion callback returns, the FTL library destroys the timer asynchronously.
| e | The exception object captures information about failures. |
| queue | The call disassociates the timer from this event queue. |
| timer | The call stops this timer. |
| completeCb | Optional. This completion callback runs after all timer event callbacks are complete. It is safe to destroy the timer's closure object within this callback. NULL indicates no completion callback. |
| TIB_API void tibEventQueue_Dispatch | ( | tibEx | e, |
| tibEventQueue | queue, | ||
| tibdouble_t | timeout | ||
| ) |
Dispatch events.
If the queue is not empty, this call scans events from the head of the queue to obtain a sequence of events that all contain the same callback. Scanning produces an array of messages, and a parallel array of closures. The dispatch call passes both arrays to the callback for processing.
If the queue is empty, the call can wait for events to arrive. The timeout parameter determines the maximum time it can wait. Note that this parameter does not guarantee a minimum wait time.
If the timeout elapses before an event arrives in the queue, then the dispatch call returns normally. The call does not indicate whether or not it actually dispatched an event.
| e | The exception object captures information about failures (during dispatch) and conveys it back to its caller. The exception does not carry information from the callback. |
| queue | The call dispatches events from this queue. |
| timeout | If the queue is empty, the call waits for an event. If an event does not arrive before this timeout (in seconds) elapses, the call returns. The constants TIB_TIMEOUT_WAIT_FOREVER and TIB_TIMEOUT_NO_WAIT are special values. |
| TIB_API tibint64_t tibEventQueue_GetCount | ( | tibEx | e, |
| tibEventQueue | id | ||
| ) |
Get the number of events in the queue.
The count includes both message events and timer events.
| e | The exception object captures information about failures. |
| id | The call gets the number of events in this queue. |
| TIB_API tibint32_t tibEventQueue_GetName | ( | tibEx | e, |
| tibEventQueue | id, | ||
| char * | buf, | ||
| tibint32_t | size | ||
| ) |
Return the name of the event queue.
| e | The exception object captures information about failures. |
| id | The call gets the name of this event queue. |
| buf | The call stores the name in this string buffer. |
| size | The program supplies the length of buffer (in bytes). |
| TIB_API void tibEventQueue_RemoveSubscriber | ( | tibEx | e, |
| tibEventQueue | queue, | ||
| tibSubscriber | subscriber, | ||
| tibSubscriberComplete | completeCb | ||
| ) |
Remove a subscriber from a queue.
Removing a subscriber from a queue dissociates the two objects. The subscriber no longer distributes message events to the queue. Message events that the subscriber has already distributed to the queue remain in the queue.
The completion callback runs asynchronously when the subscriber and closure are no longer needed – that is, after all the subscriber's events have been processed, and the callbacks have returned. It is safe to destroy the subscriber's closure within the completion callback, but not sooner.
Best practice is to remove all subscribers before destroying the event queue. However, when this practice is not possible, you can still destroy the subscriber's closure in the event queue destroy completion callback.
Associations between subscribers and queues are independent of one another; that is, removing one subscriber from a queue does not affect the association of other subscribers with that queue.
| e | The exception object captures information about failures. |
| queue | The call removes the subscriber from this queue. |
| subscriber | The call removes this subscriber from the queue. |
| completeCb | Optional. This completion callback runs after all events from the subscriber have been processed, and their callbacks have returned. NULL indicates no completion callback. |
| TIB_API void tibEventQueue_RunDispatch | ( | tibEx | e, |
| tibEventQueue | queue, | ||
| tibProperties | props | ||
| ) |
Start a thread to dispatch events.
This convenience function creates a background thread that repeatedly dispatches events from a queue. The dispatch thread runs until the program destroys the queue.
You may call this function multiple times with the same event queue, which results in multiple threads dispatching that queue. (However, multiple dispatch threads could be disadvantageous with inline mode queues; see documentation at TIB_EVENTQUEUE_PROPERTY_BOOL_INLINE_MODE.)
For precise control over thread behavior, do not use this convenience function; instead, use thread functions available on your target platform.
| e | The exception object captures information about failures during thread creation. (It does not convey information to or from the thread.) |
| queue | The thread dispatches events from this queue. |
| props | Reserved for future use. To ensure forward compatibility, programmers must supply NULL. |