Listening for Messages

Programs listen for messages by creating listener events. Each listener event object signifies that a specific transport is listening for messages that match a specific subject name (which may contain wildcards). The transport continues listening until the program destroys the listener object.

Receiving programs must define callback functions to process inbound messages. When a message arrives, Rendezvous software places the listening event on an event queue. The program dispatches the event to the listener’s callback function.

One listener can cause many invocations of its callback function, since many inbound messages can match the desired subject name.

Programs can listen several times on the same subject and transport. Each listener can specify the same callback function or different callback functions. If a program creates two listeners with the same subject and transport, each matching inbound message causes two events (and two callback invocations to process them).

Listener Creation

C

tibrvEvent_CreateListener()

tibrvcmEvent_CreateListener()

C++

TibrvListener::create()

TibrvCmListener::create()

Java

TibrvListener()

TibrvCmListener()

.NET

Listener

Listener.Destroy

Activation and Dispatch

Inbound messages on the transport that match the subject trigger the event.

Creating a listener event object automatically activates the event—that is, the transport begins listening for all inbound messages with matching subjects. When a message arrives, Rendezvous software places the event object and message on the event queue. Dispatch removes the event object from the queue, and runs the callback function to process the message. (To stop receiving inbound messages on the subject, destroy the event object; this action cancels all messages already queued for the listener event.)

Listener Activation and Dispatch illustrates that Rendezvous software does not deactivate the listener when it places new message events on the queue (in contrast to timer and I/O events, which are temporarily deactivated). Consequently, several messages can accumulate in the queue while the callback function is processing.

Figure 20: Listener Activation and Dispatch

When the callback function is I/O-bound, messages can arrive faster than the callback function can process them, and the queue can grow unacceptably long. In applications where a delay in processing messages is unacceptable, consider dispatching from several threads to process messages concurrently.