1.\" 2.\" Copyright (c) 2004 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.\" $DragonFly: src/share/man/man9/sleep.9,v 1.11 2008/03/05 17:20:23 swildner Exp $ 60.\" " 61.Dd March 5, 2008 62.Os 63.Dt SLEEP 9 64.Sh NAME 65.Nm tsleep , 66.Nm ssleep , 67.Nm serialize_sleep , 68.Nm wakeup , 69.Nm wakeup_one 70.Nd wait/sleep/block for events 71.Sh SYNOPSIS 72.In sys/param.h 73.In sys/serialize.h 74.In sys/systm.h 75.In sys/proc.h 76.Ft int 77.Fn tsleep "void *ident" "int flag" "const char *wmesg" "int timo" 78.Ft int 79.Fn ssleep "void *ident" "struct spinlock *spin" "int flag" "const char *wmesg" "int timo" 80.Ft int 81.Fn lksleep "void *ident" "struct lock *lock" "int flag" "const char *wmesg" "int timo" 82.Ft int 83.Fn serialize_sleep "void *ident" "struct lwkt_serialize *slz" "int flag" "const char *wmesg" "int timo" 84.Ft void 85.Fn wakeup "void *ident" 86.Ft void 87.Fn wakeup_one "void *ident" 88.Sh DESCRIPTION 89The functions 90.Fn tsleep , 91.Fn ssleep , 92.Fn lksleep , 93.Fn serialize_sleep , 94and 95.Fn wakeup 96handle event-based process blocking. 97If a process must wait for an 98external event, it is put on sleep by 99.Fn tsleep , 100.Fn ssleep , 101.Fn lksleep 102or 103.Fn serialize_sleep . 104The parameter 105.Ar ident 106is an arbitrary address that uniquely identifies the event on which 107the process is being asleep. 108All processes sleeping on a single 109.Fa ident 110are woken up later by 111.Nm wakeup , 112often called from inside an interrupt routine, to indicate that the 113resource the process/thread was blocking on is available now. 114.Pp 115The parameter 116.Fa wmesg 117is a string describing the sleep condition for tools like 118.Xr ps 1 . 119Due to the limited space of those programs to display arbitrary strings, 120this message should not be longer than 6 characters. 121.Pp 122The 123.Fn wakeup_one 124function is used to make the first process/thread in the queue that is 125sleeping on the parameter 126.Fa ident 127runnable. 128This can prevent the system from becoming saturated 129when a large number of processes/threads are sleeping on the same address, 130but only one of them can actually do any useful work when made 131runnable. 132.Pp 133The 134.Fn tsleep 135function is general in its use and suspends the current process/thread until a 136wakeup is performed on the specified identifier. 137The process/thread will then be made runnable. 138The process/thread will sleep at most 139.Fa timo 140\&/ hz seconds (0 means no timeout). 141If 142.Fa flags 143contains the 144.Dv PCATCH 145flag, signals are checked before and after sleeping, else signals are 146ignored. 147.Pp 148The 149.Fn ssleep 150function works like 151.Fn tsleep 152while at the same time releasing the exclusive (write) spinlock 153.Fa spin 154before sleeping and reacquiring it before 155.Fn ssleep 156returns. 157This is an atomic operation, which guarantees that a 158.Fn wakeup 159interlocked by 160.Fa spin 161will not be missed. 162.Pp 163The 164.Fn lksleep 165function works like 166.Fn tsleep 167while at the same time releasing the exclusive lockmgr lock 168.Fa lock 169before sleeping and reacquiring it before 170.Fn lksleep 171returns. 172This is an atomic operation, which guarantees that a 173.Fn wakeup 174interlocked by 175.Fa lock 176will not be missed. 177.Pp 178The 179.Fn serialize_sleep 180function works like 181.Fn tsleep 182while at the same time releasing the serializer 183.Fa slz 184before sleeping and reacquiring it before 185.Fn serialize_sleep 186returns. 187This is an atomic operation, which guarantees that a 188.Fn wakeup 189interlocked by 190.Fa slz 191will not be missed. 192.Sh IMPLEMENTATION NOTES 193Unlike 194.Fx , 195the 196.Fn tsleep 197function in 198.Dx 199ignores priority information because it is not required by the 200.Tn LWKT 201subsystem. 202Sleeps without the 203.Dv LWP_SINTR 204flag set are assumed to be disk-waits, otherwise they are 205normal sleeps. 206.Sh RETURN VALUES 207The 208.Fn tsleep 209function returns 210.Li 0 211if awakened, otherwise an appropriate error code is returned. 212.Sh ERRORS 213.Bl -tag -width Er 214.It Bq Er EWOULDBLOCK 215The timeout expired. 216.It Bq Er ERESTART 217A signal needs to be delivered and the system call should 218be restarted if possible. 219This only happens if 220.Dv PCATCH 221was set in 222.Fa flags . 223.It Bq Er EINTR 224The system call needs to be interrupted by the signal. 225This only happens if 226.Dv PCATCH 227was set in 228.Fa flags . 229.El 230.Sh SEE ALSO 231.Xr ps 1 , 232.Xr kmalloc 9 , 233.Xr serializer 9 234.Sh HISTORY 235The sleep/wakeup process synchronization mechanism is very old. 236It appeared in a very early version of Unix. 237.Pp 238.Nm Tsleep 239appeared in 240.Bx 4.4 . 241.Sh AUTHORS 242.An -nosplit 243This manual page was written by 244.An J\(:org Wunsch 245and modified for 246.Dx 247by 248.An Hiten Pandya Aq hmp@dragonflybsd.org 249