1.\" $NetBSD: ltsleep.9,v 1.17 2014/03/22 11:35:03 wiz 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 March 22, 2014 31.Dt LTSLEEP 9 32.Os 33.Sh NAME 34.Nm ltsleep , 35.Nm mtsleep , 36.Nm tsleep , 37.Nm wakeup 38.Nd process context sleep and wakeup 39.Sh SYNOPSIS 40.In sys/proc.h 41.Ft int 42.Fn "mtsleep" "wchan_t ident" "pri_t priority" "const char *wmesg" "int timo" "kmutex_t *mtx" 43.Ft int 44.Fn "tsleep" "wchan_t ident" "pri_t priority" "const char *wmesg" "int timo" 45.Ft void 46.Fn "wakeup" "wchan_t ident" 47.Sh DESCRIPTION 48.Em The interfaces described in this manual page are obsolete 49.Em and will be removed from a future version of the system. 50.Pp 51.Em The 52.Em Fn ltsleep 53.Em interface has been obsoleted and removed from the system. 54.Pp 55.Em Please see the 56.Xr condvar 9 , 57.Xr mutex 9 , 58.Em and 59.Xr rwlock 9 60.Em manual pages for information on kernel synchronisation primitives. 61.Pp 62These functions implement voluntary context switching. 63.Fn tsleep 64and 65.Fn mtsleep 66are used throughout the kernel whenever processing in the current context 67can not continue for any of the following reasons: 68.Bl -bullet -offset indent 69.It 70The current process needs to await the results of a pending I/O operation. 71.It 72The current process needs resources 73.Pq e.g., memory 74which are temporarily unavailable. 75.El 76.Pp 77The function 78.Fn wakeup 79is used to notify sleeping processes of possible changes to the condition 80that caused them to go to sleep. 81Typically, an awakened process will -- after it has acquired a context 82again -- retry the action that blocked its operation to see if the 83.Dq blocking 84condition has cleared. 85.Pp 86The 87.Fn tsleep 88and 89.Fn mtsleep 90functions take the following arguments: 91.Bl -tag -width priority 92.It Fa ident 93An identifier of the 94.Dq wait channel 95representing the resource for which the current process needs to wait. 96This typically is the virtual address of some kernel data-structure related 97to the resource for which the process is contending. 98The same identifier must be used in a call to 99.Fn wakeup 100to get the process going again. 101.Fa ident 102should not be 103.Dv NULL . 104.It Fa priority 105The process priority to be used when the process is awakened and put on 106the queue of runnable processes. 107This mechanism is used to optimize 108.Dq throughput 109of processes executing in kernel mode. 110If the flag 111.Dv PCATCH 112is OR'ed into 113.Fa priority 114the process checks for posted signals before and after sleeping. 115.It Fa wmesg 116A pointer to a character string indicating the reason a process is sleeping. 117The kernel does not use the string, but makes it available 118.Pq through the process structure field Li p_wmesg 119for user level utilities such as 120.Xr ps 1 . 121.It Fa timo 122If non-zero, the process will sleep for at most 123.Li timo/hz 124seconds. 125If this amount of time elapses and no 126.Fn wakeup "ident" 127has occurred, and no signal 128.Pq if Dv PCATCH No was set 129was posted, 130.Fn tsleep 131will return 132.Er EWOULDBLOCK . 133.El 134.Pp 135The 136.Fn mtsleep 137function takes an additional argument and flag: 138.Bl -tag -width priority 139.It Fa mtx 140A 141.Xr mutex 9 142representing the lock protecting the data-structures. 143On entry 144.Fn mtsleep 145will release the lock and re-acquire the lock on return. 146.It Fa priority 147If the flag 148.Dv PNORELOCK 149is OR'ed into 150.Fa priority 151then 152.Fn mtsleep 153will not re-acquire the lock. 154.El 155.Pp 156The 157.Fn wakeup 158function will mark all processes which are currently sleeping on the identifier 159.Fa ident 160as runnable. 161Eventually, each of the processes will resume execution in the kernel 162context, causing a return from 163.Fn tsleep 164or 165.Fn mtsleep . 166Note that processes returning from sleep should always re-evaluate the 167conditions that blocked them, since a call to 168.Fn wakeup 169merely signals a 170.Em possible 171change to the blocking conditions. 172.Sh RETURN VALUES 173.Fn tsleep 174and 175.Fn mtsleep 176return 0 if they return as a result of a 177.Fn wakeup . 178If a 179.Fn tsleep 180and 181.Fn mtsleep 182return as a result of a signal, the return value is 183.Er ERESTART 184if the signal has the 185.Dv SA_RESTART 186property 187.Pq see Xr sigaction 2 , 188and 189.Er EINTR 190otherwise. 191If 192.Fn tsleep 193and 194.Fn mtsleep 195return because of a timeout, the return value is 196.Er EWOULDBLOCK . 197.Sh MIGRATING TO CONDVAR 198Note the conversion from tsleep/wakeup into 199.Xr condvar 9 200should not be done mechanically i.e. 201.Dq blindly . 202Code logic should be understood before changing, and it may also need to be 203revisited for the change. 204Please also read the 205.Xr condvar 9 206man page. 207.Pp 208The 209.Fn tsleep 210and 211.Fn mtsleep , 212and 213.Fn wakeup 214pairs should generally be replaced by 215.Xr cv_wait 9 / 216.Xr cv_wait_sig 9 / 217.Xr cv_timedwait 9 / 218.Xr cv_timedwait_sig 9 219and 220.Xr cv_signal 9 / 221.Xr cv_broadcast 9 222pairs. 223The 224.Fn cv_wait* 225variant to use can be determinded from looking at the corresponding 226.Fn tsleep 227usage. 228.Pp 229There are two arguments of interest: 230.Ar timo 231and 232.Ar priority . 233The 234.Ar priority 235value may have OR'ed the flag 236.Dv PCATCH . 237.Pp 238The 239.Dv PCATCH 240flag means that the blocking thread should be awoken on signal, and 241the sleep call should be replaced with 242.Xr cv_wait_sig 9 . 243.Pp 244The 245.Ar timo 246value, if it is not zero, indicates how long to sleep, and 247the sleep call should be replaced with 248.Xr cv_timedwait 9 . 249.Pp 250If both the 251.Dv PCATCH 252flag and a non-zero 253.Ar timo 254value are specified, then 255.Xr cv_timedwait_sig 9 256should be used. 257.Pp 258A 259.Xr mutex 9 260(interlock) must be held across 261.Fn cv_wait 262and 263.Fn cv_broadcast 264calls, in order to protect state. 265Most old code will require the addition of locking, whereas some will 266require amending to remove 267.Dv PNORELOCK . 268.Sh SEE ALSO 269.Xr sigaction 2 , 270.Xr condvar 9 , 271.Xr hz 9 , 272.Xr mutex 9 , 273.Xr rwlock 9 274.Sh HISTORY 275The sleep/wakeup process synchronization mechanism is very old. 276It appeared in a very early version of Unix. 277.Fn tsleep 278appeared in 279.Bx 4.4 . 280.Fn ltsleep 281appeared in 282.Nx 1.5 . 283