1.\" $OpenBSD: timeout.9,v 1.55 2022/06/22 14:10:49 visa Exp $ 2.\" 3.\" Copyright (c) 2000 Artur Grabowski <art@openbsd.org> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. The name of the author may not be used to endorse or promote products 13.\" derived from this software without specific prior written permission. 14.\" 15.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, 16.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY 17.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 18.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 19.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 20.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 21.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 22.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 23.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 24.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.Dd $Mdocdate: June 22 2022 $ 27.Dt TIMEOUT_SET 9 28.Os 29.Sh NAME 30.Nm timeout_set , 31.Nm timeout_set_flags , 32.Nm timeout_set_proc , 33.Nm timeout_add , 34.Nm timeout_add_sec , 35.Nm timeout_add_msec , 36.Nm timeout_add_nsec , 37.Nm timeout_add_usec , 38.Nm timeout_add_tv , 39.Nm timeout_del , 40.Nm timeout_del_barrier , 41.Nm timeout_barrier , 42.Nm timeout_pending , 43.Nm timeout_initialized , 44.Nm timeout_triggered , 45.Nm TIMEOUT_INITIALIZER , 46.Nm TIMEOUT_INITIALIZER_FLAGS 47.Nd execute a function after a specified period of time 48.Sh SYNOPSIS 49.In sys/types.h 50.In sys/timeout.h 51.Ft void 52.Fn timeout_set "struct timeout *to" "void (*fn)(void *)" "void *arg" 53.Ft void 54.Fo timeout_set_flags 55.Fa "struct timeout *to" 56.Fa "void (*fn)(void *)" 57.Fa "void *arg" 58.Fa "int flags" 59.Fc 60.Ft void 61.Fn timeout_set_proc "struct timeout *to" "void (*fn)(void *)" "void *arg" 62.Ft int 63.Fn timeout_add "struct timeout *to" "int ticks" 64.Ft int 65.Fn timeout_del "struct timeout *to" 66.Ft int 67.Fn timeout_del_barrier "struct timeout *to" 68.Ft void 69.Fn timeout_barrier "struct timeout *to" 70.Ft int 71.Fn timeout_pending "struct timeout *to" 72.Ft int 73.Fn timeout_initialized "struct timeout *to" 74.Ft int 75.Fn timeout_triggered "struct timeout *to" 76.Ft int 77.Fn timeout_add_tv "struct timeout *to" "struct timeval *" 78.Ft int 79.Fn timeout_add_sec "struct timeout *to" "int sec" 80.Ft int 81.Fn timeout_add_msec "struct timeout *to" "int msec" 82.Ft int 83.Fn timeout_add_usec "struct timeout *to" "int usec" 84.Ft int 85.Fn timeout_add_nsec "struct timeout *to" "int nsec" 86.Fn TIMEOUT_INITIALIZER "void (*fn)(void *)" "void *arg" 87.Fn TIMEOUT_INITIALIZER_FLAGS "void (*fn)(void *)" "void *arg" "int flags" 88.Sh DESCRIPTION 89The 90.Nm timeout 91API provides a mechanism to execute a function at a given time. 92The granularity of the time is limited by the granularity of the 93.Xr hardclock 9 94timer which executes 95.Xr hz 9 96times a second. 97.Pp 98It is the responsibility of the caller to provide these functions with 99pre-allocated timeout structures. 100.Pp 101The 102.Fn timeout_set 103function prepares the timeout structure 104.Fa to 105to be used in future calls to 106.Fn timeout_add 107and 108.Fn timeout_del . 109The timeout will be prepared to call the function specified by the 110.Fa fn 111argument with a 112.Fa void * 113argument given in the 114.Fa arg 115argument. 116Once initialized, the 117.Fa to 118structure can be used repeatedly in 119.Fn timeout_add 120and 121.Fn timeout_del 122and does not need to be reinitialized unless 123the function called and/or its argument must change. 124.Pp 125The 126.Fn timeout_set_flags 127function is similar to 128.Fn timeout_set 129but it additionally accepts the bitwise OR of zero or more of the 130following 131.Fa flags : 132.Bl -tag -width TIMEOUT_PROC -offset indent 133.It Dv TIMEOUT_PROC 134Runs the timeout in a process context instead of the default 135.Dv IPL_SOFTCLOCK 136interrupt context. 137.El 138.Pp 139The 140.Fn timeout_set_proc 141function is similar to 142.Fn timeout_set 143but it runs the timeout in a process context instead of the default 144.Dv IPL_SOFTCLOCK 145interrupt context. 146.Pp 147The function 148.Fn timeout_add 149schedules the execution of the 150.Fa to 151timeout in at least 152.Fa ticks Ns /hz 153seconds. 154Negative values of 155.Fa ticks 156are illegal. 157If the value is 158.Sq 0 159it will, in the current implementation, be treated as 160.Sq 1 , 161but in the future it might cause an immediate timeout. 162The timeout in the 163.Fa to 164argument must be already initialized by 165.Fn timeout_set , 166.Fn timeout_set_flags , 167or 168.Fn timeout_set_proc 169and may not be used in calls to 170.Fn timeout_set , 171.Fn timeout_set_flags , 172or 173.Fn timeout_set_proc 174until it has timed out or been removed with 175.Fn timeout_del . 176If the timeout in the 177.Fa to 178argument is already scheduled, the old execution time will be 179replaced by the new one. 180.Pp 181The function 182.Fn timeout_del 183will cancel the timeout in the argument 184.Fa to . 185If the timeout has already executed or has never been added, 186the call will have no effect. 187.Pp 188.Fn timeout_del_barrier 189is like 190.Fn timeout_del 191but it will wait until any current execution of the timeout has completed. 192.Pp 193.Fn timeout_barrier 194ensures that any current execution of the timeout in the argument 195.Fa to 196has completed before returning. 197.Pp 198The caller of 199.Fn timeout_barrier 200or 201.Fn timeout_del_barrier 202must not hold locks that can block processing in the timeout's context. 203Otherwise, the system will deadlock. 204.Pp 205The 206.Fn timeout_pending 207macro can be used to check if a timeout is scheduled to run. 208.Pp 209The 210.Fn timeout_initialized 211macro can be used to check if a timeout has been initialized. 212.Pp 213The 214.Fn timeout_triggered 215macro can be used to check if a timeout is running or has been run. 216The 217.Fn timeout_add 218and 219.Fn timeout_del 220functions clear the triggered state for that timeout. 221.Pp 222When possible, use the 223.Fn timeout_add_tv , 224.Fn timeout_add_sec , 225.Fn timeout_add_msec , 226.Fn timeout_add_usec , 227and 228.Fn timeout_add_nsec 229functions instead of 230.Fn timeout_add . 231Those functions add a timeout whilst converting the time specified 232by the respective types. 233They also defer the timeout handler for at least one tick if called 234with a positive value. 235.Pp 236A timeout declaration can be initialised with the 237.Fn TIMEOUT_INITIALIZER 238macro. 239The timeout will be prepared to call the function specified by the 240.Fa fn 241argument with the 242.Fa void * 243argument given in 244.Fa arg . 245.Pp 246The 247.Fn TIMEOUT_INITIALIZER_FLAGS 248macro is similar to 249.Fn TIMEOUT_INITIALIZER , 250but it accepts additional flags. 251See the 252.Fn timeout_set_flags 253function for details. 254.Sh CONTEXT 255.Fn timeout_set , 256.Fn timeout_set_flags , 257and 258.Fn timeout_set_proc 259can be called during autoconf, from process context, or from interrupt 260context. 261.Pp 262.Fn timeout_add , 263.Fn timeout_add_sec , 264.Fn timeout_add_msec , 265.Fn timeout_add_nsec , 266.Fn timeout_add_usec , 267.Fn timeout_add_tv , 268.Fn timeout_del , 269.Fn timeout_pending , 270.Fn timeout_initialized , 271.Fn timeout_triggered 272can be called during autoconf, from process context, or from any 273interrupt context at or below 274.Dv IPL_CLOCK . 275.Pp 276.Fn timeout_barrier 277and 278.Fn timeout_del_barrier 279can be called from process context. 280.Pp 281When the timeout runs, the 282.Fa fn 283argument to 284.Fn timeout_set 285or 286.Fn timeout_set_flags 287will be called in an interrupt context at 288.Dv IPL_SOFTCLOCK 289or a process context if the 290.Dv TIMEOUT_PROC 291flag was given at initialization. 292The 293.Fa fn 294argument to 295.Fn timeout_set_proc 296will be called in a process context. 297.Sh RETURN VALUES 298.Fn timeout_add , 299.Fn timeout_add_sec , 300.Fn timeout_add_msec , 301.Fn timeout_add_nsec , 302.Fn timeout_add_usec , 303and 304.Fn timeout_add_tv 305will return 1 if the timeout 306.Fa to 307was added to the timeout schedule or 0 if it was already queued. 308.Pp 309.Fn timeout_del 310and 311.Fn timeout_del_barrier 312will return 1 if the timeout 313.Fa to 314was removed from the pending timeout schedule or 0 if it was not 315currently queued. 316.Sh CODE REFERENCES 317These functions are implemented in the file 318.Pa sys/kern/kern_timeout.c . 319.Sh SEE ALSO 320.Xr hz 9 , 321.Xr splclock 9 , 322.Xr tsleep 9 , 323.Xr tvtohz 9 324.Rs 325.%A George Varghese 326.%A Anthony Lauck 327.%B Hashed and hierarchical timing wheels: efficient data structures for \ 328implementing a timer facility 329.%O especially Schemes 6 and 7 330.%I IEEE/ACM 331.%J Transactions on Networking 332.%V vol. 5 333.%N no. 6 334.%P pp. 824\(en834 335.%D December 1997 336.Re 337