e_wakeup, e_wakeup_one, or e_wakeup_w_result Kernel Service

Purpose

Notifies kernel threads waiting on a shared event of the event's occurrence.

Syntax 

#include <sys/types.h>
#include <sys/errno.h> 
#include <sys/sleep.h>
void e_wakeup ( event_word)
tid_t *event_word;
void e_wakeup_one ( event_word)
tid_t *event_word;
void e_wakeup_w_result ( event_word,  result)
tid_t *event_word;
int result;

Parameters

Item Description
event_word Specifies the shared event designator. The kernel uses the event_word parameter as the anchor to the list of threads waiting on this shared event.
result Specifies the value returned to the awakened kernel thread. The following values can be used:
THREAD_AWAKENED
Indicates a normal wakeup. This is the value automatically generated by the e_wakeup or e_wakeup_one kernel services.
THREAD_INTERRUPTED
Indicates an interrupted sleep. This value is usually generated by a signal delivery when the INTERRUPTIBLE flag is set.
THREAD_TIMED_OUT
Indicates a timeout expiration.
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.

Description

The e_wakeup and e_wakeup_w_result kernel services wake up all kernel threads sleeping on the event list anchored by the event_word parameter. The e_wakeup_one kernel service wakes up only the most favored thread sleeping on the event list anchored by the event_word parameter.

When threads are awakened, they return from a call to either the e_block_thread or e_sleep_thread kernel service. The return value depends on the kernel service called to wake up the threads (the wake-up kernel service):

  • THREAD_AWAKENED is returned if the e_wakeup or e_wakeup_one kernel service is called
  • The value of the result parameter is returned if the e_wakeup_w_result kernel service is called.

If a signal is delivered to a thread being awakened by one of the wake-up kernel services, and if the thread specified the INTERRUPTIBLE flag, the signal delivery takes precedence. The thread is awakened with a return value of THREAD_INTERRUPTED, regardless of the called wake-up kernel service.

The e_wakeup and e_wakeup_w_result kernel services set the event_word parameter to EVENT_NULL.

The e_wakeup, e_wakeup_one, and e_wakeup_w_result kernel services have no return values.

Execution Environment

The e_wakeup, e_wakeup_one, and e_wakeup_w_result kernel services can be called from either the process environment or the interrupt environment.

When called by an interrupt handler, the event_word parameter must be located in pinned memory.