Guardian Procedure Calls Reference Manual

The consumer can wait on more than one event at a time (which is common), and the producer
can cause more than one event to occur at a time (which is unusual). If the intersection of the wait
set and the occurred-events set contains more than one event, the wait operation reports only the
highest-priority event to the consumer, which must iterate to consume all the events.
The paradigm by which the application causes and waits upon user events must be designed with
care. Typically, the consumer must deal with false positives (the event occurs, but the application
state implied by that occurrence is not present). The design must avoid false negatives (the
application state is present, but the event has not occurred), which can result in the consumer
waiting although there is something for it to do. For example, suppose the application has an input
queue in shared memory, and uses an event to indicate that there is now a message in the queue.
A typical paradigm has the consumer remove all the messages in the queue and then wait on the
event while the queue is empty; the producer puts something in the queue and then causes the
event if the queue had been empty. It’s possible for the consumer to see the message and take it
from the queue before the producer makes the awake call; the consumer will see that event the
next time it waits, but there may be nothing in the queue. The consumer must tolerate an occasional
false wake-up. This paradigm avoids the pathological situation in which the queue is nonempty,
but the consumer waits on the event indefinitely.
The application must properly manage whatever resource is being coordinated with the user event.
In the example above, operations on the shared-memory queue must be serialized with atomic
operations or a semaphore.
NOTE: The USEREVENT... procedures are supported on systems running H06.27 and later
H-series RVUs and J06.16 and later J-series RVUs.
USEREVENT... Procedures 1465