1.\" $OpenBSD: timeout.9,v 1.56 2023/01/01 01:19:18 cheloha Exp $ 2.\" 3.\" Copyright (c) 2000 Artur Grabowski <art@openbsd.org> 4.\" Copyright (c) 2021, 2022 Scott Cheloha <cheloha@openbsd.org> 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. The name of the author may not be used to endorse or promote products 14.\" derived from this software without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, 17.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY 18.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 19.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 20.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 21.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 22.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 23.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 24.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 25.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd $Mdocdate: January 1 2023 $ 28.Dt TIMEOUT_SET 9 29.Os 30.Sh NAME 31.Nm timeout_set , 32.Nm timeout_set_flags , 33.Nm timeout_set_proc , 34.Nm timeout_add , 35.Nm timeout_add_sec , 36.Nm timeout_add_msec , 37.Nm timeout_add_usec , 38.Nm timeout_add_nsec , 39.Nm timeout_add_tv , 40.Nm timeout_abs_ts , 41.Nm timeout_del , 42.Nm timeout_del_barrier , 43.Nm timeout_barrier , 44.Nm timeout_pending , 45.Nm timeout_initialized , 46.Nm timeout_triggered , 47.Nm TIMEOUT_INITIALIZER , 48.Nm TIMEOUT_INITIALIZER_FLAGS 49.Nd execute a function in the future 50.Sh SYNOPSIS 51.In sys/types.h 52.In sys/timeout.h 53.Ft void 54.Fo timeout_set 55.Fa "struct timeout *to" 56.Fa "void (*fn)(void *)" 57.Fa "void *arg" 58.Fc 59.Ft void 60.Fo timeout_set_flags 61.Fa "struct timeout *to" 62.Fa "void (*fn)(void *)" 63.Fa "void *arg" 64.Fa "int kclock" 65.Fa "int flags" 66.Fc 67.Ft void 68.Fo timeout_set_proc 69.Fa "struct timeout *to" 70.Fa "void (*fn)(void *)" 71.Fa "void *arg" 72.Fc 73.Ft int 74.Fo timeout_add 75.Fa "struct timeout *to" 76.Fa "int nticks" 77.Fc 78.Ft int 79.Fo timeout_add_sec 80.Fa "struct timeout *to" 81.Fa "int secs" 82.Fc 83.Ft int 84.Fo timeout_add_msec 85.Fa "struct timeout *to" 86.Fa "int msecs" 87.Fc 88.Ft int 89.Fo timeout_add_usec 90.Fa "struct timeout *to" 91.Fa "int usecs" 92.Fc 93.Ft int 94.Fo timeout_add_nsec 95.Fa "struct timeout *to" 96.Fa "int nsecs" 97.Fc 98.Ft int 99.Fo timeout_add_tv 100.Fa "struct timeout *to" 101.Fa "struct timeval *tv" 102.Fc 103.Ft int 104.Fo timeout_abs_ts 105.Fa "struct timeout *to" 106.Fa "const struct timespec *abs" 107.Fc 108.Ft int 109.Fo timeout_del 110.Fa "struct timeout *to" 111.Fc 112.Ft int 113.Fo timeout_del_barrier 114.Fa "struct timeout *to" 115.Fc 116.Ft void 117.Fo timeout_barrier 118.Fa "struct timeout *to" 119.Fc 120.Ft int 121.Fo timeout_pending 122.Fa "struct timeout *to" 123.Fc 124.Ft int 125.Fo timeout_initialized 126.Fa "struct timeout *to" 127.Fc 128.Ft int 129.Fo timeout_triggered 130.Fa "struct timeout *to" 131.Fc 132.Fo TIMEOUT_INITIALIZER 133.Fa "void (*fn)(void *)" 134.Fa "void *arg" 135.Fc 136.Fo TIMEOUT_INITIALIZER_FLAGS 137.Fa "void (*fn)(void *)" 138.Fa "void *arg" 139.Fa "int kclock" 140.Fa "int flags" 141.Fc 142.Sh DESCRIPTION 143The 144.Nm timeout 145subsystem schedules functions for asynchronous execution in the future. 146.Pp 147All state is encapsulated in a 148.Vt struct timeout 149allocated by the caller. 150A timeout must be initialized before it may be used as input to other 151functions in the API. 152Once initialized, 153a timeout does not need to be reinitialized unless its function or argument 154must change. 155.Pp 156The 157.Fn timeout_set 158function initializes the timeout 159.Fa to . 160When the timeout is executed, 161the function 162.Fa fn 163will be called with 164.Fa arg 165as its sole parameter. 166The timeout is implicitly scheduled against the 167.Dv KCLOCK_NONE 168clock and is not configured with any additional flags. 169.Pp 170The 171.Fn timeout_set_flags 172function is similar to 173.Fn timeout_set , 174except that it takes two additional parameters: 175.Bl -tag -width kclock 176.It Fa kclock 177The timeout is scheduled against the given 178.Fa kclock , 179which must be one of the following: 180.Bl -tag -width KCLOCK_UPTIME 181.It Dv KCLOCK_NONE 182Low resolution tick-based clock. 183The granularity of this clock is limited by the 184.Xr hardclock 9 , 185which executes roughly 186.Xr hz 9 187times per second. 188.It Dv KCLOCK_UPTIME 189The uptime clock. 190Counts the time elapsed since the system booted. 191.El 192.It Fa flags 193The timeout's behavior may be configured with the bitwise OR of 194zero or more of the following 195.Fa flags : 196.Bl -tag -width TIMEOUT_PROC 197.It Dv TIMEOUT_PROC 198Execute the timeout in a process context instead of the default 199.Dv IPL_SOFTCLOCK 200interrupt context. 201.El 202.El 203.Pp 204The 205.Fn timeout_set_proc 206function is similar to 207.Fn timeout_set , 208except that the given timeout is configured with the 209.Dv TIMEOUT_PROC 210flag. 211.Pp 212A timeout may also be initialized statically. 213The 214.Fn TIMEOUT_INITIALIZER 215macro is equivalent to the 216.Fn timeout_set 217function and the 218.Fn TIMEOUT_INITIALIZER_FLAGS 219macro is equivalent to the 220.Fn timeout_set_flags 221function. 222.Pp 223The interfaces available for scheduling a timeout vary with the 224.Fa kclock 225set during initialization. 226.Pp 227.Dv KCLOCK_NONE 228timeouts may be scheduled with the function 229.Fn timeout_add , 230which schedules the given timeout to execute after at least 231.Fa nticks 232.Xr hardclock 9 233ticks have elapsed. 234In practice, 235.Fa nticks 236ticks will usually elapse in slightly less than 237.Pq Fa nticks Cm / Dv hz 238seconds. 239Negative values of 240.Fa nticks 241are illegal. 242If 243.Fa nticks 244is zero it will be silently rounded up to one. 245.Pp 246For convenience, 247.Dv KCLOCK_NONE 248timeouts may also be scheduled with 249.Fn timeout_add_sec , 250.Fn timeout_add_msec , 251.Fn timeout_add_usec , 252.Fn timeout_add_nsec , 253or 254.Fn timeout_add_tv . 255These wrapper functions convert their input durations to a count of 256.Xr hardclock 9 257ticks before calling 258.Fn timeout_add 259to schedule the given timeout. 260.Pp 261Timeouts for any other 262.Fa kclock 263may be scheduled with 264.Fn timeout_abs_ts , 265which schedules the given timeout to execute at or after the absolute time 266.Fa abs 267has elapsed on the timeout's 268.Fa kclock . 269.Pp 270Once scheduled, 271a timeout is said to be 272.Qq pending . 273A pending timeout may not be reinitialized with 274.Fn timeout_set , 275.Fn timeout_set_flags , 276or 277.Fn timeout_set_proc 278until it has been executed or it has been cancelled with 279.Fn timeout_del 280or 281.Fn timeout_del_barrier . 282A pending timeout may be rescheduled without first cancelling it with 283.Fn timeout_del 284or 285.Fn timeout_del_barrier : 286the new expiration time will quietly supersede the original. 287.Pp 288The function 289.Fn timeout_del 290cancels any pending execution of the given timeout. 291.Pp 292The 293.Fn timeout_del_barrier 294function is similar to 295.Fn timeout_del , 296except that it also blocks until any current execution of the given timeout 297has completed. 298.Pp 299The 300.Fn timeout_barrier 301function blocks until any current execution of the given timeout 302has completed. 303.Pp 304Callers of 305.Fn timeout_barrier 306and 307.Fn timeout_del_barrier 308must not hold locks that can block processing in the timeout's context. 309Otherwise, the system will deadlock. 310.Pp 311The 312.Fn timeout_pending 313macro indicates whether the given timeout is scheduled for execution. 314A timeout's pending status is cleared when it executes or is cancelled. 315.Pp 316The 317.Fn timeout_initialized 318macro indicates whether the given timeout has been initialized with 319.Fn timeout_set 320or 321.Fn timeout_set_flags . 322This macro must not be used unless the memory pointed to by 323.Fa to 324has been zeroed, 325or its return value is meaningless. 326.Pp 327The 328.Fn timeout_triggered 329macro indicates whether the given timeout is executing or has finished 330executing. 331Rescheduling or cancelling a timeout clears its triggered status. 332.Sh CONTEXT 333.Fn timeout_set , 334.Fn timeout_set_flags , 335.Fn timeout_set_proc , 336.Fn timeout_add , 337.Fn timeout_add_sec , 338.Fn timeout_add_msec , 339.Fn timeout_add_usec , 340.Fn timeout_add_nsec , 341.Fn timeout_add_tv , 342.Fn timeout_abs_ts , 343.Fn timeout_del , 344.Fn timeout_pending , 345.Fn timeout_initialized , 346and 347.Fn timeout_triggered 348may be called during autoconf, 349from process context, 350or from any interrupt context. 351.Pp 352.Fn timeout_barrier 353and 354.Fn timeout_del_barrier 355may only be called from process context. 356.Pp 357When a timeout is executed, 358the function 359.Fa fn 360set during initialization is called from the 361.Dv IPL_SOFTCLOCK 362interrupt context, 363or a process context if the timeout was configured with the 364.Dv TIMEOUT_PROC 365flag. 366The function 367.Fa fn 368must not block and must be safe to execute on any CPU in the system. 369.Pp 370Currently, 371all timeouts are executed under the kernel lock. 372.Sh RETURN VALUES 373.Fn timeout_add , 374.Fn timeout_add_sec , 375.Fn timeout_add_msec , 376.Fn timeout_add_usec , 377.Fn timeout_add_nsec , 378.Fn timeout_add_tv , 379and 380.Fn timeout_abs_ts 381return 1 if the timeout 382.Fa to 383is newly scheduled, 384or zero if the timeout was already pending. 385.Pp 386.Fn timeout_del 387and 388.Fn timeout_del_barrier 389return 1 if the timeout 390.Fa to 391was pending, 392or zero otherwise. 393.Pp 394.Fn timeout_pending , 395.Fn timeout_initialized , 396and 397.Fn timeout_triggered 398return non-zero if the corresponding condition is true, 399or zero otherwise. 400.Sh CODE REFERENCES 401.Pa sys/kern/kern_timeout.c 402.Sh SEE ALSO 403.Xr hardclock 9 , 404.Xr hz 9 , 405.Xr microtime 9 , 406.Xr splclock 9 , 407.Xr task_add 9 , 408.Xr tsleep 9 , 409.Xr tvtohz 9 410.Rs 411.%A George Varghese 412.%A Anthony Lauck 413.%B Hashed and hierarchical timing wheels: efficient data structures for \ 414implementing a timer facility 415.%O especially Schemes 6 and 7 416.%I IEEE/ACM 417.%J Transactions on Networking 418.%V vol. 5 419.%N no. 6 420.%P pp. 824\(en834 421.%D December 1997 422.Re 423