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