TSLEEP(9) BSD Kernel Developer's Manual TSLEEP(9)
tsleep, msleep, wakeup, wakeup_n, wakeup_one -- process context sleep and
tsleep(void *ident, int priority, const char *wmesg, int timo);
msleep(void *ident, struct mutex *mtx, int priority, const char *wmesg,
wakeup_n(void *ident, int count);
These functions implement voluntary context switching. tsleep() and
msleep() are used throughout the kernel whenever processing in the cur-
rent context cannot continue for any of the following reasons:
o The current process needs to await the results of a pending I/O
o The current process needs resources (e.g. memory) which are
o 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 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 msleep() function behaves just like tsleep(), but takes an additional
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 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(). 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 exam-
ple, 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.
tsleep() and msleep() 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 oth-
erwise. If they return as a result of a timeout, the return value is
These functions are implemented in the file sys/kern/kern_synch.c.
hz(9), mi_switch(9), timeout(9)
BSD January 22, 2014 BSD