NAME
ltsleep,
mtsleep,
tsleep,
wakeup —
process context sleep and
wakeup
SYNOPSIS
#include <sys/proc.h>
int
mtsleep(
wchan_t
ident,
pri_t
priority,
const char
*wmesg,
int timo,
kmutex_t *mtx);
int
tsleep(
wchan_t
ident,
pri_t
priority,
const char
*wmesg,
int timo);
void
wakeup(
wchan_t
ident);
DESCRIPTION
The interfaces described in this manual page are obsolete
and will be removed from a future version of the system.
The ltsleep()
interface has
been obsoleted and removed from the system.
Please see the
condvar(9),
mutex(9),
and
rwlock(9) manual
pages for information on kernel synchronisation primitives.
These functions implement voluntary context switching.
tsleep() and
mtsleep() are used throughout
the kernel whenever processing in the current context can not 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 function
wakeup() is 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() and
mtsleep() functions take
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 be
NULL
.
-
-
- 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 no wakeup(ident) has occurred,
and no signal (if PCATCH
was
set) was posted, tsleep() will return
EWOULDBLOCK
.
The
mtsleep() function takes an additional argument and flag:
-
-
- mtx
- A mutex(9)
representing the lock protecting the data-structures. On entry
mtsleep() will release the lock and re-acquire the lock
on return.
-
-
- priority
- If the flag
PNORELOCK
is OR'ed into
priority then mtsleep() will not
re-acquire the lock.
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() or
mtsleep(). 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.
RETURN VALUES
tsleep() and
mtsleep() return 0 if they
return as a result of a
wakeup(). If a
tsleep() and
mtsleep() 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
tsleep() and
mtsleep() return because of a timeout, the return value is
EWOULDBLOCK
.
MIGRATING TO CONDVAR
Note the conversion from tsleep/wakeup into
condvar(9) should not be done
mechanically i.e. “blindly”. Code logic should be understood
before changing, and it may also need to be revisited for the change. Please
also read the
condvar(9) man
page.
The
tsleep() and
mtsleep(), and
wakeup() pairs should generally be replaced by
cv_wait(9) /
cv_wait_sig(9) /
cv_timedwait(9) /
cv_timedwait_sig(9)
and
cv_signal(9) /
cv_broadcast(9) pairs. The
cv_wait*() variant to use can be determinded from looking at
the corresponding
tsleep() usage.
There are two arguments of interest:
timo and
priority. The
priority value may
have OR'ed the flag
PCATCH
.
The
PCATCH
flag means that the blocking thread should be
awoken on signal, and the sleep call should be replaced with
cv_wait_sig(9).
The
timo value, if it is not zero, indicates how long to
sleep, and the sleep call should be replaced with
cv_timedwait(9).
If both the
PCATCH
flag and a non-zero
timo value are specified, then
cv_timedwait_sig(9)
should be used.
A
mutex(9) (interlock) must be held
across
cv_wait() and
cv_broadcast() calls,
in order to protect state. Most old code will require the addition of locking,
whereas some will require amending to remove
PNORELOCK
.
SEE ALSO
sigaction(2),
condvar(9),
hz(9),
mutex(9),
rwlock(9)
HISTORY
The sleep/wakeup process synchronization mechanism is very old. It appeared in a
very early version of Unix.
tsleep() appeared in
4.4BSD.
ltsleep() appeared in
NetBSD 1.5.