Forces the calling kernel thread to wait for the occurrence of a shared event.
#include <sys/sleep.h>int e_sleep_thread ( event_word, lock_word, flags)
tid_t *event_word;
void *lock_word;
int flags;
| Item | Description |
|---|---|
| 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. |
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.
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.
| Flag | Description |
|---|---|
| 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.
| Item | Description |
|---|---|
| INTERRUPTIBLE | The signals must be checked while the kernel thread is sleeping. If a signal needs to be delivered, the thread is awakened. |
The e_sleep_thread kernel service return a value that indicate how the kernel thread was awakened. The following values are defined:
| Item | Description |
|---|---|
| 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. |
The e_sleep_thread kernel service can be called from the process environment only.