Guardian Procedure Calls Reference Manual

USEREVENT... Procedures
The USEREVENT... procedures operate on user events. User events are events that are defined by
an application process to facilitate cooperation and coordination with other processes on the same
CPU. One process defines and owns the event and can wait for the event to occur; other processes
can cause that occurrence, subject to security considerations.
User events can be used in two scenarios:
• Applications can use user events as a coordinating mechanism only, in which case the
applications wait on the events using the USEREVENT_WAIT_ procedure.
• Applications can use user events in conjunction with the other common wait and I/O completion
procedures, in which case the applications wait on both user events and file I/O completions
using the same interfaces. In this scenario, applications use:
1. USEREVENT_REGISTER_ for establishing a file number (userEventFilenum) to map
to the user event set.
2. USEREVENT_SET_ for defining the set of user events upon which the process is to wait
as described in step 3. USEREVENT_SET_ can be invoked multiple times as necessary.
USEREVENT_GET_ reports the set of events currently defined by USEREVENT_SET_.
3. AWAITIO[X|XL], FILE_AWAITIO64_, or FILE_COMPLETE[L]_ (also referenced in this
manual as the AWAITIO/FILE_COMPLETE_ family of procedures) for waiting for both
user events and file I/O completions. If these procedures return userEventFilenum,
their tag parameter identifies the highest priority completed event.
NOTE: Applications do not have to call USEREVENT_REGISTER_ before calling
USEREVENT_SET_; the two procedures are independent operations and can be called in either
sequence. However, both procedures must be called before the eventual file-oriented wait.
USEREVENT_AWAKE_ is used in both scenarios to cause events to occur in a target process on
the same CPU.
User events are represented as bit masks of a 32-bit field thereby supporting a maximum of 31
user events per process; the units bit is reserved for reporting a timeout. An event's bit location in
the 32-bit field determines its priority: the higher-order bit has the higher priority. For example, the
event designated by 0x00008000 has higher priority than the event designated by 0x000000040,
in the sense that if both events have occurred the higher one is reported first. It is the responsibility
of the application to appropriately order the events.
Each process owns two sets of user events, those upon which it can wait, and those that are pending
and not yet reported. The process that owns an event is its consumer; a process that causes the
event to occur is a producer. A process can play either or both roles with respect to various events.
For simplicity, consider two processes that are respectively consuming and producing the user
event designated by the bit mask value 0x400. The consuming process defines a user event set
including 0x400, and waits for that event to occur. The producing process calls
USEREVENT_AWAKE_ specifying the process handle of the consumer and passing that same mask,
to cause the event to occur. If the consumer process is currently waiting on that event, it is awakened
and provided the value 0x400 to identify the event. If the process is not currently waiting, that
event remains pending in the occurred state. When an event is reported, it is removed from the
pending set; the report is a bit mask containing the single bit for that event.
There are two ways for the consumer to wait: it can call USEREVENT_WAIT_ passing the mask
value, or it can call one of the AWAITIO/FILE_COMPLETE_ family of procedures. In the latter
scenario, the consumer must previously have called USEREVENT_REGISTER to acquire a
userEventFileNum, and called USEREVENT_SET_ to specify the wait mask. Typically, the
consumer passes file number -1 to wait on all outstanding file operations as well as the defined
set of user events. It could wait explicitly on the userEventFileNum, but that is tantamount to
calling USEREVENT_WAIT_ with the same mask.
1464 Guardian Procedure Calls (T-V)