SLEEP(9) BSD Kernel Developer's Manual SLEEP(9)NAME
tsleep, ssleep, lksleep, mtxsleep, zsleep, tsleep_interlock, wakeup,
wakeup_one — wait/sleep/block for events
SYNOPSIS
#include <sys/param.h>
#include <sys/serialize.h>
#include <sys/systm.h>
#include <sys/proc.h>
int
tsleep(void *ident, int flags, const char *wmesg, int timo);
int
ssleep(void *ident, struct spinlock *spin, int flags, const char *wmesg,
int timo);
int
lksleep(void *ident, struct lock *lock, int flags, const char *wmesg,
int timo);
int
mtxsleep(void *ident, struct mtx *mtx, int flags, const char *wmesg,
int timo);
int
zsleep(void *ident, struct lwkt_serialize *slz, int flags,
const char *wmesg, int timo);
void
tsleep_interlock(void *ident, int flags);
void
wakeup(void *ident);
void
wakeup_one(void *ident);
DESCRIPTION
The functions tsleep(), ssleep(), lksleep(), mtxsleep(), zsleep(), and
wakeup() handle event-based process blocking. If a process must wait for
an external event, it is put on sleep by tsleep(), ssleep(), lksleep(),
mtxsleep(), or zsleep().
The parameter ident is an arbitrary address that uniquely identifies the
event on which the process is being asleep. All processes sleeping on a
single ident are woken up later by wakeup(), often called from inside an
interrupt routine, to indicate that the resource the process/thread was
blocking on is available now.
The parameter wmesg is a string describing the sleep condition for tools
like ps(1). Due to the limited space of those programs to display arbi‐
trary strings, this message should not be longer than 6 characters.
The tsleep() function is general in its use and suspends the current
process/thread until a wakeup is performed on the specified identifier.
The process/thread will then be made runnable. The process/thread will
sleep at most timo / hz seconds (0 means no timeout). If flags contains
the PCATCH flag, signals are checked before and after sleeping, else sig‐
nals are ignored.
Tsleep_interlock() is similar to tsleep(), in that it queues a thread on
a sleep queue, but it does not actually put the thread to sleep. This
allows coupling tsleep with higher-level synchronization primitives. The
pattern is:
(acquire high level synchronization primitive)
(test condition of interest)
tsleep_interlock(ident, flags)
(release high level synchronization primitive)
tsleep(..., PINTERLOCK)
For example, to implement ssleep():
spin_lock_wr(&important_lock);
if (important_condition == 0) {
tsleep_interlock(ident, flags);
spin_unlock_wr(&important_lock);
tsleep(..., PINTERLOCK);
}
The ssleep() function works like tsleep() while at the same time releas‐
ing the exclusive (write) spinlock spin before sleeping and reacquiring
it before ssleep() returns. This is an atomic operation, which guaran‐
tees that a wakeup() interlocked by spin will not be missed.
The lksleep() function works like tsleep() while at the same time releas‐
ing the exclusive lockmgr lock lock before sleeping and reacquiring it
before lksleep() returns. This is an atomic operation, which guarantees
that a wakeup() interlocked by lock will not be missed.
The mtxsleep() function works like tsleep() while at the same time atomi‐
cally releasing the mutex mtx before sleeping and reacquiring it in
exclusive state before mtxsleep() returns.
The zsleep() function works like tsleep() while at the same time releas‐
ing the serializer slz before sleeping and reacquiring it before zsleep()
returns. This is an atomic operation, which guarantees that a wakeup()
interlocked by slz will not be missed.
The wakeup_one() function is used to make the first process/thread in the
queue that is sleeping on the parameter ident runnable. This can prevent
the system from becoming saturated when a large number of pro‐
cesses/threads are sleeping on the same address, but only one of them can
actually do any useful work when made runnable.
IMPLEMENTATION NOTES
Unlike FreeBSD, the tsleep() function in DragonFly ignores priority
information because it is not required by the LWKT subsystem. Sleeps
without the LWP_SINTR flag set are assumed to be disk-waits, otherwise
they are normal sleeps.
RETURN VALUES
The tsleep() function returns 0 if awakened, otherwise an appropriate
error code is returned.
FILES
The various sleep functions are in /sys/kern/kern_synch.c.
ERRORS
[EWOULDBLOCK] The timeout expired.
[ERESTART] A signal needs to be delivered and the system call
should be restarted if possible. This only happens if
PCATCH was set in flags.
[EINTR] The system call needs to be interrupted by the signal.
This only happens if PCATCH was set in flags.
SEE ALSOps(1), kmalloc(9), serializer(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.
ssleep() appeared in DragonFly 1.6, zsleep() in DragonFly 2.0, and
lksleep() and mtxsleep() in DragonFly 2.3.
AUTHORS
This manual page was written by Jörg Wunsch and modified for DragonFly by
Hiten Pandya ⟨hmp@dragonflybsd.org⟩
BSD April 12, 2010 BSD
