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
(const
volatile void *ident, int
flags, const char
*wmesg, int
timo);
int
ssleep
(const
volatile void *ident,
struct spinlock *spin,
int flags,
const char *wmesg,
int timo);
int
lksleep
(const
volatile void *ident,
struct lock *lock,
int flags,
const char *wmesg,
int timo);
int
mtxsleep
(const
volatile void *ident,
struct mtx *mtx,
int flags,
const char *wmesg,
int timo);
int
zsleep
(const
volatile void *ident,
struct lwkt_serialize
*slz, int flags,
const char *wmesg,
int timo);
void
tsleep_interlock
(const
volatile void *ident, int
flags);
void
wakeup
(const
volatile void *ident);
void
wakeup_one
(const
volatile void *ident);
DESCRIPTION
The functionstsleep
(),
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 arbitrary 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 signals are
ignored.
The
tsleep_interlock
()
function 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(..., flags | PINTERLOCKED, ...)
For example, to implement
ssleep
():
spin_lock(&important_lock); if (important_condition == 0) { tsleep_interlock(ident, flags); spin_unlock(&important_lock); tsleep(..., flags | PINTERLOCKED, ...); }
The
ssleep
()
function works like tsleep
() while at the same time
releasing the exclusive spinlock spin before sleeping
and reacquiring it before ssleep
() returns. This is
an atomic operation, which guarantees that a
wakeup
() interlocked by spin
will not be missed.
The
lksleep
()
function works like tsleep
() while at the same time
releasing 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
atomically 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
releasing 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
processes/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 ALSO
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>.