1.\" $OpenBSD: tsleep.9,v 1.14 2020/01/12 00:01:12 cheloha Exp $ 2.\" $NetBSD: sleep.9,v 1.11 1999/03/24 06:15:12 mycroft Exp $ 3.\" 4.\" Copyright (c) 1996 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by Paul Kranenburg. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 21.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 23.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29.\" POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd $Mdocdate: January 12 2020 $ 32.Dt TSLEEP 9 33.Os 34.Sh NAME 35.Nm tsleep , 36.Nm tsleep_nsec , 37.Nm msleep , 38.Nm msleep_nsec , 39.Nm rwsleep , 40.Nm rwsleep_nsec , 41.Nm wakeup , 42.Nm wakeup_n , 43.Nm wakeup_one 44.Nd process context sleep and wakeup 45.Sh SYNOPSIS 46.In sys/param.h 47.In sys/systm.h 48.Fd #define INFSLP UINT64_MAX 49.Ft int 50.Fo tsleep 51.Fa "void *ident" 52.Fa "int priority" 53.Fa "const char *wmesg" 54.Fa "int timo" 55.Fc 56.Ft int 57.Fo tsleep_nsec 58.Fa "void *ident" 59.Fa "int priority" 60.Fa "const char *wmesg" 61.Fa "uint64_t nsecs" 62.Fc 63.Ft int 64.Fo msleep 65.Fa "void *ident" 66.Fa "struct mutex *mtx" 67.Fa "int priority" 68.Fa "const char *wmesg" 69.Fa "int timo" 70.Fc 71.Ft int 72.Fo msleep_nsec 73.Fa "void *ident" 74.Fa "struct mutex *mtx" 75.Fa "int priority" 76.Fa "const char *wmesg" 77.Fa "uint64_t nsecs" 78.Fc 79.Ft int 80.Fo rwsleep 81.Fa "void *ident" 82.Fa "struct rwlock *rwl" 83.Fa "int priority" 84.Fa "const char *wmesg" 85.Fa "int timo" 86.Fc 87.Ft int 88.Fo rwsleep_nsec 89.Fa "void *ident" 90.Fa "struct rwlock *rwl" 91.Fa "int priority" 92.Fa "const char *wmesg" 93.Fa "uint64_t nsecs" 94.Fc 95.Ft void 96.Fn wakeup "void *ident" 97.Ft void 98.Fn wakeup_n "void *ident" "int count" 99.Ft void 100.Fn wakeup_one "void *ident" 101.Sh DESCRIPTION 102These functions implement voluntary context switching. 103.Fn tsleep , 104.Fn msleep 105and 106.Fn rwsleep 107are used throughout the kernel whenever processing in the current context 108cannot continue for any of the following reasons: 109.Bl -bullet -offset indent 110.It 111The current process needs to await the results of a pending I/O operation. 112.It 113The current process needs resources 114.Pq e.g. memory 115which are temporarily unavailable. 116.It 117The current process wants access to data structures which are locked by 118other processes. 119.El 120.Pp 121The 122.Fn wakeup , 123.Fn wakeup_n , 124and 125.Fn wakeup_one 126functions are used to notify sleeping processes of possible changes to the 127condition that caused them to go to sleep. 128Typically, an awakened process will -- after it has acquired a context 129again -- retry the action that blocked its operation to see if the 130.Dq blocking 131condition has cleared. 132.Pp 133The 134.Fn tsleep 135function takes the following arguments: 136.Bl -tag -width priority 137.It Fa ident 138An identifier of the 139.Dq wait channel 140representing the resource for which the current process needs to wait. 141This typically is the virtual address of some kernel data structure related 142to the resource for which the process is contending. 143The same identifier must be used in a call to 144.Fn wakeup 145to get the process going again. 146.Fa ident 147should not be 148.Dv NULL . 149.It Fa priority 150The process priority to be used when the process is awakened and put on 151the queue of runnable processes. 152This mechanism is used to optimize 153.Dq throughput 154of processes executing in kernel mode. 155If the flag 156.Dv PCATCH 157is OR'ed into 158.Fa priority 159the process checks for posted signals before and after sleeping. 160.It Fa wmesg 161A pointer to a character string indicating the reason a process is sleeping. 162The kernel does not use the string, but makes it available 163.Pq through the process structure field Li p_wmesg 164for user level utilities such as 165.Xr ps 1 . 166.It Fa timo 167If non-zero, the process will sleep for at most 168.Li timo/hz 169seconds. 170If this amount of time elapses and no 171.Fn wakeup "ident" 172has occurred, and no signal 173.Pq if Dv PCATCH No was set 174was posted, 175.Fn tsleep 176will return 177.Er EWOULDBLOCK . 178.El 179.Pp 180The 181.Fn msleep 182function behaves just like 183.Fn tsleep , 184but takes an additional argument: 185.Bl -tag -width priority 186.It Fa mtx 187A mutex that will be unlocked when the process is safely 188on the sleep queue. 189The mutex will be relocked at the end of msleep unless the 190.Dv PNORELOCK 191flag is set in the 192.Fa priority 193argument. 194.El 195.Pp 196The 197.Fn rwsleep 198function behaves just like 199.Fn tsleep , 200but takes an additional argument: 201.Bl -tag -width priority 202.It Fa rwl 203A read- or write-lock that will be unlocked when the process is safely 204on the sleep queue. 205The lock will be relocked at the end of rwsleep unless the 206.Dv PNORELOCK 207flag is set in the 208.Fa priority 209argument. 210.El 211.Pp 212The 213.Fn tsleep_nsec , 214.Fn msleep_nsec , 215and 216.Fn rwsleep_nsec 217functions behave like their unsuffixed counterparts except that they 218accept a timeout in terms of nanoseconds. 219These functions will always sleep for at least one tick, 220even if 221.Fa nsecs 222is zero. 223If 224.Fa nsecs 225is equal to 226.Dv INFSLP 227these functions do not time out, 228otherwise they sleep for at least 229.Fa nsecs 230nanoseconds. 231.Pp 232The 233.Fn wakeup 234function will mark all processes which are currently sleeping on the identifier 235.Fa ident 236as runnable. 237Eventually, each of the processes will resume execution in the kernel 238context, causing a return from 239.Fn tsleep . 240Note that processes returning from sleep should always re-evaluate the 241conditions that blocked them, since a call to 242.Fn wakeup 243merely signals a 244.Em possible 245change to the blocking conditions. 246For example, when two or more processes are waiting for an exclusive lock, 247only one of them will succeed in acquiring the lock when it is released. 248All others will have to go back to sleep and wait for the next opportunity. 249.Pp 250The 251.Fn wakeup_n 252and 253.Fn wakeup_one 254functions behave similarly to 255.Fn wakeup 256except that only 257.Fa count 258or one process, respectively, is marked runnable. 259.Sh RETURN VALUES 260.Fn tsleep , 261.Fn tsleep_nsec , 262.Fn msleep , 263.Fn msleep_nsec , 264.Fn rwsleep , 265and 266.Fn rwsleep_nsec 267return 0 if they return as a result of a 268.Fn wakeup . 269If they return as a result of a signal, the return value is 270.Er ERESTART 271if the signal has the 272.Dv SA_RESTART 273property 274.Pq see Xr sigaction 2 , 275and 276.Er EINTR 277otherwise. 278If they return as a result of a timeout, the return value is 279.Er EWOULDBLOCK . 280.Sh CODE REFERENCES 281These functions are implemented in the file 282.Pa sys/kern/kern_synch.c . 283.Sh SEE ALSO 284.Xr hz 9 , 285.Xr mi_switch 9 , 286.Xr timeout 9 287