1.\" $NetBSD: ltsleep.9,v 1.2 2002/10/14 13:43:26 wiz Exp $ 2.\" 3.\" Copyright (c) 1996, 2002 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Paul Kranenburg. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd September 29, 2002 38.Dt LTSLEEP 9 39.Os 40.Sh NAME 41.Nm ltsleep , 42.Nm tsleep , 43.Nm wakeup 44.Nd process context sleep and and wakeup 45.Sh SYNOPSIS 46.Fd #include \*[Lt]sys/proc.h\*[Gt] 47.Ft int 48.Fn "ltsleep" "void *ident" "int priority" "const char *wmesg" "int timo" "__volatile struct simplelock *slock" 49.Ft int 50.Fn "tsleep" "void *ident" "int priority" "const char *wmesg" "int timo" 51.Ft void 52.Fn "wakeup" "void *ident" 53.Sh DESCRIPTION 54These functions implement voluntary context switching. 55.Fn ltsleep 56and 57.Fn tsleep 58are used throughout the kernel whenever processing in the current context 59can not continue for any of the following reasons: 60.Bl -bullet -offset indent 61.It 62The current process needs to await the results of a pending I/O operation. 63.It 64The current process needs resources 65.Pq e.g. memory 66which are temporarily unavailable. 67.It 68The current process wants access to data-structures which are locked by 69other processes. 70.El 71.Pp 72The function 73.Fn wakeup 74is used to notify sleeping processes of possible changes to the condition 75that caused them to go to sleep. 76Typically, an awakened process will -- after it has acquired a context 77again -- retry the action that blocked its operation to see if the 78.Dq blocking 79condition has cleared. 80.Pp 81The 82.Fn ltsleep 83function takes the following arguments: 84.Bl -tag -width priority 85.It Fa ident 86An identifier of the 87.Dq wait channel 88representing the resource for which the current process needs to wait. 89This typically is the virtual address of some kernel data-structure related 90to the resource for which the process is contending. 91The same identifier must be used in a call to 92.Fn wakeup 93to get the process going again. 94.Fa ident 95should not be 96.Dv NULL . 97.It Fa priority 98The process priority to be used when the process is awakened and put on 99the queue of runnable processes. 100This mechanism is used to optimize 101.Dq throughput 102of processes executing in kernel mode. 103If the flag 104.Dv PCATCH 105is OR'ed into 106.Fa priority 107the process checks for posted signals before and after sleeping. 108If the flag 109.Dv PNORELOCK 110is OR'ed into 111.Fa priority , 112.Fa slock 113is NOT re-locked after process resume. 114.It Fa wmesg 115A pointer to a character string indicating the reason a process is sleeping. 116The kernel does not use the string, but makes it available 117.Pq through the process structure field Li p_wmesg 118for user level utilities such as 119.Xr ps 1 . 120.It Fa timo 121If non-zero, the process will sleep for at most 122.Li timo/hz 123seconds. 124If this amount of time elapses and no 125.Fn wakeup "ident" 126has occurred, and no signal 127.Pq if Dv PCATCH No was set 128was posted, 129.Fn tsleep 130will return 131.Er EWOULDBLOCK . 132.It Fa slock 133If not NULL, the 134.Fa slock 135interlock is unlocked once the scheduler lock is acquired. 136Unless 137.Dv PNORELOCK 138was set, 139.Fa slock 140is locked again once 141the process is resumed from sleep. 142This provides wakeup-before-sleep condition protection facility. 143.El 144.Pp 145The 146.Fn tsleep 147macro is functionally equivalent to: 148.Bd -literal -offset indent 149ltsleep(ident, priority, wmesg, timo, NULL) 150.Ed 151.Pp 152The 153.Fn wakeup 154function will mark all processes which are currently sleeping on the identifier 155.Fa ident 156as runnable. 157Eventually, each of the processes will resume execution in the kernel 158context, causing a return from 159.Fn tsleep . 160Note that processes returning from sleep should always re-evaluate the 161conditions that blocked them, since a call to 162.Fn wakeup 163merely signals a 164.Em possible 165change to the blocking conditions. 166For example, when two or more processes are waiting for an exclusive-access 167lock 168.Pq see Xr lock 9 , 169only one of them will succeed in acquiring the lock when it is released. 170All others will have to go back to sleep and wait for the next opportunity. 171.Sh RETURN VALUES 172.Fn ltsleep 173returns 0 if it returns as a result of a 174.Fn wakeup . 175If a 176.Fn ltsleep 177returns as a result of a signal, the return value is 178.Er ERESTART 179if the signal has the 180.Dv SA_RESTART 181property 182.Pq see Xr sigaction 2 , 183and 184.Er EINTR 185otherwise. 186If 187.Fn ltsleep 188returns because of a timeout it returns 189.Er EWOULDBLOCK . 190.Sh SEE ALSO 191.Xr sigaction 2 , 192.Xr hz 9 , 193.Xr lock 9 194.Sh HISTORY 195The sleep/wakeup process synchronization mechanism is very old. 196It appeared in a very early version of Unix. 197.Fn tsleep 198appeared in 199.Bx 4.4 . 200.Fn ltsleep 201appeared in 202.Nx 1.5 . 203