NAME
tsleep
, msleep
,
rwsleep
, wakeup
,
wakeup_n
, wakeup_one
— process context sleep and
wakeup
SYNOPSIS
#include
<sys/param.h>
#include <sys/systm.h>
int
tsleep
(void
*ident, int
priority, const char
*wmesg, int
timo);
int
msleep
(void
*ident, struct mutex
*mtx, int priority,
const char *wmesg,
int timo);
int
rwsleep
(void
*ident, struct rwlock
*wl, int priority,
const char *wmesg,
int timo);
void
wakeup
(void
*ident);
void
wakeup_n
(void
*ident, int
count);
void
wakeup_one
(void
*ident);
DESCRIPTION
These functions implement voluntary context switching.
tsleep
(),
msleep
() and rwsleep
() are
used throughout the kernel whenever processing in the current context cannot
continue for any of the following reasons:
- The current process needs to await the results of a pending I/O operation.
- The current process needs resources (e.g. memory) which are temporarily unavailable.
- The current process wants access to data structures which are locked by other processes.
The
wakeup
(),
wakeup_n
(), and wakeup_one
()
functions are used to notify sleeping processes of possible changes to the
condition that caused them to go to sleep. Typically, an awakened process
will -- after it has acquired a context again -- retry the action that
blocked its operation to see if the “blocking” condition has
cleared.
The
tsleep
()
function takes the following arguments:
- ident
- An identifier of the “wait channel” representing the
resource for which the current process needs to wait. This typically is
the virtual address of some kernel data structure related to the resource
for which the process is contending. The same identifier must be used in a
call to
wakeup
() to get the process going again. ident should not beNULL
. - priority
- The process priority to be used when the process is awakened and put on
the queue of runnable processes. This mechanism is used to optimize
“throughput” of processes executing in kernel mode. If the
flag
PCATCH
is OR'ed into priority the process checks for posted signals before and after sleeping. - wmesg
- A pointer to a character string indicating the reason a process is
sleeping. The kernel does not use the string, but makes it available
(through the process structure field
p_wmesg
) for user level utilities such as ps(1). - timo
- If non-zero, the process will sleep for at most
timo/hz
seconds. If this amount of time elapses and nowakeup
(ident) has occurred, and no signal (ifPCATCH
was set) was posted,tsleep
() will returnEWOULDBLOCK
.
The
msleep
()
function behaves just like tsleep
(), but takes an
additional argument:
- mtx
- A mutex that will be unlocked when the process is safely on the sleep
queue. The mutex will be relocked at the end of msleep unless the
PNORELOCK
flag is set in the priority argument.
The
rwsleep
()
function behaves just like tsleep
(), but takes an
additional argument:
- wl
- A write lock that will be unlocked when the process is safely on the sleep
queue. The write lock will be relocked at the end of rwsleep unless the
PNORELOCK
flag is set in the priority argument.
The
wakeup
()
function will mark all processes which are currently sleeping on the
identifier ident as runnable. Eventually, each of the
processes will resume execution in the kernel context, causing a return from
tsleep
(). Note that processes returning from sleep
should always re-evaluate the conditions that blocked them, since a call to
wakeup
() merely signals a
possible
change to the blocking conditions. For example, when two or more processes
are waiting for an exclusive lock, only one of them will succeed in
acquiring the lock when it is released. All others will have to go back to
sleep and wait for the next opportunity.
The
wakeup_n
()
and
wakeup_one
()
functions behave similarly to wakeup
() except that
only count or one process, respectively, is marked
runnable.
RETURN VALUES
tsleep
(), msleep
()
and rwsleep
() return 0 if they return as a result of
a wakeup
(). If they return as a result of a signal,
the return value is ERESTART
if the signal has the
SA_RESTART
property (see
sigaction(2)), and EINTR
otherwise. If they
return as a result of a timeout, the return value is
EWOULDBLOCK
.
CODE REFERENCES
These functions are implemented in the file sys/kern/kern_synch.c.