TibrvListener

Class

Declaration

class TibrvListener : public TibrvEvent
    TibrvListener();             // Construct empty.
    virtual ~TibrvListener();    // Destroy and reclaim storage.

Purpose

Listen for inbound messages.

Remarks

A listener object continues listening for messages until the program destroys it.

The constructor creates a hollow object; the create method makes it operational.

The destructor calls the destroy method, unless the C object is already destroyed.

Destroying the queue or transport of a listener event automatically invalidates the listener as well.

Method

Description

TibrvListener::create()

Listen for inbound messages.

TibrvListener::getSubject()

Extract the subject from a listener event object.

TibrvListener::getTransport()

Extract the transport from a listener event object.

Inherited Methods

TibrvEvent::destroy()

TibrvEvent::getClosure()

TibrvEvent::getHandle()

TibrvEvent::getType()

TibrvEvent::getQueue()

TibrvEvent::isValid()

TibrvEvent::isListener()

TibrvEvent::isTimer()

TibrvEvent::isIOEvent()

Activation and Dispatch

When an inbound message on the transport has a destination subject that matches the listener subject, then the message triggers the event.

The method TibrvListener::create() creates a C 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 method 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 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 method is processing.

Figure 218: Listener Activation and Dispatch

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

Related Classes

TibrvEvent

TibrvCmListener