1.\" $OpenBSD: timeout.9,v 1.53 2021/05/11 13:29:25 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: May 11 2021 $ 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 199.Fn timeout_pending 200macro can be used to check if a timeout is scheduled to run. 201.Pp 202The 203.Fn timeout_initialized 204macro can be used to check if a timeout has been initialized. 205.Pp 206The 207.Fn timeout_triggered 208macro can be used to check if a timeout is running or has been run. 209The 210.Fn timeout_add 211and 212.Fn timeout_del 213functions clear the triggered state for that timeout. 214.Pp 215When possible, use the 216.Fn timeout_add_tv , 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 , 249.Fn timeout_set_flags , 250and 251.Fn timeout_set_proc 252can be called during autoconf, from process context, or from interrupt 253context. 254.Pp 255.Fn timeout_add , 256.Fn timeout_add_sec , 257.Fn timeout_add_msec , 258.Fn timeout_add_nsec , 259.Fn timeout_add_usec , 260.Fn timeout_add_tv , 261.Fn timeout_del , 262.Fn timeout_pending , 263.Fn timeout_initialized , 264.Fn timeout_triggered 265can be called during autoconf, from process context, or from any 266interrupt context at or below 267.Dv IPL_CLOCK . 268.Pp 269.Fn timeout_barrier 270and 271.Fn timeout_del_barrier 272can be called from process context. 273.Pp 274When the timeout runs, the 275.Fa fn 276argument to 277.Fn timeout_set 278or 279.Fn timeout_set_flags 280will be called in an interrupt context at 281.Dv IPL_SOFTCLOCK 282or a process context if the 283.Dv TIMEOUT_PROC 284flag was given at initialization. 285The 286.Fa fn 287argument to 288.Fn timeout_set_proc 289will be called in a process context. 290.Sh RETURN VALUES 291.Fn timeout_add , 292.Fn timeout_add_sec , 293.Fn timeout_add_msec , 294.Fn timeout_add_nsec , 295.Fn timeout_add_usec , 296and 297.Fn timeout_add_tv 298will return 1 if the timeout 299.Fa to 300was added to the timeout schedule or 0 if it was already queued. 301.Pp 302.Fn timeout_del 303and 304.Fn timeout_del_barrier 305will return 1 if the timeout 306.Fa to 307was removed from the pending timeout schedule or 0 if it was not 308currently queued. 309.Sh CODE REFERENCES 310These functions are implemented in the file 311.Pa sys/kern/kern_timeout.c . 312.Sh SEE ALSO 313.Xr hz 9 , 314.Xr splclock 9 , 315.Xr tsleep 9 , 316.Xr tvtohz 9 317.Rs 318.%A George Varghese 319.%A Anthony Lauck 320.%B Hashed and hierarchical timing wheels: efficient data structures for \ 321implementing a timer facility 322.%O especially Schemes 6 and 7 323.%I IEEE/ACM 324.%J Transactions on Networking 325.%V vol. 5 326.%N no. 6 327.%P pp. 824\(en834 328.%D December 1997 329.Re 330