sleep Kernel Service

Purpose

Forces the calling kernel thread to wait on a specified channel.

Syntax

#include <sys/types.h>
#include <sys/errno.h>
#include <sys/pri.h>
#include <sys/proc.h>

int sleep ( chan, priflags) void *chan; int priflags;

Parameters

Item	Description
chan	Specifies the channel number. For the sleep service, this parameter identifies the channel to wait for (sleep on).
priflags	Specifies two conditions: The priority at which the kernel thread is to run when it is reactivated. Flags indicating how a signal is to be handled by the sleep kernel service.

The valid flags and priority values are defined in the /usr/include/sys/pri.h file.

Description

The sleep kernel service is provided for compatibility only and should not be invoked by new code. The e_sleep_thread or et_wait kernel service should be used when writing new code.

The sleep service puts the calling kernel thread to sleep, causing it to wait for a wakeup to be issued for the channel specified by the chan parameter. When the process is woken up again, it runs with the priority specified in the priflags parameter. The new priority is effective until the process returns to user mode.

All processes that are waiting on the channel are restarted at once, causing a race condition to occur between the activated threads. Thus, after returning from the sleep service, each thread should check whether it needs to sleep again.

The channel specified by the chan parameter is simply an address that by convention identifies some event to wait for. When the kernel or kernel extension detects such an event, the wakeup service is called with the corresponding value in the chan parameter to start up all the threads waiting on that channel. The channel identifier must be unique systemwide. The address of an external kernel variable (which can be defined in a device driver) is generally used for this value.

If the SWAKEONSIG flag is not set in the priflags parameter, signals do not terminate the sleep. If the SWAKEONSIG flag is set and the PCATCH flag is not set, the kernel calls the longjmpx kernel service to resume the context saved by the last setjmpx call if a signal interrupts the sleep. Therefore, any system call (such as those calling device driver ddopen, ddread, and ddwrite routines) or kernel process that does an interruptible sleep without the PCATCH flag set must have set up a context using the setjmpx kernel service. This allows the sleep to resume in case a signal is sent to the sleeping process.

Attention: The caller of the sleep service must own the kernel-mode lock specified by the kernel_lock parameter. The sleep service does not provide a compatible level of serialization if the kernel lock is not owned by the caller of the sleep service.

Execution Environment

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

Return Values

Item	Description
0	Indicates successful completion.
1	Indicates that a signal has interrupted a sleep with both the PCATCH and SWAKEONSIG flags set in the priflags parameter.