Open topic with navigation

TIBCO Rendezvous® 8.8.0

# TibrvVectorListener::create()

Method

## Declaration

    TibrvStatus create (
        TibrvQueue* queue,
        TibrvVectorCallback* callback,
        TibrvTransport* transport,
        const char* subject,
        const void* closure = NULL);

## Purpose

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

## Remarks

This method creates a C vector listener and stores its handle in the C++ object.

Parameter | Description
`queue` | Place each inbound message on this event queue.
`callback` | On dispatch, process the message vector with this callback object. This object must be an instance of class TibrvVectorCallback.
`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 method 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 method 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.

## 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 object (though they need not match the same listener).

From these properties we can derive further inferences:

| • | If two vector listeners use the same callback object, 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 objects, 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 object, 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 object, 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 `PHU`. 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 222: 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 object 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 223: 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 224: 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.

## See Also

TibrvVectorListener::getSubject()

Did you find this helpful?

Yes No
Great!
Thanks for taking the time to give us some feedback.
Sorry about that

Why wasn't this helpful? (check all that apply)

Could not find what I was looking for
Instructions confusing or unclear
Instructions did not work

Want to tell us more?

Please select at least one option or provide details about the issue!!

Error occurred while submitting feedback.

Error2 occurred while submitting feedback.

TIBCO Rendezvous®

Copyright © 1997-2025. Cloud Software Group, Inc. All Rights Reserved.