et_wait Kernel Service

Purpose

Forces the calling kernel thread to wait for the occurrence of an event.

Syntax

#include <sys/types.h> #include <sys/errno.h> #include <sys/sleep.h> unsigned long et_wait ( wait_mask, clear_mask, flags) unsigned long wait_mask; unsigned long clear_mask; int flags;

Parameters

Item Description
wait_mask Specifies the mask of events to await.
clear_mask Specifies the mask of events to clear.
flags Specifies the flags controling actions on occurrence of a signal.

The flags parameter is used to control how signals affect waiting for an event. There are two flag values:

EVENT_SIGRET
Causes the wait for the event to be ended by an unmasked signal and the return value set to EVENT_SIG.
EVENT_SIGWAKE
Causes the event to be ended by an unmasked signal and control transferred to the return from the last setjmpx call, with the return value set to EXSIG.
EVENT_SHORT
Prohibits the wait from being terminated by a signal. This flag should only be used for short, guaranteed-to-wakeup sleeps.
Note: The EVENT_SIGRET flag overrides the EVENT_SIGWAKE flag.

Description

The et_wait kernel service forces the calling kernel thread to wait for specified events to occur.

The wait_mask parameter indicates a mask, where each bit set equal to 1 represents an event for which the thread must wait. The clear_mask parameter indicates a mask of events that must clear when the wait is complete. Subsequent calls to the et_wait service return immediately unless you clear the bits, which ends the wait.

Note: The et_wait service can be called with interrupts disabled only if the event or lock word is pinned.

Strategies for Using et_wait

Calling the et_wait kernel service with the EVENT_SIGRET flag clears the the pending events field when the signal is received. If et_wait is called again by the same kernel thread, the thread waits indefinitely for an event that has already occurred. When this happens, the thread does not run to completion. This problem occurs only if the event and signal are posted at the same time.

To avoid this problem, use one of the following programming methods:

The et_wait service is also used to clear events without waiting for them to occur. This is accomplished by doing one of the following:

Because the et_wait service returns an event mask indicating those events that were actually cleared, these methods can be used to poll the events.

Execution Environment

The et_wait kernel service can be called from the process environment only.

Return Values

Upon successful completion, the et_wait service returns an event mask indicating the events that terminated the wait. If an EVENT_NDELAY value is specified, the returned event mask indicates the pending events that were cleared by this call. Otherwise, it returns the following error code:

Item Description
EVENT_SIG Indicates that the EVENT_SIGRET flag is set and the wait is terminated by a signal.