1.\" $OpenBSD: tsleep.9,v 1.15 2020/03/20 03:37:09 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: March 20 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.Fd #define MAXTSLP (UINT64_MAX - 1) 50.Ft int 51.Fo tsleep 52.Fa "void *ident" 53.Fa "int priority" 54.Fa "const char *wmesg" 55.Fa "int timo" 56.Fc 57.Ft int 58.Fo tsleep_nsec 59.Fa "void *ident" 60.Fa "int priority" 61.Fa "const char *wmesg" 62.Fa "uint64_t nsecs" 63.Fc 64.Ft int 65.Fo msleep 66.Fa "void *ident" 67.Fa "struct mutex *mtx" 68.Fa "int priority" 69.Fa "const char *wmesg" 70.Fa "int timo" 71.Fc 72.Ft int 73.Fo msleep_nsec 74.Fa "void *ident" 75.Fa "struct mutex *mtx" 76.Fa "int priority" 77.Fa "const char *wmesg" 78.Fa "uint64_t nsecs" 79.Fc 80.Ft int 81.Fo rwsleep 82.Fa "void *ident" 83.Fa "struct rwlock *rwl" 84.Fa "int priority" 85.Fa "const char *wmesg" 86.Fa "int timo" 87.Fc 88.Ft int 89.Fo rwsleep_nsec 90.Fa "void *ident" 91.Fa "struct rwlock *rwl" 92.Fa "int priority" 93.Fa "const char *wmesg" 94.Fa "uint64_t nsecs" 95.Fc 96.Ft void 97.Fn wakeup "void *ident" 98.Ft void 99.Fn wakeup_n "void *ident" "int count" 100.Ft void 101.Fn wakeup_one "void *ident" 102.Sh DESCRIPTION 103These functions implement voluntary context switching. 104.Fn tsleep , 105.Fn msleep 106and 107.Fn rwsleep 108are used throughout the kernel whenever processing in the current context 109cannot continue for any of the following reasons: 110.Bl -bullet -offset indent 111.It 112The current process needs to await the results of a pending I/O operation. 113.It 114The current process needs resources 115.Pq e.g. memory 116which are temporarily unavailable. 117.It 118The current process wants access to data structures which are locked by 119other processes. 120.El 121.Pp 122The 123.Fn wakeup , 124.Fn wakeup_n , 125and 126.Fn wakeup_one 127functions are used to notify sleeping processes of possible changes to the 128condition that caused them to go to sleep. 129Typically, an awakened process will -- after it has acquired a context 130again -- retry the action that blocked its operation to see if the 131.Dq blocking 132condition has cleared. 133.Pp 134The 135.Fn tsleep 136function takes the following arguments: 137.Bl -tag -width priority 138.It Fa ident 139An identifier of the 140.Dq wait channel 141representing the resource for which the current process needs to wait. 142This typically is the virtual address of some kernel data structure related 143to the resource for which the process is contending. 144The same identifier must be used in a call to 145.Fn wakeup 146to get the process going again. 147.Fa ident 148should not be 149.Dv NULL . 150.It Fa priority 151The process priority to be used when the process is awakened and put on 152the queue of runnable processes. 153This mechanism is used to optimize 154.Dq throughput 155of processes executing in kernel mode. 156If the flag 157.Dv PCATCH 158is OR'ed into 159.Fa priority 160the process checks for posted signals before and after sleeping. 161.It Fa wmesg 162A pointer to a character string indicating the reason a process is sleeping. 163The kernel does not use the string, but makes it available 164.Pq through the process structure field Li p_wmesg 165for user level utilities such as 166.Xr ps 1 . 167.It Fa timo 168If non-zero, the process will sleep for at most 169.Li timo/hz 170seconds. 171If this amount of time elapses and no 172.Fn wakeup "ident" 173has occurred, and no signal 174.Pq if Dv PCATCH No was set 175was posted, 176.Fn tsleep 177will return 178.Er EWOULDBLOCK . 179.El 180.Pp 181The 182.Fn msleep 183function behaves just like 184.Fn tsleep , 185but takes an additional argument: 186.Bl -tag -width priority 187.It Fa mtx 188A mutex that will be unlocked when the process is safely 189on the sleep queue. 190The mutex will be relocked at the end of msleep unless the 191.Dv PNORELOCK 192flag is set in the 193.Fa priority 194argument. 195.El 196.Pp 197The 198.Fn rwsleep 199function behaves just like 200.Fn tsleep , 201but takes an additional argument: 202.Bl -tag -width priority 203.It Fa rwl 204A read- or write-lock that will be unlocked when the process is safely 205on the sleep queue. 206The lock will be relocked at the end of rwsleep unless the 207.Dv PNORELOCK 208flag is set in the 209.Fa priority 210argument. 211.El 212.Pp 213The 214.Fn tsleep_nsec , 215.Fn msleep_nsec , 216and 217.Fn rwsleep_nsec 218functions behave like their unsuffixed counterparts except that they 219accept a timeout in terms of nanoseconds. 220These functions will always sleep for at least one tick, 221even if 222.Fa nsecs 223is zero. 224If 225.Fa nsecs 226is equal to 227.Dv INFSLP 228these functions do not time out, 229otherwise they sleep for at least 230.Fa nsecs 231nanoseconds. 232.Pp 233The 234.Fn wakeup 235function will mark all processes which are currently sleeping on the identifier 236.Fa ident 237as runnable. 238Eventually, each of the processes will resume execution in the kernel 239context, causing a return from 240.Fn tsleep . 241Note that processes returning from sleep should always re-evaluate the 242conditions that blocked them, since a call to 243.Fn wakeup 244merely signals a 245.Em possible 246change to the blocking conditions. 247For example, when two or more processes are waiting for an exclusive lock, 248only one of them will succeed in acquiring the lock when it is released. 249All others will have to go back to sleep and wait for the next opportunity. 250.Pp 251The 252.Fn wakeup_n 253and 254.Fn wakeup_one 255functions behave similarly to 256.Fn wakeup 257except that only 258.Fa count 259or one process, respectively, is marked runnable. 260.Sh RETURN VALUES 261.Fn tsleep , 262.Fn tsleep_nsec , 263.Fn msleep , 264.Fn msleep_nsec , 265.Fn rwsleep , 266and 267.Fn rwsleep_nsec 268return 0 if they return as a result of a 269.Fn wakeup . 270If they return as a result of a signal, the return value is 271.Er ERESTART 272if the signal has the 273.Dv SA_RESTART 274property 275.Pq see Xr sigaction 2 , 276and 277.Er EINTR 278otherwise. 279If they return as a result of a timeout, the return value is 280.Er EWOULDBLOCK . 281.Sh CODE REFERENCES 282These functions are implemented in the file 283.Pa sys/kern/kern_synch.c . 284.Sh SEE ALSO 285.Xr hz 9 , 286.Xr mi_switch 9 , 287.Xr timeout 9 288