| sleep.9 (c4d9468ea0e627c69802bd0689c93527dc2e2a85) | sleep.9 (b4e95913f75b8fdae825596be4e912fd91d66f02) |
|---|---|
| 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: --- 18 unchanged lines hidden (view full) --- 27.\" " 28.Dd December 17, 1998 29.Os 30.Dt SLEEP 9 31.Sh NAME 32.Nm sleep , 33.Nm msleep , 34.Nm tsleep , | 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: --- 18 unchanged lines hidden (view full) --- 27.\" " 28.Dd December 17, 1998 29.Os 30.Dt SLEEP 9 31.Sh NAME 32.Nm sleep , 33.Nm msleep , 34.Nm tsleep , |
| 35.Nm asleep , 36.Nm await , | |
| 37.Nm wakeup 38.Nd wait for events 39.Sh SYNOPSIS 40.Fd #include <sys/param.h> 41.Fd #include <sys/systm.h> 42.Fd #include <sys/proc.h> 43.Ft int 44.Fn tsleep "void *ident" "int priority" "const char *wmesg" "int timo" 45.Ft int 46.Fn msleep "void *ident" "struct mtx *mtx" "int priority" "const char *wmesg" "int timo" | 35.Nm wakeup 36.Nd wait for events 37.Sh SYNOPSIS 38.Fd #include <sys/param.h> 39.Fd #include <sys/systm.h> 40.Fd #include <sys/proc.h> 41.Ft int 42.Fn tsleep "void *ident" "int priority" "const char *wmesg" "int timo" 43.Ft int 44.Fn msleep "void *ident" "struct mtx *mtx" "int priority" "const char *wmesg" "int timo" |
| 47.Ft int 48.Fn asleep "void *ident" "int priority" "const char *wmesg" "int timo" 49.Ft int 50.Fn await "int priority" "int timo" | |
| 51.Ft void 52.Fn wakeup "void *ident" 53.Ft void 54.Fn wakeup_one "void *ident" 55.Sh DESCRIPTION 56The functions 57.Fn tsleep 58and --- 63 unchanged lines hidden (view full) --- 122includes the 123.Dv PDROP 124flag, the 125.Ar mtx 126parameter will not be entered before returning. The mutex is 127used to ensure that a condition can be checked atomicly, and 128that the current process can be suspended without missing a 129change to the condition, or an associated wakeup. | 45.Ft void 46.Fn wakeup "void *ident" 47.Ft void 48.Fn wakeup_one "void *ident" 49.Sh DESCRIPTION 50The functions 51.Fn tsleep 52and --- 63 unchanged lines hidden (view full) --- 116includes the 117.Dv PDROP 118flag, the 119.Ar mtx 120parameter will not be entered before returning. The mutex is 121used to ensure that a condition can be checked atomicly, and 122that the current process can be suspended without missing a 123change to the condition, or an associated wakeup. |
| 130.Pp 131.Nm Asleep 132implements the new asynchronous sleep function. It takes the same arguments 133as 134.Fn tsleep 135and places the process on the appropriate wait queue, but 136.Fn asleep 137leaves the process runnable and returns immediately. The caller is then 138expected to, at some point in the future, call 139.Fn await 140to actually wait for the previously queued wait condition. 141If 142.Fn asleep 143is called several times, only the most recent call is effective. 144.Fn asleep 145may be called with an 146.Ar ident 147value of NULL 148to remove any previously queued condition. 149.Pp 150.Nm Await 151implements the new asynchronous wait function. When 152.Fn asleep 153is called on an identifier it associates the process with that 154identifier but does not block. 155.Fn await 156will actually block the process until 157.Fn wakeup 158is called on that identifier any time after the 159.Fn asleep . 160If 161.Fn wakeup 162is called after you 163.Fn asleep 164but before you 165.Fn await 166then the 167.Fn await 168call is effectively a NOP. 169If 170.Fn await 171is called multiple times without an intervening 172.Fn asleep , 173the 174.Fn await 175is effectively a NOP but will also call 176.Fn mi_switch 177for safety. The 178.Fn await 179function allows you to override the priority and timeout values to be used. 180If the value -1 is specified for an argument, the value is taken from the 181previous 182.Fn asleep 183call. If -1 is passed for the priority you must be prepared to catch signal 184conditions if the prior call to 185.Fn asleep 186specified it in its priority. If -1 is passed for the timeout you must be 187prepared to catch a timeout condition if the prior call to 188.Fn asleep 189specified a timeout. When you use -1, it is usually a good idea to not make 190assumptions as to the arguments used by the prior 191.Fn asleep 192call. 193.Pp 194The 195.Fn asleep 196and 197.Fn await 198functions are mainly used by the kernel to shift the burden of blocking 199away from extremely low level routines and to push it onto their callers. 200This in turn allows more complex interlocking code to 201.Em backout 202of a temporary resource failure 203(such as lack of memory) in order to release major locks prior to actually 204blocking, and to then retry the operation on wakeup. This key feature is 205expected to be heavily used in SMP situations in order to allow code to make 206better use of spinlocks. A spinlock, by its very nature, cannot be used 207around code that might block. It is hoped that these capabilities will 208make it easier to migrate the SMP master locks deeper into the kernel. 209.Pp 210These routines may also be used to avoid nasty spl*() calls to get around 211race conditions with simple conditional test/wait interlocks. You simply 212call 213.Fn asleep 214prior to your test, then conditionally 215.Fn await 216only if the test fails. It is usually a good idea to cancel an 217.Fn asleep 218if you wind up never calling the related 219.Fn await , 220but it is not required. If you do not want to waste cpu calling 221.Fn asleep 222unnecessarily, you can surround the whole thing with a second test. The 223race condition is still handled by the inside 224.Fn asleep 225call. | |
| 226.Sh RETURN VALUES 227See above. 228.Sh SEE ALSO 229.Xr ps 1 , 230.Xr malloc 9 , 231.Xr mi_switch 9 232.Sh HISTORY 233The sleep/wakeup process synchronization mechanism is very old. It 234appeared in a very early version of Unix. 235.Pp 236.Nm Tsleep 237appeared in 238.Bx 4.4 . 239.Pp | 124.Sh RETURN VALUES 125See above. 126.Sh SEE ALSO 127.Xr ps 1 , 128.Xr malloc 9 , 129.Xr mi_switch 9 130.Sh HISTORY 131The sleep/wakeup process synchronization mechanism is very old. It 132appeared in a very early version of Unix. 133.Pp 134.Nm Tsleep 135appeared in 136.Bx 4.4 . 137.Pp |
| 240.Nm Asleep Ns / Ns Nm await 241first appeared in 242.Fx 3.0 243and is designed to shift the burden of blocking 244away from extremely low level routines and push it up to their callers. 245.Pp | |
| 246.Nm Sleep 247used to be the traditional form. It doesn't let you specify a timeout or a 248.Ar wmesg , 249hence it has been discontinued. 250.Sh AUTHORS 251.An -nosplit 252This man page was written by 253.An J\(:org Wunsch . | 138.Nm Sleep 139used to be the traditional form. It doesn't let you specify a timeout or a 140.Ar wmesg , 141hence it has been discontinued. 142.Sh AUTHORS 143.An -nosplit 144This man page was written by 145.An J\(:org Wunsch . |
| 254.Nm Asleep 255and 256.Nm await 257were designed and written by 258.An Matthew Dillon . | |