Copyright © Cloud Software Group, Inc. All Rights Reserved

Event Queues

When an event occurs, the event driver places the event object on an event queue, where it awaits dispatch to its callback function.

Programs create event queues to influence the dispatch order, and to distribute events among several program threads. For example, a program could assign messages to a set of queues based on subjects. Program threads can dispatch events from separate queues.

Maximum Events and Limit Policy

A creation parameter limits the maximum number of events that a queue can contain. Another creation parameter selects the queue’s policy for situations in which a new event would overflow the queue’s maximum event limit.

Limit Policy	Description
Discard None	Never discard events; use this policy when a queue has no limit on the number of events it can contain.
Discard First	Discard the first event in the queue (which would otherwise be the next event to dispatch).
Discard Last	Discard the last event in the queue.
Discard New	Discard the new event (which would otherwise cause the queue to overflow its maximum event limit).

Dispatch

Queue dispatch calls remove the event at the head of a queue, and run its callback function.

Three types of dispatch calls behave differently in situations where the queue is empty:

•	Timed dispatch blocks waiting for an event, but returns without dispatching anything if a waiting time limit is exceeded.

•	Ordinary dispatch blocks indefinitely, until the queue contains an event.

•	Polling dispatch does not block; if the queue is empty, it returns immediately.

 

 

We discourage programmers from depending on a one-to-one correspondence between dispatch and callback. Intuitively, one might expect that each successful dispatch call triggers an event callback. However, it is possible for a dispatch call to return successfully without a callback. For example, it might dispatch an event that is internal to Rendezvous software, rather than an event defined in your program.

Dispatcher Threads

Most programs dispatch events in a loop that includes one of the dispatch calls. For convenience, the Rendezvous API includes a call that creates a separate dispatcher thread. The dispatcher thread runs a loop to repeatedly dispatch events. Programs can use this convenience feature, or dispatch events in any other appropriate way. However, every program must dispatch its events.

 

Table 16 Dispatcher Threads 

C	tibrvDispatcher
C++	TibrvDispatcher
Java	TibrvDispatcher
.NET	Dispatcher

Queue Groups and Priority

Queue groups allow fine-grained control over dispatch order from a single blocking point. A group can contain any number of event queues; the relative priorities of the queues determine the order in which dispatch calls dispatch their events. A queue can belong to any number of groups, or none at all.

Queue group dispatch calls search the group’s queues in order of priority, and dispatch the head event from the first non-empty queue. If two or more queues have identical priorities, subsequent dispatch calls rotate through them in round-robin fashion.

Parallel to queue dispatch calls, two types of queue group dispatch calls behave differently in situations where the queue is empty:

•	Ordinary group dispatch blocks indefinitely, until any queue in the group contains an event.

•	Timed group dispatch blocks waiting for an event, but returns without dispatching anything if a waiting time limit is exceeded.

•	Polling group dispatch does not block; if all the queues in the group are empty, it returns immediately.

Default Queue

The Rendezvous open call automatically creates a default queue. Programs can use this queue for simplicity, or create their own queues, or do both.

The default queue can contain an unlimited number of events (and never discards an event). It has priority 1 (last priority), so in any queue group, it is always among the last queues to dispatch.

When any queue discards an event (which would otherwise have caused the queue to exceed its event limit), Rendezvous software presents a QUEUE.LIMIT_EXCEEDED advisory message.

Strategies for Using Queues and Groups

This section presents examples of several common uses of event queues and groups.

Default Queue Only

Use the default queue as the only event queue.

Programs migrating from Rendezvous 5 (and earlier) can use this technique to emulate the event dispatch system of earlier releases.

Figure 7 Default Event Queue

Prioritize Queues within a Group

Dispatch the group, rather than individual queues. Assign queue priorities to reflect the relative priorities of their events (1 indicates the lowest, or last, priority; larger integers indicate higher priority).

This technique ensures that important events dispatch before less important events. For example, you can always dispatch a timer queue before inbound message queues, or give priority to messages with specific subjects.

Figure 8 Prioritize Event Queues in a Group

Selectively Suspend Dispatch

Remove selected queues from a group to suspend dispatch of their events. Even when a queue has been removed from its group, events continue to accumulate. Normal dispatch resumes when you add the queue back into the group.

Figure 9 Remove Event Queues from a Group to Suspend Dispatch

Copyright © Cloud Software Group, Inc. All Rights Reserved