273 lines
6.1 KiB
Groff
273 lines
6.1 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 February 27, 2007
|
|
.Os
|
|
.Dt SLEEP 9
|
|
.Sh NAME
|
|
.Nm msleep ,
|
|
.Nm msleep_spin ,
|
|
.Nm pause ,
|
|
.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 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 pause "const char *wmesg" "int timo"
|
|
.Ft int
|
|
.Fn tsleep "void *chan" "int priority" "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 pause ,
|
|
.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 ,
|
|
.Fn msleep_spin ,
|
|
or
|
|
.Fn pause .
|
|
The parameter
|
|
.Fa chan
|
|
is an arbitrary address that uniquely identifies the event on which
|
|
the thread is being put to sleep.
|
|
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 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 No / Va 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.
|
|
.Pp
|
|
The
|
|
.Fn pause
|
|
function is a wrapper around
|
|
.Fn tsleep
|
|
that suspends execution of the current thread for the indicated timeout.
|
|
The thread can not be awakened early by signals or calls to
|
|
.Fn wakeup
|
|
or
|
|
.Fn wakeup_one .
|
|
.Pp
|
|
The
|
|
.Fn wakeup_one
|
|
function makes the first thread in the queue that is sleeping on the
|
|
parameter
|
|
.Fa chan
|
|
runnable.
|
|
This reduces the load 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
|
|
Due to the way it works, the
|
|
.Fn wakeup_one
|
|
function requires that only related threads sleep on a specific
|
|
.Fa chan
|
|
address.
|
|
It is the programmer's responsibility to choose a unique
|
|
.Fa chan
|
|
value.
|
|
The older
|
|
.Fn wakeup
|
|
function did not require this, though it was never good practice
|
|
for threads to share a
|
|
.Fa chan
|
|
value.
|
|
When converting from
|
|
.Fn wakeup
|
|
to
|
|
.Fn wakeup_one ,
|
|
pay particular attention to ensure that no other threads wait on the
|
|
same
|
|
.Fa chan .
|
|
.Sh RETURN VALUES
|
|
See above.
|
|
.Sh SEE ALSO
|
|
.Xr ps 1 ,
|
|
.Xr malloc 9 ,
|
|
.Xr mi_switch 9
|
|
.Sh HISTORY
|
|
The functions
|
|
.Fn sleep
|
|
and
|
|
.Fn wakeup
|
|
were present in
|
|
.At v1 .
|
|
They were probably also present in the preceding
|
|
PDP-7 version of
|
|
.Ux .
|
|
They were the basic process synchronization model.
|
|
.Pp
|
|
The
|
|
.Fn tsleep
|
|
function appeared in
|
|
.Bx 4.4
|
|
and added the parameters
|
|
.Fa wmesg
|
|
and
|
|
.Fa timo .
|
|
The
|
|
.Fn sleep
|
|
function was removed in
|
|
.Fx 2.2 .
|
|
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 6.2 .
|
|
The
|
|
.Fn pause
|
|
function appeared in
|
|
.Fx 7.0 .
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
This manual page was written by
|
|
.An J\(:org Wunsch Aq joerg@FreeBSD.org .
|