1.\" $NetBSD: ltsleep.9,v 1.11 2007/06/17 18:50:07 pooka Exp $ 2.\" 3.\" Copyright (c) 1996, 2002, 2007 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 June 17, 2007 38.Dt LTSLEEP 9 39.Os 40.Sh NAME 41.Nm ltsleep , 42.Nm tsleep , 43.Nm wakeup 44.Nd process context sleep and wakeup 45.Sh SYNOPSIS 46.In sys/proc.h 47.Ft int 48.Fn "ltsleep" "wchan_t ident" "pri_t priority" "const char *wmesg" "int timo" "volatile struct simplelock *slock" 49.Ft int 50.Fn "tsleep" "wchan_t ident" "pri_t priority" "const char *wmesg" "int timo" 51.Ft void 52.Fn "wakeup" "wchan_t ident" 53.Sh DESCRIPTION 54.Em The interfaces described in this manual page are obsolete 55.Em and will be removed from a future version of the system. 56.Pp 57.Em Please see the 58.Xr condvar 9 , 59.Xr mutex 9 , 60.Em and 61.Xr rwlock 9 62.Em manual pages for information on kernel synchronisation primitives. 63.Pp 64These functions implement voluntary context switching. 65.Fn ltsleep 66and 67.Fn tsleep 68are used throughout the kernel whenever processing in the current context 69can not continue for any of the following reasons: 70.Bl -bullet -offset indent 71.It 72The current process needs to await the results of a pending I/O operation. 73.It 74The current process needs resources 75.Pq e.g., memory 76which are temporarily unavailable. 77.It 78The current process wants access to data-structures which are locked by 79other processes. 80.El 81.Pp 82The function 83.Fn wakeup 84is used to notify sleeping processes of possible changes to the condition 85that caused them to go to sleep. 86Typically, an awakened process will -- after it has acquired a context 87again -- retry the action that blocked its operation to see if the 88.Dq blocking 89condition has cleared. 90.Pp 91The 92.Fn ltsleep 93function takes the following arguments: 94.Bl -tag -width priority 95.It Fa ident 96An identifier of the 97.Dq wait channel 98representing the resource for which the current process needs to wait. 99This typically is the virtual address of some kernel data-structure related 100to the resource for which the process is contending. 101The same identifier must be used in a call to 102.Fn wakeup 103to get the process going again. 104.Fa ident 105should not be 106.Dv NULL . 107.It Fa priority 108The process priority to be used when the process is awakened and put on 109the queue of runnable processes. 110This mechanism is used to optimize 111.Dq throughput 112of processes executing in kernel mode. 113If the flag 114.Dv PCATCH 115is OR'ed into 116.Fa priority 117the process checks for posted signals before and after sleeping. 118If the flag 119.Dv PNORELOCK 120is OR'ed into 121.Fa priority , 122.Fa slock 123is NOT re-locked after process resume. 124.It Fa wmesg 125A pointer to a character string indicating the reason a process is sleeping. 126The kernel does not use the string, but makes it available 127.Pq through the process structure field Li p_wmesg 128for user level utilities such as 129.Xr ps 1 . 130.It Fa timo 131If non-zero, the process will sleep for at most 132.Li timo/hz 133seconds. 134If this amount of time elapses and no 135.Fn wakeup "ident" 136has occurred, and no signal 137.Pq if Dv PCATCH No was set 138was posted, 139.Fn tsleep 140will return 141.Er EWOULDBLOCK . 142.It Fa slock 143If not NULL, the 144.Fa slock 145interlock is unlocked once the scheduler lock is acquired. 146Unless 147.Dv PNORELOCK 148was set, 149.Fa slock 150is locked again once 151the process is resumed from sleep. 152This provides wakeup-before-sleep condition protection facility. 153.El 154.Pp 155The 156.Fn tsleep 157macro is functionally equivalent to: 158.Bd -literal -offset indent 159ltsleep(ident, priority, wmesg, timo, NULL) 160.Ed 161.Pp 162The 163.Fn wakeup 164function will mark all processes which are currently sleeping on the identifier 165.Fa ident 166as runnable. 167Eventually, each of the processes will resume execution in the kernel 168context, causing a return from 169.Fn tsleep . 170Note that processes returning from sleep should always re-evaluate the 171conditions that blocked them, since a call to 172.Fn wakeup 173merely signals a 174.Em possible 175change to the blocking conditions. 176For example, when two or more processes are waiting for an exclusive-access 177lock 178.Pq see Xr lock 9 , 179only one of them will succeed in acquiring the lock when it is released. 180All others will have to go back to sleep and wait for the next opportunity. 181.Sh RETURN VALUES 182.Fn ltsleep 183returns 0 if it returns as a result of a 184.Fn wakeup . 185If a 186.Fn ltsleep 187returns as a result of a signal, the return value is 188.Er ERESTART 189if the signal has the 190.Dv SA_RESTART 191property 192.Pq see Xr sigaction 2 , 193and 194.Er EINTR 195otherwise. 196If 197.Fn ltsleep 198returns because of a timeout it returns 199.Er EWOULDBLOCK . 200.Sh SEE ALSO 201.Xr sigaction 2 , 202.Xr condvar 9 , 203.Xr hz 9 , 204.Xr lock 9 , 205.Xr mutex 9 , 206.Xr rwlock 9 207.Sh HISTORY 208The sleep/wakeup process synchronization mechanism is very old. 209It appeared in a very early version of Unix. 210.Fn tsleep 211appeared in 212.Bx 4.4 . 213.Fn ltsleep 214appeared in 215.Nx 1.5 . 216