Copyright © Cloud Software Group, Inc. All Rights Reserved

Listener Event Semantics

The arrival of an inbound message is an important event for most Rendezvous programs. It is also an instructive exemplar of an asynchronous event—the receiving program cannot know in advance when a particular message might arrive in the queue. To receive messages, programs create listener events, define callback functions to process the inbound messages, and dispatch events in a loop.

While a program is listening for messages, the event driver queues the listener event each time a message arrives with a matching subject name. Each appearance of the event in the queue leads to a separate invocation of its callback function. At any moment in time, an event queue can contain several references to the same listener event object—each reference paired with a different inbound message.

Each time the callback function runs, it receives an inbound message as an argument. The callback function must process the message in an appropriate application-specific fashion.

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).

 

Table 17 Listener Creation (Sheet 1 of 2)

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.)

Figure 10 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 10 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.

Destroying a Listener

A listening transport continues receiving inbound messages indefinitely, until the program destroys the listener event (or its supporting objects).

Destroying a listener’s transport or event queue invalidates the listener event; inbound messages specified by the event no longer arrive. An invalid listener cannot be repaired; the program must destroy and re-create it.

Copyright © Cloud Software Group, Inc. All Rights Reserved