tibrvEvent_CreateListener()

Function

Declaration

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

Purpose

Listen for inbound messages.

Parameter	Description
`event`	For each inbound message, 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 inbound message, 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.

Activation and Dispatch

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

This function creates a listener event object, and activates the event—that is, it begins listening for all inbound messages with matching subjects. When a message arrives, Rendezvous software places the event object and message on its 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; see also tibrvEvent_Destroy().)

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 I/O events, which are temporarily deactivated). Consequently, several messages can accumulate in the queue while the callback function is processing.

Figure 180: 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.

Listening for Advisory Messages

Use this function to listen for advisory subjects. We recommend sending advisory message events to the default queue.

Inbox Listener