| sleep.9 (167218) | sleep.9 (167387) |
|---|---|
| 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 unchanged lines hidden (view full) --- 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.\" | 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 unchanged lines hidden (view full) --- 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: head/share/man/man9/sleep.9 167218 2007-03-05 05:59:49Z grog $ | 26.\" $FreeBSD: head/share/man/man9/sleep.9 167387 2007-03-09 22:41:01Z jhb $ |
| 27.\" 28.Dd February 27, 2007 29.Os 30.Dt SLEEP 9 31.Sh NAME 32.Nm msleep , 33.Nm msleep_spin , 34.Nm pause , --- 28 unchanged lines hidden (view full) --- 63handle event-based thread blocking. 64If a thread must wait for an 65external event, it is put to sleep by 66.Fn tsleep , 67.Fn msleep , 68.Fn msleep_spin , 69or 70.Fn pause . | 27.\" 28.Dd February 27, 2007 29.Os 30.Dt SLEEP 9 31.Sh NAME 32.Nm msleep , 33.Nm msleep_spin , 34.Nm pause , --- 28 unchanged lines hidden (view full) --- 63handle event-based thread blocking. 64If a thread must wait for an 65external event, it is put to sleep by 66.Fn tsleep , 67.Fn msleep , 68.Fn msleep_spin , 69or 70.Fn pause . |
| 71Threads may also wait using one of the locking primitive sleep routines 72.Xr mtx_sleep 9 , 73.Xr rw_sleep 9 , 74or 75.Xr sx_sleep 9 . 76.Pp |
|
| 71The parameter 72.Fa chan 73is an arbitrary address that uniquely identifies the event on which 74the thread is being put to sleep. 75All threads sleeping on a single 76.Fa chan 77are woken up later by 78.Fn wakeup , 79often called from inside an interrupt routine, to indicate that the 80resource the thread was blocking on is available now. 81.Pp 82The parameter | 77The parameter 78.Fa chan 79is an arbitrary address that uniquely identifies the event on which 80the thread is being put to sleep. 81All threads sleeping on a single 82.Fa chan 83are woken up later by 84.Fn wakeup , 85often called from inside an interrupt routine, to indicate that the 86resource the thread was blocking on is available now. 87.Pp 88The parameter |
| 83.Fa wmesg 84is a string describing the sleep condition for tools like 85.Xr ps 1 . 86Due to the limited space of those programs to display arbitrary strings, 87this message should not be longer than 6 characters. 88.Pp 89The 90.Fn msleep 91function is the general sleep call. 92It suspends the current thread until a wakeup is 93performed on the specified identifier. 94The 95.Fa mtx 96parameter is a mutex which will be released before sleeping and reacquired 97before 98.Fn msleep 99returns. 100If | |
| 101.Fa priority | 89.Fa priority |
| 102includes the 103.Dv PDROP 104flag, the 105.Fa mtx 106parameter will not be reacquired before returning. 107The mutex is used to ensure that a condition can be checked atomically, 108and that the current thread can be suspended without missing a 109change to the condition, or an associated wakeup. 110If 111.Fa priority 112is not 0, | 90specifies a new priority for the thread as well as some optional flags. 91If the new priority is not 0, |
| 113then the thread will be made 114runnable with the specified 115.Fa priority 116when it resumes. 117If | 92then the thread will be made 93runnable with the specified 94.Fa priority 95when it resumes. 96If |
| 118.Fa timo 119is not 0, 120then the thread will sleep for at most 121.Fa timo No / Va hz 122seconds. 123If the 124.Va Giant 125lock is not held and 126.Fa mtx 127is 128.Dv NULL , 129then 130.Fa timo 131must be non-zero. 132If | |
| 133.Fa priority 134includes the 135.Dv PCATCH 136flag, signals are checked before and after sleeping, otherwise signals are 137not checked. | 97.Fa priority 98includes the 99.Dv PCATCH 100flag, signals are checked before and after sleeping, otherwise signals are 101not checked. |
| 138The 139.Fn msleep 140function returns 0 if awakened, 141.Er EWOULDBLOCK 142if the timeout expires. | |
| 143If 144.Dv PCATCH 145is set and a signal needs to be delivered, 146.Er ERESTART 147is returned if the current system call should be restarted if 148possible, and 149.Er EINTR 150is returned if the system call should be interrupted by the signal 151(return 152.Er EINTR ) . 153.Pp | 102If 103.Dv PCATCH 104is set and a signal needs to be delivered, 105.Er ERESTART 106is returned if the current system call should be restarted if 107possible, and 108.Er EINTR 109is returned if the system call should be interrupted by the signal 110(return 111.Er EINTR ) . 112.Pp |
| 154The | 113The parameter 114.Fa wmesg 115is a string describing the sleep condition for tools like 116.Xr ps 1 . 117Due to the limited space of those programs to display arbitrary strings, 118this message should not be longer than 6 characters. 119.Pp 120The parameter 121.Fa timo 122specifies a timeout for the sleep. 123If 124.Fa timo 125is not 0, 126then the thread will sleep for at most 127.Fa timo No / Va hz 128seconds. 129If the timeout expires, 130then the sleep function will return 131.Er EWOULDBLOCK . 132.Pp 133Several of the sleep functions including 134.Fn msleep , 135.Fn msleep_spin , 136and the locking primitive sleep routines specify an additional lock 137parameter. 138The lock will be released before sleeping and reacquired 139before the sleep routine returns. 140If 141.Fa priority 142includes the 143.Dv PDROP 144flag, then 145the lock will not be reacquired before returning. 146The lock is used to ensure that a condition can be checked atomically, 147and that the current thread can be suspended without missing a 148change to the condition, or an associated wakeup. 149In addition, all of the sleep routines will fully drop the 150.Va Giant 151mutex 152(even if recursed) 153while the thread is suspended and will reacquire the 154.Va Giant 155mutex before the function returns. 156.Pp 157To avoid lost wakeups, 158either a lock should be used to protect against races, 159or a timeout should be specified to place an upper bound on the delay due 160to a lost wakeup. 161As a result, 162the |
| 155.Fn tsleep | 163.Fn tsleep |
| 156function is a variation on 157.Fn msleep . 158It is identical to invoking | 164function should only be invoked with a timeout of 0 when the 165.Va Giant 166mutex is held. 167.Pp 168The |
| 159.Fn msleep | 169.Fn msleep |
| 160with a 161.Dv NULL | 170function requires that |
| 162.Fa mtx | 171.Fa mtx |
| 163parameter. | 172reference a default, i.e. non-spin, mutex. 173It's use is deprecated in favor of 174.Xr mtx_sleep 9 175which provides identical behavior. |
| 164.Pp 165The 166.Fn msleep_spin | 176.Pp 177The 178.Fn msleep_spin |
| 167function is another variation on 168.Fn msleep . 169This function accepts a spin mutex rather than a default mutex for its | 179function requires that |
| 170.Fa mtx | 180.Fa mtx |
| 171parameter. 172It is also more limited in that it does not accept a | 181reference a spin mutex. 182The 183.Fn msleep_spin 184function does not accept a |
| 173.Fa priority | 185.Fa priority |
| 174parameter. 175Thus, it will not change the priority of a sleeping thread, 176and it does not support the | 186parameter and thus does not support changing the current thread's priority, 187the |
| 177.Dv PDROP | 188.Dv PDROP |
| 178and | 189flag, 190or catching signals via the |
| 179.Dv PCATCH | 191.Dv PCATCH |
| 180flags. | 192flag. |
| 181.Pp 182The 183.Fn pause 184function is a wrapper around 185.Fn tsleep 186that suspends execution of the current thread for the indicated timeout. 187The thread can not be awakened early by signals or calls to 188.Fn wakeup --- 27 unchanged lines hidden (view full) --- 216When converting from 217.Fn wakeup 218to 219.Fn wakeup_one , 220pay particular attention to ensure that no other threads wait on the 221same 222.Fa chan . 223.Sh RETURN VALUES | 193.Pp 194The 195.Fn pause 196function is a wrapper around 197.Fn tsleep 198that suspends execution of the current thread for the indicated timeout. 199The thread can not be awakened early by signals or calls to 200.Fn wakeup --- 27 unchanged lines hidden (view full) --- 228When converting from 229.Fn wakeup 230to 231.Fn wakeup_one , 232pay particular attention to ensure that no other threads wait on the 233same 234.Fa chan . 235.Sh RETURN VALUES |
| 224See above. | 236If the thread is awakened by a call to 237.Fn wakeup 238or 239.Fn wakeup_one , 240the 241.Fn msleep , 242.Fn msleep_spin , 243.Fn tsleep , 244and locking primitive sleep functions return 0. 245Otherwise, a non-zero error code is returned. 246.Sh ERRORS 247.Fn msleep , 248.Fn msleep_spin , 249.Fn tsleep , 250and the locking primitive sleep functions will fail if: 251.Bl -tag -width Er 252.It Bq Er EINTR 253The 254.Dv PCATCH 255flag was specified, a signal was caught, and the system call should be 256interrupted. 257.It Bq Er ERESTART 258The 259.Dv PCATCH 260flag was specified, a signal was caught, and the system call should be 261restarted. 262.It Bq Er EWOULDBLOCK 263A non-zero timeout was specified and the timeout expired. 264.El |
| 225.Sh SEE ALSO 226.Xr ps 1 , 227.Xr malloc 9 , | 265.Sh SEE ALSO 266.Xr ps 1 , 267.Xr malloc 9 , |
| 228.Xr mi_switch 9 | 268.Xr mi_switch 9 , 269.Xr mtx_sleep 9 , 270.Xr rw_sleep 9 , 271.Xr sx_sleep 9 |
| 229.Sh HISTORY 230The functions 231.Fn sleep 232and 233.Fn wakeup 234were present in 235.At v1 . 236They were probably also present in the preceding --- 36 unchanged lines hidden --- | 272.Sh HISTORY 273The functions 274.Fn sleep 275and 276.Fn wakeup 277were present in 278.At v1 . 279They were probably also present in the preceding --- 36 unchanged lines hidden --- |