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.

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:

Use the EVENT_SHORT flag to prevent signals from waking the thread up.
Mask signals prior to the call of et_wait by using the limit_sigs kernel service. Then call et_wait. Invoke the sigprocmask call to restore the signal mask by using the mask returned previously by limit_sigs.

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:

Set the wait_mask parameter to EVENT_NDELAY.
Set the bits in the clear_mask parameter that correspond with the events to be cleared to 1.

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.