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