event_flags(3K) SDK R4.11 event_flags(3K)
NAME
eventflags: lminitializeeventflag, lmcleareventflag,
lmawaiteventflag, lmseteventflag, lmeventflagisclear,
lmeventflagisset, - handle event flags
SYNOPSIS
#include "/usr/src/uts/aviion/ii/ilm.h"
void lminitializeeventflag (
lmeventflagptrtype eventflagptr WRITEONLY
)
void lmcleareventflag (
uint32eptrtype eventflagptr READWRITE
)
void lmawaiteventflag (
volatile lmeventflagtype *eventflagptr, READWRITE
uint32etype timeoutsec, READONLY
booleantype allowinterrupts READONLY
)
void lmseteventflag (
uint32eptrtype eventflagptr READWRITE
)
booleantype lmeventflagisclear (
volatile lmeventflagtype *eventflagptr READONLY
)
booleantype lmeventflagisset (
lmeventflagptrtype eventflagptr READONLY
)
where:
eventflagptr A pointer to the eventflag to be used.
timeoutsec The number of seconds to wait before returning, or
LMAWAITFOREVERSEC.
allowinterrupts
A boolean indicating whether the LWP (Light-Weight
Process, or thread) should be allowed to proceed if a
software interrupt arrives.
DESCRIPTION
The following routines are described in this man page:
lminitializeeventflag Initialize a new eventflag.
lmcleareventflag Prepare eventflag before
initiating waitable activity.
lmawaiteventflag Have LWP wait until eventflag is
set, or timeout, or signal.
lmseteventflag Cause waiting LWP to proceed.
lmeventflagisclear Determine if event has not yet
occurred.
lmeventflagisset Determine if event has already
occurred.
Overview to Using Event Flags
Eventflags are one of the primary synchronization mechanisms used in
the DG/UX kernel. See also eventcounters(3K). Eventflags are more
efficient than eventcounters and should be used in place of
eventcounters whenever possible.
An eventflag is simply an indication as to whether or not some action
of interest has happened. You create an eventflag by declaring a
variable of eventflag type (lmeventflagtype) and then initializing
it by calling lminitializeeventflag. When the eventflag is set,
the kernel automatically awakens all LWPs waiting on the eventflag.
You cause a LWP to wait for an eventflag to be set by calling
lmawaiteventflag. The lmawaiteventflag routine actually allows
you to suspend waiting for an eventflag, (optionally) a specified
number of seconds, or (optionally) the arrival of a software
interrupt (signal). If the eventflag is already set, or a software
signal has already arrived (and the caller specifies that they are to
be honored) when the await call is made, await returns immediately
and the LWP continues execution. If none of the specified criteria
are satisfied, the process enters the awaiting state where it does
not compete for CPU resources. Because a process doing an
lmawaiteventflag may suspend indefinitely, it should hold locks
only 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 process. However, the calling process can be awakened
"spuriously", before any of the criteria have been satisfied. It is
the calling process's responsibility to examine the eventflag or in
some other way determine if it can now proceed or if it must re-await
the eventflag. You may determine if the eventflag has been set by
calling the routine lmeventflagisset.
Some part of your code will have to set the eventflag when the
condition of interest occurs. You set an eventflag by calling
lmseteventflag. After setting the specified eventflag, the set
operation checks to see whether any LWPs were awaiting this
eventflag. If any were, they are scheduled to run. Because
interrupts are one common condition of interest, interrupt service
routines are frequently the ones calling lmseteventflag.
Eventflags can be used in simple (but commonly occurring) situations
where the LWP that is going to await the occurrence of interest can
clear the eventflag with complete confidence that no other LWP can
possibly be waiting for this particular eventflag. If this is not
the case (i.e., if it's possible that some other LWP may be awaiting
the same eventflag), then an eventcounter must be used instead, with
each LWP awaiting a separate value of the eventcounter.
You must be careful of the order in which you perform the tasks
involved in clearing and awaiting an eventflag lest you accidentally
create an endless wait situation. Specifically, if you start the I/O
operation to be awaited before you clear the eventflag, the I/O may
complete (and the eventflag get set) before you clear the eventflag,
and the clear operation will erase all record of the I/O having
completed. The best sequence for clearing and awaiting eventflags
is:
1) clear the eventflag;
2) start the I/O operation;
3) check the eventflag;
4) if it is not set (and you do want to suspend until it is), await
the eventflag.
The typical code sequence is as follows:
devcirdbuildscattergatherarrays(requestblockptr);
lmcleareventflag(&requestblockptr->syncioef);
status = devcirdstartcommandlistrequest(requestblockptr);
if (status == OK)
{
lmawaiteventflag(&requestblockptr->syncioef,
DEVCIRDBASICTIMEOUTSECONDS,
FALSE);
}
If you use routines from this man page, you must allocate the space
used by the eventflag instance (type lmeventflagtype). Eventflags
may be allocated from global memory or dynamically, as needed.
lminitializeeventflag
This routine initialized an eventflag. It should be invoked before
the eventflag is used for anything else.
lmcleareventflag
This routine puts the eventflag into the clear state, to indicate
that the event has not yet occurred. It should be invoked before
initiating the action that will eventually be awaited.
lmawaiteventflag
This routine causes the calling LWP to be suspended until the
eventflag is set. If the eventflag is already set when this routine
is invoked, the LWP is not suspended. Additionally, a maximum number
of seconds to suspend may be specified; if that time limit expires,
the routine will return. If no such time limit is desired, the value
LMAWAITFOREVERSEC should be specified. These timeouts are
implemented imprecisely and may expire up to roughly a second early
or late. Additionally, a boolean parameter specifies whether or not
the arrival of a software signal should cause the suspension to be
interrupted and the LWP allowed to proceed, even without the
eventflag having been set or the timeout expired.
lmseteventflag
This routine causes the eventflag to be set, and any LWP awaiting the
eventflag to be scheduled for execution.
lmeventflagisclear
This routine returns TRUE if the eventflag is in the clear state
(indicating that the event has not yet occurred).
lmeventflagisset
This routine returns TRUE if the eventflag is in the set state
(indicating that the event has occurred).
NOTES
Do not depend on the value in the eventflag being intuitively
obvious; use the isclear and isset routines.
DIAGNOSTICS
Return Value
For lmeventflagisclear:
TRUE The eventflag is clear.
FALSE The eventflag is set.
For lmeventflagisset:
TRUE The eventflag is set.
FALSE The eventflag is clear.
For the other routines: none.
Errors
None.
SEE ALSO
eventcounters(3K).
Programming in the DG/UX Kernel Environment.
Licensed material--property of copyright holder(s)