1.\" 2.\" Copyright (c) 2004,2010 The DragonFly Project. All rights reserved. 3.\" 4.\" This code is derived from software contributed to The DragonFly Project 5.\" by Hiten Pandya <hmp@backplane.com>. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in 15.\" the documentation and/or other materials provided with the 16.\" distribution. 17.\" 3. Neither the name of The DragonFly Project nor the names of its 18.\" contributors may be used to endorse or promote products derived 19.\" from this software without specific, prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 22.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 23.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 24.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 25.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 26.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 27.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 28.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 29.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 30.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 31.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" Copyright (c) 1996 Joerg Wunsch 35.\" 36.\" All rights reserved. 37.\" 38.\" Redistribution and use in source and binary forms, with or without 39.\" modification, are permitted provided that the following conditions 40.\" are met: 41.\" 1. Redistributions of source code must retain the above copyright 42.\" notice, this list of conditions and the following disclaimer. 43.\" 2. Redistributions in binary form must reproduce the above copyright 44.\" notice, this list of conditions and the following disclaimer in the 45.\" documentation and/or other materials provided with the distribution. 46.\" 47.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 48.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 49.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 50.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 51.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 52.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 53.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 54.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 55.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 56.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 57.\" 58.\" $FreeBSD: src/share/man/man9/sleep.9,v 1.18.2.5 2001/12/17 11:30:19 ru Exp $ 59.\" 60.Dd October 12, 2012 61.Dt SLEEP 9 62.Os 63.Sh NAME 64.Nm tsleep , 65.Nm ssleep , 66.Nm lksleep , 67.Nm mtxsleep , 68.Nm zsleep , 69.Nm tsleep_interlock , 70.Nm wakeup , 71.Nm wakeup_one 72.Nd wait/sleep/block for events 73.Sh SYNOPSIS 74.In sys/param.h 75.In sys/serialize.h 76.In sys/systm.h 77.In sys/proc.h 78.Ft int 79.Fn tsleep "const volatile void *ident" "int flags" "const char *wmesg" "int timo" 80.Ft int 81.Fn ssleep "const volatile void *ident" "struct spinlock *spin" "int flags" "const char *wmesg" "int timo" 82.Ft int 83.Fn lksleep "const volatile void *ident" "struct lock *lock" "int flags" "const char *wmesg" "int timo" 84.Ft int 85.Fn mtxsleep "const volatile void *ident" "struct mtx *mtx" "int flags" "const char *wmesg" "int timo" 86.Ft int 87.Fn zsleep "const volatile void *ident" "struct lwkt_serialize *slz" "int flags" "const char *wmesg" "int timo" 88.Ft void 89.Fn tsleep_interlock "const volatile void *ident" "int flags" 90.Ft void 91.Fn wakeup "const volatile void *ident" 92.Ft void 93.Fn wakeup_one "const volatile void *ident" 94.Sh DESCRIPTION 95The functions 96.Fn tsleep , 97.Fn ssleep , 98.Fn lksleep , 99.Fn mtxsleep , 100.Fn zsleep , 101and 102.Fn wakeup 103handle event-based process blocking. 104If a process must wait for an 105external event, it is put on sleep by 106.Fn tsleep , 107.Fn ssleep , 108.Fn lksleep , 109.Fn mtxsleep , 110or 111.Fn zsleep . 112.Pp 113The parameter 114.Ar ident 115is an arbitrary address that uniquely identifies the event on which 116the process is being asleep. 117All processes sleeping on a single 118.Fa ident 119are woken up later by 120.Fn wakeup , 121often called from inside an interrupt routine, to indicate that the 122resource the process/thread was blocking on is available now. 123.Pp 124The parameter 125.Fa wmesg 126is a string describing the sleep condition for tools like 127.Xr ps 1 . 128Due to the limited space of those programs to display arbitrary strings, 129this message should not be longer than 6 characters. 130.Pp 131The 132.Fn tsleep 133function is general in its use and suspends the current process/thread until a 134wakeup is performed on the specified identifier. 135The process/thread will then be made runnable. 136The process/thread will sleep at most 137.Fa timo 138\&/ hz seconds (0 means no timeout). 139If 140.Fa flags 141contains the 142.Dv PCATCH 143flag, signals are checked before and after sleeping, else signals are 144ignored. 145.Pp 146The 147.Fn tsleep_interlock 148function is similar to 149.Fn tsleep , 150in that it queues a thread on a sleep queue, but it does not actually put the 151thread to sleep. 152This allows coupling tsleep with higher-level synchronization primitives. 153The pattern is: 154.Bd -literal 155(acquire high level synchronization primitive) 156(test condition of interest) 157tsleep_interlock(ident, flags) 158(release high level synchronization primitive) 159tsleep(..., PINTERLOCKED, ...) 160.Ed 161.Pp 162For example, to implement 163.Fn ssleep : 164.Bd -literal 165spin_lock(&important_lock); 166if (important_condition == 0) { 167 tsleep_interlock(ident, flags); 168 spin_unlock(&important_lock); 169 tsleep(..., PINTERLOCKED, ...); 170} 171.Ed 172.Pp 173The 174.Fn ssleep 175function works like 176.Fn tsleep 177while at the same time releasing the exclusive spinlock 178.Fa spin 179before sleeping and reacquiring it before 180.Fn ssleep 181returns. 182This is an atomic operation, which guarantees that a 183.Fn wakeup 184interlocked by 185.Fa spin 186will not be missed. 187.Pp 188The 189.Fn lksleep 190function works like 191.Fn tsleep 192while at the same time releasing the exclusive lockmgr lock 193.Fa lock 194before sleeping and reacquiring it before 195.Fn lksleep 196returns. 197This is an atomic operation, which guarantees that a 198.Fn wakeup 199interlocked by 200.Fa lock 201will not be missed. 202.Pp 203The 204.Fn mtxsleep 205function works like 206.Fn tsleep 207while at the same time atomically releasing the mutex 208.Fa mtx 209before sleeping and reacquiring it in exclusive state before 210.Fn mtxsleep 211returns. 212.Pp 213The 214.Fn zsleep 215function works like 216.Fn tsleep 217while at the same time releasing the serializer 218.Fa slz 219before sleeping and reacquiring it before 220.Fn zsleep 221returns. 222This is an atomic operation, which guarantees that a 223.Fn wakeup 224interlocked by 225.Fa slz 226will not be missed. 227.Pp 228The 229.Fn wakeup_one 230function is used to make the first process/thread in the queue that is 231sleeping on the parameter 232.Fa ident 233runnable. 234This can prevent the system from becoming saturated 235when a large number of processes/threads are sleeping on the same address, 236but only one of them can actually do any useful work when made 237runnable. 238.Sh IMPLEMENTATION NOTES 239Unlike 240.Fx , 241the 242.Fn tsleep 243function in 244.Dx 245ignores priority information because it is not required by the 246.Tn LWKT 247subsystem. 248Sleeps without the 249.Dv LWP_SINTR 250flag set are assumed to be disk-waits, otherwise they are 251normal sleeps. 252.Sh RETURN VALUES 253The 254.Fn tsleep 255function returns 256.Li 0 257if awakened, otherwise an appropriate error code is returned. 258.Sh FILES 259The various sleep functions are in 260.Pa /sys/kern/kern_synch.c . 261.Sh ERRORS 262.Bl -tag -width Er 263.It Bq Er EWOULDBLOCK 264The timeout expired. 265.It Bq Er ERESTART 266A signal needs to be delivered and the system call should 267be restarted if possible. 268This only happens if 269.Dv PCATCH 270was set in 271.Fa flags . 272.It Bq Er EINTR 273The system call needs to be interrupted by the signal. 274This only happens if 275.Dv PCATCH 276was set in 277.Fa flags . 278.El 279.Sh SEE ALSO 280.Xr ps 1 , 281.Xr kmalloc 9 , 282.Xr serializer 9 283.Sh HISTORY 284The sleep/wakeup process synchronization mechanism is very old. 285It appeared in a very early version of Unix. 286.Pp 287.Fn tsleep 288appeared in 289.Bx 4.4 . 290.Pp 291.Fn ssleep 292appeared in 293.Dx 1.6 , 294.Fn zsleep 295in 296.Dx 2.0 , 297and 298.Fn lksleep 299and 300.Fn mtxsleep 301in 302.Dx 2.3 . 303.Sh AUTHORS 304.An -nosplit 305This manual page was written by 306.An J\(:org Wunsch 307and modified for 308.Dx 309by 310.An Hiten Pandya Aq Mt hmp@dragonflybsd.org . 311