1.\" 2.\" Copyright (c) 1996 Joerg Wunsch 3.\" 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd December 17, 1998 29.Os 30.Dt SLEEP 9 31.Sh NAME 32.Nm msleep , 33.Nm msleep_spin , 34.Nm tsleep , 35.Nm wakeup 36.Nd wait for events 37.Sh SYNOPSIS 38.In sys/param.h 39.In sys/systm.h 40.In sys/proc.h 41.Ft int 42.Fn tsleep "void *chan" "int priority" "const char *wmesg" "int timo" 43.Ft int 44.Fn msleep "void *chan" "struct mtx *mtx" "int priority" "const char *wmesg" "int timo" 45.Ft int 46.Fn msleep_spin "void *chan" "struct mtx *mtx" "const char *wmesg" "int timo" 47.Ft void 48.Fn wakeup "void *chan" 49.Ft void 50.Fn wakeup_one "void *chan" 51.Sh DESCRIPTION 52The functions 53.Fn tsleep , 54.Fn msleep , 55.Fn msleep_spin , 56.Fn wakeup , 57and 58.Fn wakeup_one 59handle event-based thread blocking. 60If a thread must wait for an 61external event, it is put to sleep by 62.Fn tsleep , 63.Fn msleep , 64or 65.Fn msleep_spin . 66The parameter 67.Fa chan 68is an arbitrary address that uniquely identifies the event on which 69the thread is being asleep. 70All threads sleeping on a single 71.Fa chan 72are woken up later by 73.Fn wakeup , 74often called from inside an interrupt routine, to indicate that the 75resource the thread was blocking on is available now. 76.Pp 77The parameter 78.Fa wmesg 79is a string describing the sleep condition for tools like 80.Xr ps 1 . 81Due to the limited space of those programs to display arbitrary strings, 82this message should not be longer than 6 characters. 83.Pp 84The 85.Fn wakeup_one 86function is used to make the first thread in the queue that is 87sleeping on the parameter 88.Fa chan 89runnable. 90This can prevent the system from becoming saturated 91when a large number of threads are sleeping on the same address, 92but only one of them can actually do any useful work when made 93runnable. 94.Pp 95The 96.Fn msleep 97function is the general sleep call. 98It suspends the current thread until a wakeup is 99performed on the specified identifier. 100The 101.Fa mtx 102parameter is a mutex which will be released before sleeping and reacquired 103before 104.Fn msleep 105returns. 106If 107.Fa priority 108includes the 109.Dv PDROP 110flag, the 111.Fa mtx 112parameter will not be reacquired before returning. 113The mutex is used to ensure that a condition can be checked atomically, 114and that the current thread can be suspended without missing a 115change to the condition, or an associated wakeup. 116If 117.Fa priority 118is not 0, 119then the thread will be made 120runnable with the specified 121.Fa priority 122when it resumes. 123If 124.Fa timo 125is not 0, 126then the thread will sleep for at most 127.Fa timo 128\&/ hz seconds. 129If the 130.Va Giant 131lock is not held and 132.Fa mtx 133is 134.Dv NULL , 135then 136.Fa timo 137must be non-zero. 138If 139.Fa priority 140includes the 141.Dv PCATCH 142flag, signals are checked before and after sleeping, otherwise signals are 143not checked. 144The 145.Fn msleep 146function returns 0 if awakened, 147.Er EWOULDBLOCK 148if the timeout expires. 149If 150.Dv PCATCH 151is set and a signal needs to be delivered, 152.Er ERESTART 153is returned if the current system call should be restarted if 154possible, and 155.Er EINTR 156is returned if the system call should be interrupted by the signal 157(return 158.Er EINTR ) . 159.Pp 160The 161.Fn tsleep 162function is a variation on 163.Fn msleep . 164It is identical to invoking 165.Fn msleep 166with a 167.Dv NULL 168.Fa mtx 169parameter. 170.Pp 171The 172.Fn msleep_spin 173function is another variation on 174.Fn msleep . 175This function accepts a spin mutex rather than a default mutex for its 176.Fa mtx 177parameter. 178It is also more limited in that it does not accept a 179.Fa priority 180parameter. 181Thus, it will not change the priority of a sleeping thread, 182and it does not support the 183.Dv PDROP 184and 185.Dv PCATCH 186flags. 187.Sh RETURN VALUES 188See above. 189.Sh SEE ALSO 190.Xr ps 1 , 191.Xr malloc 9 , 192.Xr mi_switch 9 193.Sh HISTORY 194The sleep/wakeup thread synchronization mechanism is very old. 195It 196appeared in a very early version of 197.Ux . 198.Pp 199The 200.Fn tsleep 201function appeared in 202.Bx 4.4 . 203The 204.Fn wakeup_one 205function appeared in 206.Fx 2.2 . 207The 208.Fn msleep 209function appeared in 210.Fx 5.0 , 211and the 212.Fn msleep_spin 213function appeared in 214.Fx 7.0 . 215.Pp 216The 217.Fn sleep 218function used to be the traditional form. 219It did not let you specify a timeout or a 220.Fa wmesg , 221hence it was discontinued. 222.Sh AUTHORS 223.An -nosplit 224This manual page was written by 225.An J\(:org Wunsch Aq joerg@FreeBSD.org . 226