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