1.\" $NetBSD: ltsleep.9,v 1.20 2024/05/07 15:40:15 christos 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 May 7, 2024 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 \(em after it has acquired a 82context again \(em retry the action that blocked its operation to see 83if the 84.Dq blocking 85condition has cleared. 86.Pp 87The 88.Fn tsleep 89and 90.Fn mtsleep 91functions take the following arguments: 92.Bl -tag -width priority 93.It Fa ident 94An identifier of the 95.Dq wait channel 96representing the resource for which the current process needs to wait. 97This typically is the virtual address of some kernel data-structure related 98to the resource for which the process is contending. 99The same identifier must be used in a call to 100.Fn wakeup 101to get the process going again. 102.Fa ident 103should not be 104.Dv NULL . 105.It Fa priority 106The process priority to be used when the process is awakened and put on 107the queue of runnable processes. 108This mechanism is used to optimize 109.Dq throughput 110of processes executing in kernel mode. 111If the flag 112.Dv PCATCH 113is OR'ed into 114.Fa priority 115the process checks for posted signals before and after sleeping. 116.It Fa wmesg 117A pointer to a character string indicating the reason a process is sleeping. 118The kernel does not use the string, but makes it available 119.Pq through the process structure field Li p_wmesg 120for user level utilities such as 121.Xr ps 1 . 122.It Fa timo 123If non-zero, the process will sleep for at most 124.Li timo/hz 125seconds. 126If this amount of time elapses and no 127.Fn wakeup "ident" 128has occurred, and no signal 129.Pq if Dv PCATCH No was set 130was posted, 131.Fn tsleep 132will return 133.Er EWOULDBLOCK . 134.El 135.Pp 136The 137.Fn mtsleep 138function takes an additional argument and flag: 139.Bl -tag -width priority 140.It Fa mtx 141A 142.Xr mutex 9 143representing the lock protecting the data-structures. 144On entry 145.Fn mtsleep 146will release the lock and re-acquire the lock on return. 147.It Fa priority 148If the flag 149.Dv PNORELOCK 150is OR'ed into 151.Fa priority 152then 153.Fn mtsleep 154will not re-acquire the lock. 155.El 156.Pp 157The 158.Fn wakeup 159function will mark all processes which are currently sleeping on the identifier 160.Fa ident 161as runnable. 162Eventually, each of the processes will resume execution in the kernel 163context, causing a return from 164.Fn tsleep 165or 166.Fn mtsleep . 167Note that processes returning from sleep should always re-evaluate the 168conditions that blocked them, since a call to 169.Fn wakeup 170merely signals a 171.Em possible 172change to the blocking conditions. 173.Sh RETURN VALUES 174.Fn tsleep 175and 176.Fn mtsleep 177return 0 if they return as a result of a 178.Fn wakeup . 179If a 180.Fn tsleep 181and 182.Fn mtsleep 183return as a result of a signal, the return value is 184.Er ERESTART 185if the signal has the 186.Dv SA_RESTART 187property 188.Pq see Xr sigaction 2 , 189and 190.Er EINTR 191otherwise. 192If 193.Fn tsleep 194and 195.Fn mtsleep 196return because of a timeout, the return value is 197.Er EWOULDBLOCK . 198.Sh MIGRATING TO CONDVAR 199Note the conversion from tsleep/wakeup into 200.Xr condvar 9 201should not be done mechanically i.e. 202.Dq blindly . 203Code logic should be understood before changing, and it may also need to be 204revisited for the change. 205Please also read the 206.Xr condvar 9 207man page. 208.Pp 209The 210.Fn tsleep 211and 212.Fn mtsleep , 213and 214.Fn wakeup 215pairs should generally be replaced by 216.Xr cv_wait 9 / 217.Xr cv_wait_sig 9 / 218.Xr cv_timedwait 9 / 219.Xr cv_timedwait_sig 9 220and 221.Xr cv_signal 9 / 222.Xr cv_broadcast 9 223pairs. 224The 225.Fn cv_wait* 226variant to use can be determined from looking at the corresponding 227.Fn tsleep 228usage. 229.Pp 230There are two arguments of interest: 231.Ar timo 232and 233.Ar priority . 234The 235.Ar priority 236value may have OR'ed the flag 237.Dv PCATCH . 238.Pp 239The 240.Dv PCATCH 241flag means that the blocking thread should be awoken on signal, and 242the sleep call should be replaced with 243.Xr cv_wait_sig 9 . 244.Pp 245The 246.Ar timo 247value, if it is not zero, indicates how long to sleep, and 248the sleep call should be replaced with 249.Xr cv_timedwait 9 . 250.Pp 251If both the 252.Dv PCATCH 253flag and a non-zero 254.Ar timo 255value are specified, then 256.Xr cv_timedwait_sig 9 257should be used. 258.Pp 259A 260.Xr mutex 9 261(interlock) must be held across 262.Fn cv_wait 263and 264.Fn cv_broadcast 265calls, in order to protect state. 266Most old code will require the addition of locking, whereas some will 267require amending to remove 268.Dv PNORELOCK . 269.Sh SEE ALSO 270.Xr sigaction 2 , 271.Xr condvar 9 , 272.Xr hz 9 , 273.Xr kpause 9 , 274.Xr mutex 9 , 275.Xr rwlock 9 276.Sh HISTORY 277The sleep/wakeup process synchronization mechanism is very old. 278It appeared in a very early version of Unix. 279.Fn tsleep 280appeared in 281.Bx 4.4 . 282.Fn ltsleep 283appeared in 284.Nx 1.5 . 285