8ba7a3578b
- Describe msleep() as the primary sleep function now rather than tsleep() and describe tsleep() and msleep_spin() as variations. - Try to make the description of msleep() a bit closer to English (sentences with actual subjects, etc.) - Document that a priority of 0 now prevents the thread's priority from being altered. - Add a history note for wakeup_one().
226 lines
5.3 KiB
Groff
226 lines
5.3 KiB
Groff
.\"
|
|
.\" Copyright (c) 1996 Joerg Wunsch
|
|
.\"
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
|
.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
|
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
|
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd December 17, 1998
|
|
.Os
|
|
.Dt SLEEP 9
|
|
.Sh NAME
|
|
.Nm msleep ,
|
|
.Nm msleep_spin ,
|
|
.Nm tsleep ,
|
|
.Nm wakeup
|
|
.Nd wait for events
|
|
.Sh SYNOPSIS
|
|
.In sys/param.h
|
|
.In sys/systm.h
|
|
.In sys/proc.h
|
|
.Ft int
|
|
.Fn tsleep "void *chan" "int priority" "const char *wmesg" "int timo"
|
|
.Ft int
|
|
.Fn msleep "void *chan" "struct mtx *mtx" "int priority" "const char *wmesg" "int timo"
|
|
.Ft int
|
|
.Fn msleep_spin "void *chan" "struct mtx *mtx" "const char *wmesg" "int timo"
|
|
.Ft void
|
|
.Fn wakeup "void *chan"
|
|
.Ft void
|
|
.Fn wakeup_one "void *chan"
|
|
.Sh DESCRIPTION
|
|
The functions
|
|
.Fn tsleep ,
|
|
.Fn msleep ,
|
|
.Fn msleep_spin ,
|
|
.Fn wakeup ,
|
|
and
|
|
.Fn wakeup_one
|
|
handle event-based thread blocking.
|
|
If a thread must wait for an
|
|
external event, it is put to sleep by
|
|
.Fn tsleep ,
|
|
.Fn msleep ,
|
|
or
|
|
.Fn msleep_spin .
|
|
The parameter
|
|
.Fa chan
|
|
is an arbitrary address that uniquely identifies the event on which
|
|
the thread is being asleep.
|
|
All threads sleeping on a single
|
|
.Fa chan
|
|
are woken up later by
|
|
.Fn wakeup ,
|
|
often called from inside an interrupt routine, to indicate that the
|
|
resource the thread was blocking on is available now.
|
|
.Pp
|
|
The parameter
|
|
.Fa wmesg
|
|
is a string describing the sleep condition for tools like
|
|
.Xr ps 1 .
|
|
Due to the limited space of those programs to display arbitrary strings,
|
|
this message should not be longer than 6 characters.
|
|
.Pp
|
|
The
|
|
.Fn wakeup_one
|
|
function is used to make the first thread in the queue that is
|
|
sleeping on the parameter
|
|
.Fa chan
|
|
runnable.
|
|
This can prevent the system from becoming saturated
|
|
when a large number of threads are sleeping on the same address,
|
|
but only one of them can actually do any useful work when made
|
|
runnable.
|
|
.Pp
|
|
The
|
|
.Fn msleep
|
|
function is the general sleep call.
|
|
It suspends the current thread until a wakeup is
|
|
performed on the specified identifier.
|
|
The
|
|
.Fa mtx
|
|
parameter is a mutex which will be released before sleeping and reacquired
|
|
before
|
|
.Fn msleep
|
|
returns.
|
|
If
|
|
.Fa priority
|
|
includes the
|
|
.Dv PDROP
|
|
flag, the
|
|
.Fa mtx
|
|
parameter will not be reacquired before returning.
|
|
The mutex is used to ensure that a condition can be checked atomically,
|
|
and that the current thread can be suspended without missing a
|
|
change to the condition, or an associated wakeup.
|
|
If
|
|
.Fa priority
|
|
is not 0,
|
|
then the thread will be made
|
|
runnable with the specified
|
|
.Fa priority
|
|
when it resumes.
|
|
If
|
|
.Fa timo
|
|
is not 0,
|
|
then the thread will sleep for at most
|
|
.Fa timo
|
|
\&/ hz seconds.
|
|
If the
|
|
.Va Giant
|
|
lock is not held and
|
|
.Fa mtx
|
|
is
|
|
.Dv NULL ,
|
|
then
|
|
.Fa timo
|
|
must be non-zero.
|
|
If
|
|
.Fa priority
|
|
includes the
|
|
.Dv PCATCH
|
|
flag, signals are checked before and after sleeping, otherwise signals are
|
|
not checked.
|
|
The
|
|
.Fn msleep
|
|
function returns 0 if awakened,
|
|
.Er EWOULDBLOCK
|
|
if the timeout expires.
|
|
If
|
|
.Dv PCATCH
|
|
is set and a signal needs to be delivered,
|
|
.Er ERESTART
|
|
is returned if the current system call should be restarted if
|
|
possible, and
|
|
.Er EINTR
|
|
is returned if the system call should be interrupted by the signal
|
|
(return
|
|
.Er EINTR ) .
|
|
.Pp
|
|
The
|
|
.Fn tsleep
|
|
function is a variation on
|
|
.Fn msleep .
|
|
It is identical to invoking
|
|
.Fn msleep
|
|
with a
|
|
.Dv NULL
|
|
.Fa mtx
|
|
parameter.
|
|
.Pp
|
|
The
|
|
.Fn msleep_spin
|
|
function is another variation on
|
|
.Fn msleep .
|
|
This function accepts a spin mutex rather than a default mutex for its
|
|
.Fa mtx
|
|
parameter.
|
|
It is also more limited in that it does not accept a
|
|
.Fa priority
|
|
parameter.
|
|
Thus, it will not change the priority of a sleeping thread,
|
|
and it does not support the
|
|
.Dv PDROP
|
|
and
|
|
.Dv PCATCH
|
|
flags.
|
|
.Sh RETURN VALUES
|
|
See above.
|
|
.Sh SEE ALSO
|
|
.Xr ps 1 ,
|
|
.Xr malloc 9 ,
|
|
.Xr mi_switch 9
|
|
.Sh HISTORY
|
|
The sleep/wakeup thread synchronization mechanism is very old.
|
|
It
|
|
appeared in a very early version of
|
|
.Ux .
|
|
.Pp
|
|
The
|
|
.Fn tsleep
|
|
function appeared in
|
|
.Bx 4.4 .
|
|
The
|
|
.Fn wakeup_one
|
|
function appeared in
|
|
.Fx 2.2 .
|
|
The
|
|
.Fn msleep
|
|
function appeared in
|
|
.Fx 5.0 ,
|
|
and the
|
|
.Fn msleep_spin
|
|
function appeared in
|
|
.Fx 7.0 .
|
|
.Pp
|
|
The
|
|
.Fn sleep
|
|
function used to be the traditional form.
|
|
It did not let you specify a timeout or a
|
|
.Fa wmesg ,
|
|
hence it was discontinued.
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
This manual page was written by
|
|
.An J\(:org Wunsch Aq joerg@FreeBSD.org .
|