1.\" $OpenBSD: timeout.9,v 1.50 2020/01/03 02:16:38 cheloha 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: January 3 2020 $ 27.Dt TIMEOUT_SET 9 28.Os 29.Sh NAME 30.Nm timeout_set , 31.Nm timeout_set_flags , 32.Nm timeout_add , 33.Nm timeout_add_sec , 34.Nm timeout_add_msec , 35.Nm timeout_add_nsec , 36.Nm timeout_add_usec , 37.Nm timeout_add_tv , 38.Nm timeout_add_ts , 39.Nm timeout_add_bt , 40.Nm timeout_del , 41.Nm timeout_del_barrier , 42.Nm timeout_barrier , 43.Nm timeout_pending , 44.Nm timeout_initialized , 45.Nm timeout_triggered , 46.Nm TIMEOUT_INITIALIZER , 47.Nm TIMEOUT_INITIALIZER_FLAGS 48.Nd execute a function after a specified period of time 49.Sh SYNOPSIS 50.In sys/types.h 51.In sys/timeout.h 52.Ft void 53.Fn timeout_set "struct timeout *to" "void (*fn)(void *)" "void *arg" 54.Ft void 55.Fo timeout_set_flags 56.Fa "struct timeout *to" 57.Fa "void (*fn)(void *)" 58.Fa "void *arg" 59.Fa "int flags" 60.Fc 61.Ft int 62.Fn timeout_add "struct timeout *to" "int ticks" 63.Ft int 64.Fn timeout_del "struct timeout *to" 65.Ft int 66.Fn timeout_del_barrier "struct timeout *to" 67.Ft void 68.Fn timeout_barrier "struct timeout *to" 69.Ft int 70.Fn timeout_pending "struct timeout *to" 71.Ft int 72.Fn timeout_initialized "struct timeout *to" 73.Ft int 74.Fn timeout_triggered "struct timeout *to" 75.Ft int 76.Fn timeout_add_tv "struct timeout *to" "struct timeval *" 77.Ft int 78.Fn timeout_add_ts "struct timeout *to" "struct timespec *" 79.Ft int 80.Fn timeout_add_bt "struct timeout *to" "struct bintime *" 81.Ft int 82.Fn timeout_add_sec "struct timeout *to" "int sec" 83.Ft int 84.Fn timeout_add_msec "struct timeout *to" "int msec" 85.Ft int 86.Fn timeout_add_usec "struct timeout *to" "int usec" 87.Ft int 88.Fn timeout_add_nsec "struct timeout *to" "int nsec" 89.Fn TIMEOUT_INITIALIZER "void (*fn)(void *)" "void *arg" 90.Fn TIMEOUT_INITIALIZER_FLAGS "void (*fn)(void *)" "void *arg" "int flags" 91.Sh DESCRIPTION 92The 93.Nm timeout 94API provides a mechanism to execute a function at a given time. 95The granularity of the time is limited by the granularity of the 96.Xr hardclock 9 97timer which executes 98.Xr hz 9 99times a second. 100.Pp 101It is the responsibility of the caller to provide these functions with 102pre-allocated timeout structures. 103.Pp 104The 105.Fn timeout_set 106function prepares the timeout structure 107.Fa to 108to be used in future calls to 109.Fn timeout_add 110and 111.Fn timeout_del . 112The timeout will be prepared to call the function specified by the 113.Fa fn 114argument with a 115.Fa void * 116argument given in the 117.Fa arg 118argument. 119Once initialized, the 120.Fa to 121structure can be used repeatedly in 122.Fn timeout_add 123and 124.Fn timeout_del 125and does not need to be reinitialized unless 126the function called and/or its argument must change. 127.Pp 128The 129.Fn timeout_set_flags 130function is similar to 131.Fn timeout_set 132but it additionally accepts the bitwise OR of zero or more of the 133following 134.Fa flags : 135.Bl -tag -width TIMEOUT_PROC -offset indent 136.It Dv TIMEOUT_PROC 137Runs the timeout in a process context instead of the default 138.Dv IPL_SOFTCLOCK 139interrupt context. 140.El 141.Pp 142The function 143.Fn timeout_add 144schedules the execution of the 145.Fa to 146timeout in at least 147.Fa ticks Ns /hz 148seconds. 149Negative values of 150.Fa ticks 151are illegal. 152If the value is 153.Sq 0 154it will, in the current implementation, be treated as 155.Sq 1 , 156but in the future it might cause an immediate timeout. 157The timeout in the 158.Fa to 159argument must be already initialized by 160.Fn timeout_set 161or 162.Fn timeout_set_flags 163and may not be used in calls to 164.Fn timeout_set 165or 166.Fn timeout_set_flags 167until it has timed out or been removed with 168.Fn timeout_del . 169If the timeout in the 170.Fa to 171argument is already scheduled, the old execution time will be 172replaced by the new one. 173.Pp 174The function 175.Fn timeout_del 176will cancel the timeout in the argument 177.Fa to . 178If the timeout has already executed or has never been added 179the call will have no effect. 180.Pp 181.Fn timeout_del_barrier 182is like 183.Fn timeout_del 184but it will wait until any current execution of the timeout has completed. 185.Pp 186.Fn timeout_barrier 187ensures that any current execution of the timeout in the argument 188.Fa to 189has completed before returning. 190If the timeout 191.Fa to 192has been initialised with 193.Fn timeout_set 194it will take the kernel lock. 195.Pp 196The 197.Fn timeout_pending 198macro can be used to check if a timeout is scheduled to run. 199.Pp 200The 201.Fn timeout_initialized 202macro can be used to check if a timeout has been initialized. 203.Pp 204The 205.Fn timeout_triggered 206macro can be used to check if a timeout is running or has been run. 207The 208.Fn timeout_add 209and 210.Fn timeout_del 211functions clear the triggered state for that timeout. 212.Pp 213When possible, use the 214.Fn timeout_add_tv , 215.Fn timeout_add_ts , 216.Fn timeout_add_bt , 217.Fn timeout_add_sec , 218.Fn timeout_add_msec , 219.Fn timeout_add_usec , 220and 221.Fn timeout_add_nsec 222functions instead of 223.Fn timeout_add . 224Those functions add a timeout whilst converting the time specified 225by the respective types. 226They also defer the timeout handler for at least one tick if called 227with a positive value. 228.Pp 229A timeout declaration can be initialised with the 230.Fn TIMEOUT_INITIALIZER 231macro. 232The timeout will be prepared to call the function specified by the 233.Fa fn 234argument with the 235.Fa void * 236argument given in 237.Fa arg . 238.Pp 239The 240.Fn TIMEOUT_INITIALIZER_FLAGS 241macro is similar to 242.Fn TIMEOUT_INITIALIZER , 243but it accepts additional flags. 244See the 245.Fn timeout_set_flags 246function for details. 247.Sh CONTEXT 248.Fn timeout_set 249and 250.Fn timeout_set_flags 251can be called during autoconf, from process context, or from interrupt 252context. 253.Pp 254.Fn timeout_add , 255.Fn timeout_add_sec , 256.Fn timeout_add_msec , 257.Fn timeout_add_nsec , 258.Fn timeout_add_usec , 259.Fn timeout_add_tv , 260.Fn timeout_add_ts , 261.Fn timeout_add_bt , 262.Fn timeout_del , 263.Fn timeout_pending , 264.Fn timeout_initialized , 265.Fn timeout_triggered 266can be called during autoconf, from process context, or from any 267interrupt context at or below 268.Dv IPL_CLOCK . 269.Pp 270.Fn timeout_barrier 271and 272.Fn timeout_del_barrier 273can be called from process context. 274.Pp 275When the timeout runs, the 276.Fa fn 277argument to 278.Fn timeout_set 279or 280.Fn timeout_set_flags 281will be called in an interrupt context at 282.Dv IPL_SOFTCLOCK 283or a process context if the 284.Dv TIMEOUT_PROC 285flag was given at initialization. 286.Sh RETURN VALUES 287.Fn timeout_add , 288.Fn timeout_add_sec , 289.Fn timeout_add_msec , 290.Fn timeout_add_nsec , 291.Fn timeout_add_usec , 292.Fn timeout_add_tv , 293.Fn timeout_add_ts , 294and 295.Fn timeout_add_bt 296will return 1 if the timeout 297.Fa to 298was added to the timeout schedule or 0 if it was already queued. 299.Pp 300.Fn timeout_del 301and 302.Fn timeout_del_barrier 303will return 1 if the timeout 304.Fa to 305was removed from the pending timeout schedule or 0 if it was not 306currently queued. 307.Sh CODE REFERENCES 308These functions are implemented in the file 309.Pa sys/kern/kern_timeout.c . 310.Sh SEE ALSO 311.Xr hz 9 , 312.Xr splclock 9 , 313.Xr tsleep 9 , 314.Xr tvtohz 9 315.Rs 316.%A George Varghese 317.%A Anthony Lauck 318.%B Hashed and hierarchical timing wheels: efficient data structures for \ 319implementing a timer facility 320.%O especially Schemes 6 and 7 321.%I IEEE/ACM 322.%J Transactions on Networking 323.%V vol. 5 324.%N no. 6 325.%P pp. 824\(en834 326.%D December 1997 327.Re 328