[ Previous | Next | Contents | Home | Search ]
AIX Version 4.3 Kernel and Subsystems Technical Reference, Volume 1

e_sleep_thread Kernel Service

Purpose

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

Syntax

#include <sys/sleep.h>
int e_sleep_thread (event_word, lock_word, flags)
int *event_word;
void *lock_word;
int flags;

Parameters

event_word Specifies the shared event word. The kernel uses the event_word parameter as the anchor to the list of threads waiting on this shared event.
lock_word Specifies simple or complex lock to unlock.
flags Specifies lock and signal handling options.

Description

The e_sleep_thread kernel service forces the calling thread to wait until a shared event occurs. The kernel places the calling thread on the event list anchored by the event_word parameter. This list is used by the e_wakeup, e_wakeup_one, and e_wakeup_w_result kernel services to wakeup some or all threads waiting for the event to occur.

A lock can be specified; it will be unlocked when the kernel service is entered, just before the thread blocks. This lock can be a simple or a complex lock, as specified by the flags parameter. When the kernel service exits, the lock is re-acquired.

Flags

The flags parameter specifies options for the kernel service. Several flags can be combined with the bitwise OR operator. They are described below.

The four following flags specify the lock type. If the lock_word parameter is not NULL, exactly one of these flags must be used.

LOCK_HANDLER lock_word specifies a simple lock protecting a thread-interrupt or interrupt-interrupt critical section.
LOCK_SIMPLE lock_word specifies a simple lock protecting a thread-thread critical section.
LOCK_READ lock_word specifies a complex lock in shared-read mode.
LOCK_WRITE lock_word specifies a complex lock in exclusive write mode.

The following flag specify the signal handling. By default, while the thread sleeps, signals are held pending until it wakes up.

INTERRUPTIBLE The signals must be checked while the kernel thread is sleeping. If a signal needs to be delivered, the thread is awakened.

Return Values

The e_sleep_thread kernel service return a value that indicate how the kernel thread was awakened. The following values are defined:

THREAD_AWAKENED Denotes a normal wakeup; the event occurred.
THREAD_INTERRUPTED Denotes an interruption by a signal. This value can be returned even if the INTERRUPTIBLE flag is not set since it may be also generated by the e_clear_wait or e_wakeup_w_result kernel services.
THREAD_TIMED_OUT Denotes a timeout expiration. The e_sleep_thread has no timeout. However, the e_clear_wait or e_wakeup_w_result kernel services may generate this return value.
THREAD_OTHER Delineates the predefined system codes from those that need to be defined at the subsystem level. Subsystem should define their own values greater than or equal to this value.

Execution Environment

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

Implementation Specifics

The e_sleep_thread kernel service is part of the Base Operating System (BOS) Runtime.

Related Information

The e_wakeup, e_wakeup_one, or e_wakeup_w_result kernel services, e_block_thread kernel service, e_clear_wait kernel service.

Process and Exception Management Kernel Services in AIX Kernel Extensions and Device Support Programming Concepts.

Understanding Locking in AIX Kernel Extensions and Device Support Programming Concepts

Locking Kernel Services in AIX Kernel Extensions and Device Support Programming Concepts

[ Previous | Next | Contents | Home | Search ]