sleep(D3) sleep(D3)
NAME
sleep - suspend process execution pending occurrence of an
event
SYNOPSIS
#include <sys/types.h>
#include <sys/param.h>
#include <sys/ddi.h>
int sleep(caddr_t event, int priority);
Arguments
event
Kernel address signifying an event for which the caller
wishes to wait.
priority
A hint to the scheduling policy as to the relative
priority the caller wishes to be assigned while running
in the kernel after waking up.
DESCRIPTION
sleep suspends execution of a process to await certain events
such as reaching a known system state in hardware or software.
For instance, when a process wants to read a device and no
data are available, the driver may need to call sleep to wait
for data to become available before returning. This causes
the kernel to suspend execution of the process that called
sleep and schedule another process. The process that called
sleep can be resumed by a call to the wakeup function with the
same event specified as that used to call sleep.
Return Values
sleep returns 0 if the caller woke up because of a call to
wakeup, or if the caller was stopped by a job control signal
and subsequently continued. If the sleep is interrupted by a
signal that does not cause the process to be stopped and the
priority argument includes the PCATCH flag, the sleep call
returns a value of 1. If the sleep is interrupted by a signal
and the PCATCH flag is not set, the process will longjmp out
of the driver and the sleep call will never return to the
calling code.
USAGE
event Argument
The address has no significance except that the same address
must be passed to wakeup(D3) to resume the sleeping process.
Copyright 1994 Novell, Inc. Page 1
sleep(D3) sleep(D3)
The address used should be the address of a kernel data
structure associated with the driver, or one of the driver's
own data structures. Use of arbitrary addresses not
associated with a private data structure can result in
conflict with other, unrelated sleep and wakeup operations in
the kernel.
priority Argument
Valid values for priority are 0 through 39 inclusive. In
general, a lower value will result in more favorable
scheduling although the exact semantic of the priority
argument is specific to the scheduling class of the caller,
and some scheduling classes may choose to ignore the argument
for the purposes of assigning a scheduling priority.
In addition to the scheduling semantics, the value of the
priority argument determines whether the sleep may be
interrupted by signals. If the value of priority is less than
or equal to the value of the constant PZERO (defined in
sys/param.h), the sleeping process will not be awakened by a
signal. If the value of priority is greater than PZERO and
the PCATCH bit flag is ORed into the priority argument, the
process will wake up prematurely (without a call to wakeup)
upon receipt of a non-ignored, non-held signal and will
normally return 1 to the calling code. If priority is greater
than PZERO and PCATCH is not set, the sleep function will
longjmp out of the driver upon receipt of a signal and will
never return to the caller.
General Considerations
If a process were to sleep while it is manipulating global
data inside a critical section of driver code, it would be
possible for another process to execute base level driver code
which manipulates the same data while the first process was
sleeping, resulting in data corruption. A driver should not
sleep inside such a critical section unless it takes explicit
steps to prevent concurrent access to the data (for example,
the driver could implement its own locking protocol to protect
the data).
The value for priority should be selected based on whether or
not a wakeup is certain to occur as well as the importance of
the driver and of any resources that the driver will hold
after waking up. If the driver is holding or waiting for a
critical kernel resource or is otherwise crucial to the
performance of the system, and the corresponding call to
wakeup is guaranteed to happen, the driver should specify a
Copyright 1994 Novell, Inc. Page 2
sleep(D3) sleep(D3)
priority argument less than or equal to PZERO. If the driver
is less performance critical or it is possible that the wakeup
may not occur, the driver should specify a priority argument
greater than PZERO.
If there is any driver state that needs to be cleaned up in
the event of a signal, the driver should OR the PCATCH flag in
with the priority argument. Typical items that need cleaning
up are locked data structures that should be unlocked or
dynamically allocated resources that need to be freed. When
PCATCH is specified sleep will normally return a 1 in the
event of a signal, indicating that the calling routine should
perform any necessary cleanup and then return.
If sleep is called from the driver strategy(D2) routine, the
caller should OR the priority argument with PCATCH or select a
priority of PZERO or less.
Level
Base only.
Synchronization Constraints
Can sleep.
REFERENCES
wakeup(D3)
NOTICES
Portability
All processors
Applicability
ddi: 1, 2, 3, 4, 5, 6
SV_WAIT(D3) and SV_WAIT_SIG(D3) replace sleep.
Copyright 1994 Novell, Inc. Page 3