e_sleepl 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_sleepl ( lock_word, event_word, flags) int *lock_word; tid_t *event_word; int flags;

Parameters

Item Description
lock_word Specifies the lock word for a conventional process lock.
event_word Specifies the shared event word. The kernel uses this word to anchor the list of kernel threads sleeping on this event. This event word must be initialized to EVENT_NULL before its first use.
flags Specifies the flags that control action on occurrence of a signal. These flags are found in the /usr/include/sys/sleep.h file.

Description

Note: The e_sleepl kernel service is provided for porting old applications written for previous versions of the operating system. Use the e_sleep_thread kernel service when writing new applications.

The e_sleepl kernel service waits for the specified shared event to occur. The kernel places the current kernel thread on the list anchored by the event_word parameter. The e_wakeup service wakes up all threads on the list.

The e_wakeup service does not wake up a thread that is not currently sleeping in the e_sleepl function. That is, if an e_wakeup operation for an event is issued before the thread calls the e_sleepl service for the event, the thread still sleeps, waiting on the next e_wakeup operation 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_sleepl service for the event has been called.

The e_sleepl service also unlocks the conventional lock specified by the lock_word parameter before putting the thread to sleep. It also reacquires the lock when the thread wakes up.

The anchor for the event list, specified by 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.

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

Values for the flags Parameter

The flags parameter controls how signals affect waiting for an event. There are three flags available to the e_sleepl service:

Item Description
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 also indicates the transfer of control to the return from the last setjmpx service with the return value set to EINTR.
EVENT_SHORT Indicates that signals cannot terminate the wait. Use the EVENT_SHORT flag for only short, guaranteed-to-wakeup sleeps.
Note: The EVENT_SIGRET flag overrides the EVENT_SIGWAKE flag.

Execution Environment

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

Return Values

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