1.\" $OpenBSD: timeout.9,v 1.59 2024/08/11 00:50:38 dlg 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: August 11 2024 $ 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 "uint64_t msecs" 87.Fc 88.Ft int 89.Fo timeout_add_usec 90.Fa "struct timeout *to" 91.Fa "uint64_t usecs" 92.Fc 93.Ft int 94.Fo timeout_add_nsec 95.Fa "struct timeout *to" 96.Fa "uint64_t 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_MPSAFE 197.It Dv TIMEOUT_PROC 198Execute the timeout in a process context instead of the default 199.Dv IPL_SOFTCLOCK 200interrupt context. 201.It Dv TIMEOUT_MPSAFE 202Execute the timeout without the kernel lock. 203Requires the 204.Dv TIMEOUT_PROC 205flag. 206.El 207.El 208.Pp 209The 210.Fn timeout_set_proc 211function is similar to 212.Fn timeout_set , 213except that the given timeout is configured with the 214.Dv TIMEOUT_PROC 215flag. 216.Pp 217A timeout may also be initialized statically. 218The 219.Fn TIMEOUT_INITIALIZER 220macro is equivalent to the 221.Fn timeout_set 222function and the 223.Fn TIMEOUT_INITIALIZER_FLAGS 224macro is equivalent to the 225.Fn timeout_set_flags 226function. 227.Pp 228The interfaces available for scheduling a timeout vary with the 229.Fa kclock 230set during initialization. 231.Pp 232.Dv KCLOCK_NONE 233timeouts may be scheduled with the function 234.Fn timeout_add , 235which schedules the given timeout to execute after at least 236.Fa nticks 237.Xr hardclock 9 238ticks have elapsed. 239In practice, 240.Fa nticks 241ticks will usually elapse in slightly less than 242.Pq Fa nticks Cm / Dv hz 243seconds. 244Negative values of 245.Fa nticks 246are illegal. 247If 248.Fa nticks 249is zero it will be silently rounded up to one. 250.Pp 251For convenience, 252.Dv KCLOCK_NONE 253timeouts may also be scheduled with 254.Fn timeout_add_sec , 255.Fn timeout_add_msec , 256.Fn timeout_add_usec , 257.Fn timeout_add_nsec , 258or 259.Fn timeout_add_tv . 260These wrapper functions convert their input durations to a count of 261.Xr hardclock 9 262ticks before calling 263.Fn timeout_add 264to schedule the given timeout. 265.Pp 266Timeouts for any other 267.Fa kclock 268may be scheduled with 269.Fn timeout_abs_ts , 270which schedules the given timeout to execute at or after the absolute time 271.Fa abs 272has elapsed on the timeout's 273.Fa kclock . 274.Pp 275Once scheduled, 276a timeout is said to be 277.Qq pending . 278A pending timeout may not be reinitialized with 279.Fn timeout_set , 280.Fn timeout_set_flags , 281or 282.Fn timeout_set_proc 283until it has been executed or it has been cancelled with 284.Fn timeout_del 285or 286.Fn timeout_del_barrier . 287A pending timeout may be rescheduled without first cancelling it with 288.Fn timeout_del 289or 290.Fn timeout_del_barrier : 291the new expiration time will quietly supersede the original. 292.Pp 293The function 294.Fn timeout_del 295cancels any pending execution of the given timeout. 296.Pp 297The 298.Fn timeout_del_barrier 299function is similar to 300.Fn timeout_del , 301except that it also blocks until any current execution of the given timeout 302has completed. 303.Pp 304The 305.Fn timeout_barrier 306function blocks until any current execution of the given timeout 307has completed. 308.Pp 309Callers of 310.Fn timeout_barrier 311and 312.Fn timeout_del_barrier 313must not hold locks that can block processing in the timeout's context. 314Otherwise, the system will deadlock. 315.Pp 316The 317.Fn timeout_pending 318macro indicates whether the given timeout is scheduled for execution. 319A timeout's pending status is cleared when it executes or is cancelled. 320.Pp 321The 322.Fn timeout_initialized 323macro indicates whether the given timeout has been initialized with 324.Fn timeout_set 325or 326.Fn timeout_set_flags . 327This macro must not be used unless the memory pointed to by 328.Fa to 329has been zeroed, 330or its return value is meaningless. 331.Pp 332The 333.Fn timeout_triggered 334macro indicates whether the given timeout is executing or has finished 335executing. 336Rescheduling or cancelling a timeout clears its triggered status. 337.Sh CONTEXT 338.Fn timeout_set , 339.Fn timeout_set_flags , 340.Fn timeout_set_proc , 341.Fn timeout_add , 342.Fn timeout_add_sec , 343.Fn timeout_add_msec , 344.Fn timeout_add_usec , 345.Fn timeout_add_nsec , 346.Fn timeout_add_tv , 347.Fn timeout_abs_ts , 348.Fn timeout_del , 349.Fn timeout_pending , 350.Fn timeout_initialized , 351and 352.Fn timeout_triggered 353may be called during autoconf, 354from process context, 355or from any interrupt context. 356.Pp 357.Fn timeout_barrier 358and 359.Fn timeout_del_barrier 360may only be called from process context. 361.Pp 362When a timeout is executed, 363the function 364.Fa fn 365set during initialization is called from the 366.Dv IPL_SOFTCLOCK 367interrupt context, 368or a process context if the timeout was configured with the 369.Dv TIMEOUT_PROC 370flag. 371The function 372.Fa fn 373must not block and must be safe to execute on any CPU in the system. 374.Pp 375Timeouts without the 376.Dv TIMEOUT_MPSAFE 377flag are executed under the kernel lock. 378.Sh RETURN VALUES 379.Fn timeout_add , 380.Fn timeout_add_sec , 381.Fn timeout_add_msec , 382.Fn timeout_add_usec , 383.Fn timeout_add_nsec , 384.Fn timeout_add_tv , 385and 386.Fn timeout_abs_ts 387return 1 if the timeout 388.Fa to 389is newly scheduled, 390or zero if the timeout was already pending. 391.Pp 392.Fn timeout_del 393and 394.Fn timeout_del_barrier 395return 1 if the timeout 396.Fa to 397was pending, 398or zero otherwise. 399.Pp 400.Fn timeout_pending , 401.Fn timeout_initialized , 402and 403.Fn timeout_triggered 404return non-zero if the corresponding condition is true, 405or zero otherwise. 406.Sh CODE REFERENCES 407.Pa sys/kern/kern_timeout.c 408.Sh SEE ALSO 409.Xr hardclock 9 , 410.Xr hz 9 , 411.Xr microtime 9 , 412.Xr splclock 9 , 413.Xr task_add 9 , 414.Xr tsleep 9 , 415.Xr tvtohz 9 416.Rs 417.%A George Varghese 418.%A Anthony Lauck 419.%B Hashed and hierarchical timing wheels: efficient data structures for \ 420implementing a timer facility 421.%O especially Schemes 6 and 7 422.%I IEEE/ACM 423.%J Transactions on Networking 424.%V vol. 5 425.%N no. 6 426.%P pp. 824\(en834 427.%D December 1997 428.Re 429