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 sleep , 33.Nm tsleep , 34.Nm asleep , 35.Nm await , 36.Nm wakeup 37.Nd wait for events 38.Sh SYNOPSIS 39.Fd #include <sys/param.h> 40.Fd #include <sys/systm.h> 41.Fd #include <sys/proc.h> 42.Ft int 43.Fn tsleep "void *ident" "int priority" "const char *wmesg" "int timo" 44.Ft int 45.Fn asleep "void *ident" "int priority" "const char *wmesg" "int timo" 46.Ft int 47.Fn await "int priority" "int timo" 48.Ft void 49.Fn wakeup "void *ident" 50.Ft void 51.Fn wakeup_one "void *ident" 52.Sh DESCRIPTION 53The functions 54.Fn tsleep 55and 56.Fn wakeup 57handle event-based process blocking. If a process must wait for an 58external event, it is put on sleep by 59.Nm tsleep . 60The parameter 61.Ar ident 62is an arbitrary address that uniquely identifies the event on which 63the process is being asleep. All processes sleeping on a single 64.Ar ident 65are woken up later by 66.Nm wakeup , 67often called from inside an interrupt routine, to indicate that the 68resource the process was blocking on is available now. 69.Pp 70The parameter 71.Ar wmesg 72is a string describing the sleep condition for tools like 73.Xr ps 1 . 74Due to the limited space of those programs to display arbitrary strings, 75this message should not be longer than 6 characters. 76.Pp 77The 78.Fn wakeup_one 79function is used to make the first process in the queue that is 80sleeping on the parameter 81.Fa ident 82runnable. This can prevent the system from becoming saturated 83when a large number of processes are sleeping on the same address, 84but only one of them can actually do any useful work when made 85runnable. 86.Pp 87.Nm Tsleep 88is the general sleep call. Suspends the current process until a wakeup is 89performed on the specified identifier. The process will then be made 90runnable with the specified 91.Ar priority . 92Sleeps at most 93.Ar timo 94\&/ hz seconds (0 means no timeout). If 95.Ar pri 96includes the 97.Dv PCATCH 98flag, signals are checked before and after sleeping, else signals are 99not checked. Returns 0 if awakened, 100.Dv EWOULDBLOCK 101if the timeout expires. If 102.Dv PCATCH 103is set and a signal needs to be delivered, 104.Dv ERESTART 105is returned if the current system call should be restarted if 106possible, and 107.Dv EINTR 108is returned if the system call should be interrupted by the signal 109.Pq return Dv EINTR . 110.Pp 111.Nm Asleep 112implements the new asynchronous sleep function. It takes the same arguments 113as 114.Fn tsleep 115and places the process on the appropriate wait queue, but 116.Fn asleep 117leaves the process runnable and returns immediately. The caller is then 118expected to, at some point in the future, call 119.Fn await 120to actually wait for the previously queued wait condition. 121If 122.Fn asleep 123is called several times, only the most recent call is effective. 124.Fn asleep 125may be called with an 126.Ar ident 127value of NULL 128to remove any previously queued condition. 129.Pp 130.Nm Await 131implements the new asynchronous wait function. When 132.Fn asleep 133is called on an identifier it associates the process with that 134identifier but does not block. 135.Fn await 136will actually block the process until 137.Fn wakeup 138is called on that identifier any time after the 139.Fn asleep . 140If 141.Fn wakeup 142is called after you 143.Fn asleep 144but before you 145.Fn await 146then the 147.Fn await 148call is effectively a NOP. 149If 150.Fn await 151is called multiple times without an intervening 152.Fn asleep , 153the 154.Fn await 155is effectively a NOP but will also call 156.Fn mswitch 157for safety. The 158.Fn await 159function allows you to override the priority and timeout values to be used. 160If the value -1 is specified for an argument, the value is taken from the 161previous 162.Fn asleep 163call. If -1 is passed for the priority you must be prepared to catch signal 164conditions if the prior call to 165.Fn asleep 166specified it in its priority. If -1 is passed for the timeout you must be 167prepared to catch a timeout condition if the prior call to 168.Fn asleep 169specified a timeout. When you use -1, it is usually a good idea to not make 170assumptions as to the arguments used by the prior 171.Fn asleep 172call. 173.Pp 174The 175.Fn asleep 176and 177.Fn await 178functions are mainly used by the kernel to shift the burden of blocking 179away from extremely low level routines and to push it onto their callers. 180This in turn allows more complex interlocking code to 181.Em backout 182of a temporary resource failure 183(such as lack of memory) in order to release major locks prior to actually 184blocking, and to then retry the operation on wakeup. This key feature is 185expected to be heavily used in SMP situations in order to allow code to make 186better use of spinlocks. A spinlock, by its very nature, cannot be used 187around code that might block. It is hoped that these capabilities will 188make it easier to migrate the SMP master locks deeper into the kernel. 189.Pp 190These routines may also be used to avoid nasty spl*() calls to get around 191race conditions with simple conditional test/wait interlocks. You simply 192call 193.Fn asleep 194prior to your test, then conditionally 195.Fn await 196only if the test fails. It is usually a good idea to cancel an 197.Fn asleep 198if you wind up never calling the related 199.Fn await , 200but it is not required. If you do not want to waste cpu calling 201.Fn asleep 202unnecessarily, you can surround the whole thing with a second test. The 203race condition is still handled by the inside 204.Fn asleep 205call. 206.Sh RETURN VALUES 207See above. 208.Sh SEE ALSO 209.Xr ps 1 , 210.Xr malloc 9 211.Sh HISTORY 212The sleep/wakeup process synchronization mechanism is very old. It 213appeared in a very early version of Unix. 214.Pp 215.Nm Tsleep 216appeared in 217.Bx 4.4 . 218.Pp 219.Nm Asleep/await 220first appeared in 221.Fx 3.0 222and is designed to shift the burden of blocking 223away from extremely low level routines and push it up to their callers. 224.Pp 225.Nm Sleep 226used to be the traditional form. It doesn't let you specify a timeout nor a 227.Ar wmesg , 228hence it has been discontinued. 229.Sh AUTHORS 230This man page has been written by 231.ie t J\(:org Wunsch. 232.el Joerg Wunsch. 233.Nm Asleep 234and 235.Nm await 236designed and written by 237.An Matthew Dillon. 238