tibrvEvent_CreateVectorListener()

Function

Declaration

tibrv_status tibrvEvent_CreateVectorListener(
    tibrvEvent*                event,
    tibrvQueue                 queue,
    tibrvEventVectorCallback   callback,
    tibrvTransport             transport,
    const char*                subject,
    const void*                closure);

Purpose

Listen for inbound messages, and receive them in a vector.

Parameter	Description
`event`	For each vector of inbound messages, place this event on the event queue. The program supplies a location, and the function stores the new event in that location. The event object remains valid until the program explicitly destroys it.
`queue`	For each vector of inbound messages, place the event on this event queue.
`callback`	On dispatch, process the event with this callback function.
`transport`	Listen for inbound messages on this transport.
`subject`	Listen for inbound messages with subjects that match this specification. Wildcard subjects are permitted. The empty string is not a legal subject name.
`closure`	Store this closure data in the event object.

Motivation

The standard way of receiving messages—one at a time—has the advantage of simplicity. However, if your application requires high throughput and low latency, consider receiving data messages in a vector instead. Vector listeners can boost performance for programs that receive a large number of messages by reducing the overhead associated with message dispatch. Applications that require high throughput (that is, many messages arriving rapidly) could benefit from vector listeners.

Warning

We do not recommend vector listeners for command messages, administrative messages, advisory messages, nor any other out-of-band purpose.

Activation and Dispatch

This function creates a vector listener event object, and activates the event—that is, it begins listening for all inbound messages with matching subjects. Dispatch removes a group of matching messages from the queue, and runs the callback function to process the message vector.

To stop receiving inbound messages on the subject, destroy the event object; this action cancels all messages already queued for the vector listener event; see also tibrvEvent_Destroy().

Interoperability

Vector listeners and ordinary listeners can listen on the same queue.

Grouping Messages into Vectors

When several vector listeners use the same queue, the dispatcher groups messages into vectors with the following properties:

•

The sequence of messages in a vector reflect consecutive arrival in the queue.

•

All messages in a vector share the same callback function (though they need not match the same listener).

From these properties we can derive further inferences:

•

If two vector listeners use the same callback function, then the dispatcher can group messages on their subjects into the same vector.

•

If two messages are adjacent in the queue, but require different callback functions, then the dispatcher cannot group them into the same vector.

Vector Listeners: Same Callback

Two vector listeners, F and P, listen on subjects FOO and PHU, respectively. Both F and P designate the same queue, Q1, and the same callback function, C1, to process their messages. In this situation, the dispatcher for Q1 can group messages on subjects FOO and PHU into the same vector (as long as the messages constitute a contiguous sequence within Q1).

Vector Listeners: Different Callbacks

Extend the previous example by adding a third vector listener, B, which listens on subject BAR. B designates the same queue, Q1, but uses a new callback function, C2 to process its messages. In this situation, the dispatcher for Q1 must group messages on subject BAR separately from messages on subjects FOO and PHU.

Suppose the Q1 contains 49 messages with subjects FOO or PHU, then 1 message with subject BAR, then 30 more messages with subjects FOO and s. Grouping Messages into Vectors shows this message queue. The dispatcher produces at least three separate events.

Because messages 49 and 50 require different callbacks, the dispatcher must close the vector of FOO and PHU messages at message 49, and start a new vector for message 50 with subject BAR. When the dispatcher encounters message 51 with subject FOO again, it closes the BAR vector after only one message, and starts a third vector for FOO.

Figure 186: Grouping Messages into Vectors

Vector Listeners: Mixing Vector and Ordinary Listeners

Altering the previous example, suppose that B is an ordinary listener, instead of a vector listener. B necessarily specifies a different callback function than F and P (because ordinary listeners and vector listeners require different callback types with different signatures).

The behavior of the dispatcher remains the same as in Vector Listeners: Different Callbacks.

Dispatch Order vs.
Processing Order

Messages dispatch in the order that they arrive in the queue. However, the order in which callbacks process messages can differ from dispatch order. The following examples illustrate this possibility by contrasting three scenarios.

Vector Listeners: Deliberately Processing Out of Order

The simplest callback (from the programmer’s perspective) processes the messages within a vector in order (that is, the order that dispatcher moves them from the queue into the vector, which mirrors the order in which the messages arrive in the queue). Nonetheless you could program a callback that processes messages in reverse order, or any other order (though one would need a convincing reason to do so).

Vector Listeners: Processing Message Vectors in a Single Dispatcher Thread

Vector Listener Callbacks in a Single Dispatch Thread shows a closer look at the situation of Vector Listeners: Different Callbacks, in which several vector listeners all designate Q1 for their events. If a single thread dispatches Q1, then the callbacks are guaranteed to run in sequence. If the callbacks process messages in the order that they appear within the vectors, then message processing order is identical to dispatch order, which is also identical to arrival order. Vector Listener Callbacks in a Single Dispatch Thread shows this effect.

Figure 187: Vector Listener Callbacks in a Single Dispatch Thread

Vector Listeners: Processing Message Vectors in Separate Threads

However, if several threads dispatch Q1 in parallel, then the callbacks can run concurrently. In this situation, message processing order could differ dramatically from arrival order. Vector Listener Callbacks in Multiple Dispatch Threads shows this possibility.

Figure 188: Vector Listener Callbacks in Multiple Dispatch Threads

Although message number 49 dispatches (in event A) before message 50 (in event B), it is possible for the BAR callback (in thread B) to process message 50 before the FOO callback (in thread A) processes message 49. Furthermore, it is even possible for the FOO callback (in thread C) to process message 51 before the FOO callback (in thread A) processes message 49.

Note	Before developing a program that processes inbound message vectors in several threads, consider carefully whether it is important (in the context of your application’s semantics) to process messages in order of arrival.