event_counters(3K) DG/UX R4.11MU05 event_counters(3K)
NAME
eventcounters: lmaddtoecvalue, lmadvanceec, lmawaitevents,
lmconvertclockvaluetoecvalue,
lmconvertecvaluetoclockvalue, lmgetnextecvalue,
lmhaseventoccurred, lmincrementecvalue, lminitializeec,
lminitializesequencer, lmreadec, lmticketsequencer,
lmareecvaluesequal - handle event counters
SYNOPSIS
#include "/usr/src/uts/aviion/ii/ilm.h"
void lmaddtoecvalue (
lmecvalueptrtype ecvalueptr, READWRITE
uint32type addend READONLY
)
void lmadvanceec (
lmeventcountername ecname, READWRITE
)
booleantype lmareecvaluesequal (
lmecvaluetype value1, READONLY
lmecvaluetype value2 READONLY
)
void lmawaitevents (
lmeventtype callereventlist[], READONLY
int32type callerlistsize, READONLY
int32ptrtype listindexptr WRITEONLY
)
lmecvaluetype lmconvertclockvaluetoecvalue (
miscclockvalueptrtype clockvalueptr READONLY
)
void lmconvertecvaluetoclockvalue (
lmecvaluetype ecvalue, READONLY
miscclockvalueptrtype clockvalueptr WRITEONLY
)
lmecvaluetype lmgetnextecvalue (
lmecptrtype ecname READONLY
)
booleantype lmhaseventoccurred (
lmeventptrtype eventptr READONLY
)
void lmincrementecvalue (
lmecvalueptrtype ecvalueptr READWRITE
)
void lminitializeec (
lmecptrtype ecname READONLY
)
void lminitializesequencer (
lmecptrtype seqname READONLY
)
lmecvaluetype lmreadec (
lmecptrtype ecname READONLY
)
void lmticketsequencer (
lmecptrtype seqname, READONLY
lmecvalueptrtype seqvalueptr WRITEONLY
)
where:
addend The value to be added to the event-counter value.
clockvalueptr A pointer to a clock value or to the location where
the clock value is to be written.
ecname A pointer to the event counter to be advanced,
initialized, or read.
ecvalueptr A pointer to an event-counter value or to the
location where the event-counter value (or the event-
counter value plus one) is to be written.
eventlist An array of events for which the LWP (Light-Weight
Process, or thread) will await.
eventptr A pointer to the subject event.
listindexptr A pointer to the array index (zero based) of an event
that is satisfied when the call returns.
listsize The number of elements in eventlist.
seqname A pointer to the sequencer to be initialized or
ticketed.
seqvalueptr A pointer to the location in which the new value of
the sequencer is to be written.
value1ptr A pointer to an event-counter value.
value2ptr A pointer to an event-counter value.
DESCRIPTION
The following routines are described in this man page:
f4lm_add_to_ec_value Add amount to event counter value
lmadvanceec Add one to an event counter and
awaken waiting LWPs.
lmawaitevents Perform await operation on one or
more events
lmconvertclockvaluetoecvalue Convert a clock value into an
event-counter value
lmconvertecvaluetoclockvalue Convert an event-counter value
into a clock value
lmgetnextecvalue Return event-counter value plus
one
lmhaseventoccurred Determine whether event has
occurred
lmincrementecvalue Increment event-counter value
lminitializeec Prepare an eventcounter for its
first use
lminitializesequencer Set sequencer to zero
lmreadec Read specified event counter
lmticketsequencer Add 1 to sequencer and return
value in variable
lmareecvaluesequal Compare two event-counter values
Overview to Using Event Counters
Event counters are one of the primary synchronization mechanism used
in the DG/UX kernel (see also eventflags(3K)). The DG/UX system's
treatment of event counters and the related concept of a sequencer
comes from work by Reed and Kanodia. See the Communications of the
ACM papers listed in the "Other Documents" section of the Preface to
Programming in the DG/UX Environment for more technical background on
event counters and sequencers.
The event-counter synchronization mechanism uses two basic elements:
event counters and events. An event counter is simply a count of the
number of times some condition of interest has happened. You create
an event counter by declaring a variable of event-counter type
(lmectype) and then initializing its count value to zero by calling
lminitializeec.
Events are separate from event counters. Event allow you to define
"events" of interest by connecting an event counter with a critical
value. When the eventcount is equal to the critical value, the event
is said to be "satisfied" and the kernel automatically awakens all
LWPs waiting on the event. You create an event by declaring a
variable of event type (lmeventtype) and filling in the name of the
event counter (pointer to its count address) and the critical value.
Typically, you will define an event counter globally and create
successive events from it.
Typically, you will also want to wait for the event to occur once you
have created it. You do this by calling lmawaitevents. The
lmawaitevents routine actually allows you to suspend while waiting
for any of a number of events supplied in an event list. If one or
more of the specified events is already satisfied when the await call
is made, await returns immediately and the LWP continues execution.
If none of the specified events is satisfied, the LWP enters the
awaiting state where it does not compete for CPU resources. Because
a LWP doing a lmawaitevents may suspend indefinitely, it should
only hold locks while awaiting an event that can be counted on
occurring in a reasonable time (perhaps a second or less).
When one of the events is satisfied, the kernel will awaken the
waiting LWP and pass it the index of the event that has occurred.
The index identifies the event in the list that caused the await to
be satisfied. However, the event specified by the index is not
necessarily the only event that has occurred in the list. You may
determine if other events in the list have occurred by calling the
routine lmhaseventoccurred for each entry in the event list. Note
that if you want to wait until ALL of the desired events have
occurred, you may need to do several calls to lmawaitevents,
reconstructing a shortened list of events each time.
Frequently, the event you will want to create is the next occurrence
of the condition, that is, the next increment of the event counter
(however, if this is the case, also consider using an eventflag; see
eventflags(3K)). You can create such an event by: 1) calling
lmreadec which reads the current count into an event value
variable; and 2) calling lmincrementec which adds one to that count
value--making a critical value equal to "the next occurrence."
Alternatively, you can call lmgetnextecvalue to perform these two
steps in one indivisible step; it reads and returns an incremented
count into an event value variable.
Some part of your code will also have to advance the event counter
each time the condition of interest occurs. You advance the event
counter by calling lmadvanceec. After incrementing the specified
event counter, the advance operation checks to see whether the new
value of the incremented event counter causes any events to be
satisfied. If the LWP associated with a satisfied event is still in
the awaiting state, it is scheduled to run. Because interrupts are
one common condition of interest, interrupt service routines are
frequently the ones calling lmadvanceec.
Because event counters are monotonically increasing values, they map
very well into the normal concepts of clocks and times. This allows
clocks routines and timer routines to be based on the same event-
counter mechanism. A clock can be considered an event counter, and
when the clock reaches a certain value an event is triggered. The
two routines lmconvertclockvaluetoecvalue and
lmconvertecvaluetoclockvalue allow you to convert between clock
and event-counter values.
Because event counters are monotonically increasing values, they also
provide a natural ordering of events. This allows the event-counter
mechanism to be extended to support sequencing using the concept of
"sequencers." Often simply waiting on an event is not enough; what
is wanted is a way of ordering, or sequencing, the waiters on an
event. This is often the case when the event being awaited is access
to a resource of some sort, such as a critical section of code or
shared data. Sequencers support such ordering.
Sequencers, like event counters, are simply counters with values that
increase in a monotonic fashion. Like event counters, sequencers are
declared and initialized (in sequencer's case, by calling
lminitializesequencer). Sequencers order events by issuing
sequential "tickets." You get a ticket by calling
lmticketsequencer which atomically increments the current value of
the sequencer and returns the new value. Thus, each caller of the
ticket operation gets a unique value and the values are ordered by
the order in which the calls to ticket were made: the first caller
will get 1, the second 2, and so on. You create events using these
ticket values and await them using lmawaitevents. Each LWP will
see its event in turn--in the same order as the sequencer values.
This is exactly the same as in any store where you "take a number for
service."
Event counters offer several advantages over the more simplistic
synchronizations techniques used in most standard UNIX
implementations. First, because event counters actually count the
number of occurrences of an event, you can tell if an event has
already happened. Thus, in a sense event counters remember previous
events. If code tries to wait on an event that has already happened
(the event's critical value is less than the current count), the wait
returns immediately because the event has been satisfied. There is
no danger of the waiting LWP pending forever as with the standard
UNIX sleep and wakeup primitives.
The lmareecvaluesequal routine for comparing event-counter values
is provided for convenience.
You must be careful of the order in which you perform the tasks
involved in creating and awaiting an event lest you accidentally
create an endless wait situation. Specifically, if you start the I/O
operation to be awaited before you create the event, the I/O may be
logged before you get the event counter and the condition you create
will be one count past the operation you started. The best sequence
for creating and awaiting events is: 1) create the event to be
awaited; 2) start the I/O operation; 3) check the event; 4) if it is
not satisfied (and you want to suspend until it is), start the await
process. The typical code sequence is as follows:
devcirdbuildscattergatherarrays(requestblockptr);
requestcompletionevent.name = &requestblockptr->syncioec;
lmgetnextecvalue(&requestblockptr->syncioec,
&requestcompletionevent.value);
status = devcirdstartcommandlistrequest(requestblockptr);
if (status == OK)
{
lmawaitevents(&requestcompletionevent,
(int32type)1,
&resultindex);
}
If you use routines from this man page, you must allocate the space
used by the event and event-counter instances (see the Constants and
Data Structures subsection below). Event counters may be allocated
from global memory or allocated dynamically. Event types are
allocated dynamically, as needed.
Constants and Data Structures
This subsection describes constants and data structures defined in
the include files cited in the SYNOPSIS section and used by the
routines documented in this man page.
Try to avoid dependencies on the specifics of these structures, such
as size or location of fields, because these specifics may change in
later releases of the software. You can verify exact variable
definitions in the appropriate include file. The best way to avoid
such dependencies is to use kernel-supplied routines to manipulate
these structures.
lmeventtype
typedef struct
{
lmecptrtype name;
lmecvaluetype value;
}
lmeventtype ;
This structure defines an event, which is an event counter name and
an event-counter value. The event is said to occur or to be
satisfied when the value of the event counter pointed to by the name
field is greater than or equal to the value field.
lmaddtoecvalue
This routine adds the given value to the specified event-counter
value. The specified 32-bit integer is added to the specified event-
counter value.
lmadvanceec
This routine performs an advance (by one) on the specified event
counter. Any LWPs awaiting on the new value of the event counter
will be notified.
The event counter is indivisibly incremented, and any LWPs awaiting
on the new value are notified. If a higher priority LWP becomes
eligible to run as a result of the notification, it may be
rescheduled. Thus, your LWP may be preempted if you call this
routine.
lmareecvaluesequal
This routine compares two event-counter values and returns TRUE if
they are equal.
lmawaitevents
This routine performs the await operation on one or more events. The
calling LWP will be suspended until at least one of the specified
events is satisfied.
If any of the events is satisfied at the time the call is made, the
LWP is not suspended. When the call returns, the listindexptr is
set to the index of an event that is satisfied, but if more than one
event is satisfied, no statement is made about which event will be
indicated by listindexptr.
lmconvertclockvaluetoecvalue
This routine converts a clock value into an event-counter value.
Converting from clock value to event-counter value requires
converting the 64-bit clock value to a 32-bit event-counter value.
The number of bits to take from the high and low word of the clock
value are defined in ilm.h as LMCLOCKTOECHIGHBITS and
LMCLOCKTOECLOWBITS.
lmconvertecvaluetoclockvalue
This routine converts an event-counter value into a clock value.
Conversion from event-counter value to clock value requires
converting a 32-bit event-counter value to a 64-bit clock value.
This routine uses the current time in calculating the high-order bits
of the clock value; converting an event-counter value that is too far
in the future or past will result in an incorrect result. The
permissible interval is defined by the value miscclockvaluetype
variable lmmaxclockecincrement, and is approximately 72 hours.
The number of bits to assign to the high and low word of the clock
value are defined in ilm.h as LMCLOCKTOECHIGHBITS and
LMCLOCKTOECLOWBITS.
lmgetnextecvalue
This routine indivisibly reads the specified event counter and
returns its value plus one.
The event counter is read indivisibly with respect to other
processors and with respect to the executing processor's interrupt
level. The value is then increased by one, which is equal to the
value that will be reached the next time the event counter is
advanced.
lmhaseventoccurred
This routine determines whether the given event has occurred.
lmincrementecvalue
This routine increments the specified event-counter value. The
routine simply takes the event-counter value passed in and increments
it. It does not cause any LWP to be awoken.
lminitializeec
This routine initializes an event counter to zero.
lminitializesequencer
This routine initializes a sequencer to zero.
lmreadec
This routine indivisibly reads the specified event counter and
returns the value in the variable pointed to by ecvalueptr.
The event counter is read indivisibly with respect to other
processors and with respect to the executing processor's interrupt
level.
lmticketsequencer
This routine indivisibly increments the value of the specified
sequencer and returns the new value (that is, the value after the
increment).
The sequencer value is incremented and then read as an indivisible
operation.
DIAGNOSTICS
Return Value
For lmareecvaluesequal:
TRUE The event-counter values are equal.
FALSE The event-counter values are not equal.
For lmhaseventoccurred:
TRUE The event has been satisfied.
FALSE The event has not yet occurred.
For the other routines: none.
Errors
None.
NOTES
An older family of routines, whose names start with "vp" is also
supported. The routines described here ("lm") are more efficient
and offer a slightly easier to use interface. The use of the vp
routines is deprecated.
SEE ALSO
systemclock(3K).
eventflags(3K).
Programming in the DG/UX Kernel Environment.
Licensed material--property of copyright holder(s)