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. |
|
Note |
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.
|
C |
|
|
C++ |
|
|
Java |
|
|
.NET |
|
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.