diff options
Diffstat (limited to 'share/man/man9/sleep.9')
| -rw-r--r-- | share/man/man9/sleep.9 | 338 |
1 files changed, 338 insertions, 0 deletions
diff --git a/share/man/man9/sleep.9 b/share/man/man9/sleep.9 new file mode 100644 index 0000000..91a2121 --- /dev/null +++ b/share/man/man9/sleep.9 @@ -0,0 +1,338 @@ +.\" +.\" 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 12, 2009 +.Dt SLEEP 9 +.Os +.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 . +Threads may also wait using one of the locking primitive sleep routines +.Xr mtx_sleep 9 , +.Xr rw_sleep 9 , +or +.Xr sx_sleep 9 . +.Pp +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 priority +specifies a new priority for the thread as well as some optional flags. +If the new priority is not 0, +then the thread will be made +runnable with the specified +.Fa priority +when it resumes. +.Dv PZERO +should never be used, as it is for compatibility only. +A new priority of 0 means to use the thread's current priority when +it is made runnable again. +.Pp +If +.Fa priority +includes the +.Dv PCATCH +flag, signals are checked before and after sleeping, otherwise signals are +not checked. +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 ) . +If +.Dv PBDRY +flag is specified in addition to +.Dv PCATCH , +then the sleeping thread is not stopped while sleeping upon delivery of +.Dv SIGSTOP +or other stop action. +Instead, it is waken up, assuming that stop occurs on reaching a stop +point when returning to usermode. +The flag should be used when sleeping thread owns resources, for instance +vnode locks, that should be freed timely. +.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 parameter +.Fa timo +specifies a timeout for the sleep. +If +.Fa timo +is not 0, +then the thread will sleep for at most +.Fa timo No / Va hz +seconds. +If the timeout expires, +then the sleep function will return +.Er EWOULDBLOCK . +.Pp +Several of the sleep functions including +.Fn msleep , +.Fn msleep_spin , +and the locking primitive sleep routines specify an additional lock +parameter. +The lock will be released before sleeping and reacquired +before the sleep routine returns. +If +.Fa priority +includes the +.Dv PDROP +flag, then +the lock will not be reacquired before returning. +The lock 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. +In addition, all of the sleep routines will fully drop the +.Va Giant +mutex +(even if recursed) +while the thread is suspended and will reacquire the +.Va Giant +mutex before the function returns. +Note that the +.Va Giant +mutex may be specified as the lock to drop. +In that case, however, the +.Dv PDROP +flag is not allowed. +.Pp +To avoid lost wakeups, +either a lock should be used to protect against races, +or a timeout should be specified to place an upper bound on the delay due +to a lost wakeup. +As a result, +the +.Fn tsleep +function should only be invoked with a timeout of 0 when the +.Va Giant +mutex is held. +.Pp +The +.Fn msleep +function requires that +.Fa mtx +reference a default, i.e. non-spin, mutex. +Its use is deprecated in favor of +.Xr mtx_sleep 9 +which provides identical behavior. +.Pp +The +.Fn msleep_spin +function requires that +.Fa mtx +reference a spin mutex. +The +.Fn msleep_spin +function does not accept a +.Fa priority +parameter and thus does not support changing the current thread's priority, +the +.Dv PDROP +flag, +or catching signals via the +.Dv PCATCH +flag. +.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 +If the thread is awakened by a call to +.Fn wakeup +or +.Fn wakeup_one , +the +.Fn msleep , +.Fn msleep_spin , +.Fn tsleep , +and locking primitive sleep functions return 0. +Otherwise, a non-zero error code is returned. +.Sh ERRORS +.Fn msleep , +.Fn msleep_spin , +.Fn tsleep , +and the locking primitive sleep functions will fail if: +.Bl -tag -width Er +.It Bq Er EINTR +The +.Dv PCATCH +flag was specified, a signal was caught, and the system call should be +interrupted. +.It Bq Er ERESTART +The +.Dv PCATCH +flag was specified, a signal was caught, and the system call should be +restarted. +.It Bq Er EWOULDBLOCK +A non-zero timeout was specified and the timeout expired. +.El +.Sh SEE ALSO +.Xr ps 1 , +.Xr locking 9 , +.Xr malloc 9 , +.Xr mi_switch 9 , +.Xr mtx_sleep 9 , +.Xr rw_sleep 9 , +.Xr sx_sleep 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 . |
