EC2_$INTRO Domain/OS EC2_$INTRO
NAME
intro - Level 2 Eventcount Manager
SYNOPSIS (C)
#include <apollo/base.h>
#include <apollo/ec2.h>
SYNOPSIS (Pascal)
%include '/sys/ins/base.ins.pas';
%include '/sys/ins/ec2.ins.pas';
SYNOPSIS (FORTRAN)
%include '/sys/ins/base.ins.ftn'
%include '/sys/ins/ec2.ins.ftn'
DESCRIPTION
The ec2_$ (Level 2 Eventcount) calls create and manage eventcounts.
The following is a list of the ec2_$ calls.
ec2_$advance increment an eventcount
ec2_$init initialize an eventcount
ec2_$read return an eventcount value
ec2_$wait wait for an eventcount trigger
ec2_$wait_slow_io wait for an eventcount trigger during I/O
ec2_$wait_svc wait for an eventcount trigger or asyn-
chronous fault
Programs can use eventcounts to sychronize processes. A process typi-
cally synchronizes with another process by waiting on an eventcount that
is advanced by the other process.
There are two types of eventcounts: system eventcounts and user
eventcounts.
System eventcounts are created, initialized, and advanced by the system.
A program should not use ec2_$init and ec2_$advance with system
eventcounts. Each manager that uses eventcounts has a call that gets
pointers to the eventcounts maintained by the manager, which can then be
passed in a wait call.
User eventcounts are created, initialized, and advanced by user processes
and are typically kept in a file shared among all the processes that need
them. The eventcount file is mapped by each process with ms_$mapl and a
shared write lock, and the eventcounts initialized with ec2_$init.
Thereafter, the eventcounts in the file can be advanced with ec2_$advance
or read with ec2_$read by any process sharing the file. Only processes
on the same node can concurrently get shared write locks on a file, so
eventcounts cannot be shared across nodes.
A process waits on a system or user eventcount by passing a pointer to
the eventcount in a call to ec2_$wait, ec2_$wait_slow_io, or
ec2_$wait_svc. When the specified eventcount advances, the wait call
returns. The wait calls differ only in the way they respond to asynchro-
nous faults.
A program should not dereference an eventcount pointer and attempt to
access the contents of an eventcount directly; always use the ec2_$ calls
because even user-defined eventcounts are shared with the system, and
attempts to circumvent the eventcount interface will lead to unexpected
results.
Constants
ec2_$always_ready_ec
Replaces an eventcount pointer to indicate that the event is always
ready.
Data Types
ec2_$eventcount_t
An eventcount. The diagram below illustrates the ec2_$eventcount_t
data type.
15 0
______________________________________________________________
| value |
|_____________________________________________________________|
| value |
|_____________________________________________________________|
| awaiters |
|_____________________________________________________________|
| NOT USED |
______________________________________________________________
15 0
value
The value of the eventcount.
awaiters
Reserved for internal use by the eventcount manager.
ec2_$ptr_list_t
An array of up to 128 pointers to eventcounts.
ec2_$ptr_t
A pointer to an eventcount.
ec2_$val_list_t
An array of trigger values for each of the eventcounts in an
eventcount pointer list. Each trigger value is a positive integer.
Errors
ec2_$bad_eventcount
Bad eventcount.
ec2_$internal_error
Internal error.
ec2_$no_wait_entries
Internal table exhausted.
ec2_$wait_quit
An asynchronous fault was received while waiting on an eventcount.