LTSLEEP(9)

LTSLEEP(9) | 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 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 determined 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.

March 22, 2014 | NetBSD 10.0