ltsleep(9)
- NetBSD Manual Pages
LTSLEEP(9) NetBSD Kernel Developer's Manual LTSLEEP(9)
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 cur-
rent 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'' condi-
tion 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 ker-
nel 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 sec-
onds. 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-struc-
tures. 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 sleep-
ing on the identifier ident as runnable. Eventually, each of the pro-
cesses 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 determined from looking at the corre-
sponding 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 sig-
nal, 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 addi-
tion 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.
NetBSD 10.99 March 22, 2014 NetBSD 10.99
Powered by man-cgi (2021-06-01).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.