1.\" $OpenBSD: timeout.9,v 1.52 2021/04/26 20:32:30 mvs 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: April 26 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. 197If the timeout 198.Fa to 199has been initialised with 200.Fn timeout_set 201it will take the kernel lock. 202.Pp 203The 204.Fn timeout_pending 205macro can be used to check if a timeout is scheduled to run. 206.Pp 207The 208.Fn timeout_initialized 209macro can be used to check if a timeout has been initialized. 210.Pp 211The 212.Fn timeout_triggered 213macro can be used to check if a timeout is running or has been run. 214The 215.Fn timeout_add 216and 217.Fn timeout_del 218functions clear the triggered state for that timeout. 219.Pp 220When possible, use the 221.Fn timeout_add_tv , 222.Fn timeout_add_sec , 223.Fn timeout_add_msec , 224.Fn timeout_add_usec , 225and 226.Fn timeout_add_nsec 227functions instead of 228.Fn timeout_add . 229Those functions add a timeout whilst converting the time specified 230by the respective types. 231They also defer the timeout handler for at least one tick if called 232with a positive value. 233.Pp 234A timeout declaration can be initialised with the 235.Fn TIMEOUT_INITIALIZER 236macro. 237The timeout will be prepared to call the function specified by the 238.Fa fn 239argument with the 240.Fa void * 241argument given in 242.Fa arg . 243.Pp 244The 245.Fn TIMEOUT_INITIALIZER_FLAGS 246macro is similar to 247.Fn TIMEOUT_INITIALIZER , 248but it accepts additional flags. 249See the 250.Fn timeout_set_flags 251function for details. 252.Sh CONTEXT 253.Fn timeout_set , 254.Fn timeout_set_flags , 255and 256.Fn timeout_set_proc 257can be called during autoconf, from process context, or from interrupt 258context. 259.Pp 260.Fn timeout_add , 261.Fn timeout_add_sec , 262.Fn timeout_add_msec , 263.Fn timeout_add_nsec , 264.Fn timeout_add_usec , 265.Fn timeout_add_tv , 266.Fn timeout_del , 267.Fn timeout_pending , 268.Fn timeout_initialized , 269.Fn timeout_triggered 270can be called during autoconf, from process context, or from any 271interrupt context at or below 272.Dv IPL_CLOCK . 273.Pp 274.Fn timeout_barrier 275and 276.Fn timeout_del_barrier 277can be called from process context. 278.Pp 279When the timeout runs, the 280.Fa fn 281argument to 282.Fn timeout_set 283or 284.Fn timeout_set_flags 285will be called in an interrupt context at 286.Dv IPL_SOFTCLOCK 287or a process context if the 288.Dv TIMEOUT_PROC 289flag was given at initialization. 290The 291.Fa fn 292argument to 293.Fn timeout_set_proc 294will be called in a process context. 295.Sh RETURN VALUES 296.Fn timeout_add , 297.Fn timeout_add_sec , 298.Fn timeout_add_msec , 299.Fn timeout_add_nsec , 300.Fn timeout_add_usec , 301and 302.Fn timeout_add_tv 303will return 1 if the timeout 304.Fa to 305was added to the timeout schedule or 0 if it was already queued. 306.Pp 307.Fn timeout_del 308and 309.Fn timeout_del_barrier 310will return 1 if the timeout 311.Fa to 312was removed from the pending timeout schedule or 0 if it was not 313currently queued. 314.Sh CODE REFERENCES 315These functions are implemented in the file 316.Pa sys/kern/kern_timeout.c . 317.Sh SEE ALSO 318.Xr hz 9 , 319.Xr splclock 9 , 320.Xr tsleep 9 , 321.Xr tvtohz 9 322.Rs 323.%A George Varghese 324.%A Anthony Lauck 325.%B Hashed and hierarchical timing wheels: efficient data structures for \ 326implementing a timer facility 327.%O especially Schemes 6 and 7 328.%I IEEE/ACM 329.%J Transactions on Networking 330.%V vol. 5 331.%N no. 6 332.%P pp. 824\(en834 333.%D December 1997 334.Re 335