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