TSLEEP(9) | Kernel Developer's Manual | TSLEEP(9)

# NAME

`tsleep`, `tsleep_nsec`, `msleep`, `msleep_nsec`, `rwsleep`, `rwsleep_nsec`, `wakeup`, `wakeup_n`, `wakeup_one` — process context sleep and wakeup

# SYNOPSIS

`#include <sys/param.h>`
`#include <sys/systm.h>`

`#define INFSLP UINT64_MAX`
`#define MAXTSLP (UINT64_MAX - 1)`

int
`tsleep`(void *ident, int priority, const char *wmesg, int timo);

int
`tsleep_nsec`(void *ident, int priority, const char *wmesg, uint64_t nsecs);

int
`msleep`(void *ident, struct mutex *mtx, int priority, const char *wmesg, int timo);

int
`msleep_nsec`(void *ident, struct mutex *mtx, int priority, const char *wmesg, uint64_t nsecs);

int
`rwsleep`(void *ident, struct rwlock *rwl, int priority, const char *wmesg, int timo);

int
`rwsleep_nsec`(void *ident, struct rwlock *rwl, int priority, const char *wmesg, uint64_t nsecs);

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 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 `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:

rwl
  A read- or write-lock that will be unlocked when the process is safely on the sleep queue. The lock will be relocked at the end of rwsleep unless the `PNORELOCK` flag is set in the priority argument.

The `tsleep_nsec`(), `msleep_nsec`(), and `rwsleep_nsec`() functions behave like their unsuffixed counterparts except that they accept a timeout in terms of nanoseconds. These functions will always sleep for at least one tick, even if nsecs is zero. If nsecs is equal to `INFSLP` these functions do not time out, otherwise they sleep for at least nsecs nanoseconds.

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`(), `tsleep_nsec`(), `msleep`(), `msleep_nsec`(), `rwsleep`(), and `rwsleep_nsec`() 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.

# SEE ALSO

hz(9), mi_switch(9), timeout(9)

March 31, 2022 | Debian