e_sleep Kernel Service

Purpose

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

Syntax

#include <sys/types.h> #include <sys/errno.h> #include <sys/sleep.h> int e_sleep ( event_word, flags) tid_t *event_word; int flags;

Parameters

Item	Description
event_word	Specifies the shared event word. The kernel uses the event_word parameter to anchor the list of processes sleeping on this event. The event_word parameter must be initialized to EVENT_NULL before its first use.
flags	Specifies the flags that control action on occurrence of signals. These flags can be found in the /usr/include/sys/sleep.h file. The flags parameter is used to control how signals affect waiting for an event. The following flags are available to the e_sleep service: EVENT_SIGRET Indicates the termination of the wait for the event by an unmasked signal. The return value is set to EVENT_SIG. EVENT_SIGWAKE Indicates the termination of the event by an unmasked signal. This flag results in the transfer of control to the return from the last setjmpx service with the return value set to EINTR. EVENT_SHORT Prohibits the wait from being terminated by a signal. This flag should only be used for short, guaranteed-to-wakeup sleeps.

Item

Description

event_word

Specifies the shared event word. The kernel uses the event_word parameter to anchor the list of processes sleeping on this event. The event_word parameter must be initialized to EVENT_NULL before its first use.

flags

Specifies the flags that control action on occurrence of signals. These flags can be found in the /usr/include/sys/sleep.h file. The flags parameter is used to control how signals affect waiting for an event. The following flags are available to the e_sleep service:

EVENT_SIGRET: Indicates the termination of the wait for the event by an unmasked signal. The return value is set to EVENT_SIG.
EVENT_SIGWAKE: Indicates the termination of the event by an unmasked signal. This flag results in the transfer of control to the return from the last setjmpx service with the return value set to EINTR.
EVENT_SHORT: Prohibits the wait from being terminated by a signal. This flag should only be used for short, guaranteed-to-wakeup sleeps.

Description

The e_sleep kernel service is used to wait for the specified shared event to occur. The kernel places the current kernel thread on the list anchored by the event_word parameter. This list is used by the e_wakeup service to wake up all threads waiting for the event to occur.

The anchor for the event list, the event_word parameter, must be initialized to EVENT_NULL before its first use. Kernel extensions must not alter this anchor while it is in use.

The e_wakeup service does not wake up a thread that is not currently sleeping in the e_sleep function. That is, if an e_wakeup operation for an event is issued before the process calls the e_sleep service for the event, the thread still sleeps, waiting on the next e_wakeup service for the event. This implies that routines using this capability must ensure that no timing window exists in which events could be missed due to the e_wakeup service being called before the e_sleep operation for the event has been called.

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

Execution Environment

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

Return Values

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