1.\" $OpenBSD: timeout.9,v 1.43 2016/06/14 15:58:03 bluhm 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: June 14 2016 $ 27.Dt TIMEOUT_SET 9 28.Os 29.Sh NAME 30.Nm timeout_set , 31.Nm timeout_add , 32.Nm timeout_add_sec , 33.Nm timeout_add_msec , 34.Nm timeout_add_nsec , 35.Nm timeout_add_usec , 36.Nm timeout_add_tv , 37.Nm timeout_add_ts , 38.Nm timeout_add_bt , 39.Nm timeout_del , 40.Nm timeout_pending , 41.Nm timeout_initialized , 42.Nm timeout_triggered , 43.Nm TIMEOUT_INITIALIZER 44.Nd execute a function after a specified period of time 45.Sh SYNOPSIS 46.In sys/types.h 47.In sys/timeout.h 48.Ft void 49.Fn timeout_set "struct timeout *to" "void (*fn)(void *)" "void *arg" 50.Ft int 51.Fn timeout_add "struct timeout *to" "int ticks" 52.Ft int 53.Fn timeout_del "struct timeout *to" 54.Ft int 55.Fn timeout_pending "struct timeout *to" 56.Ft int 57.Fn timeout_initialized "struct timeout *to" 58.Ft int 59.Fn timeout_triggered "struct timeout *to" 60.Ft int 61.Fn timeout_add_tv "struct timeout *to" "struct timeval *" 62.Ft int 63.Fn timeout_add_ts "struct timeout *to" "struct timespec *" 64.Ft int 65.Fn timeout_add_bt "struct timeout *to" "struct bintime *" 66.Ft int 67.Fn timeout_add_sec "struct timeout *to" "int sec" 68.Ft int 69.Fn timeout_add_msec "struct timeout *to" "int msec" 70.Ft int 71.Fn timeout_add_usec "struct timeout *to" "int usec" 72.Ft int 73.Fn timeout_add_nsec "struct timeout *to" "int nsec" 74.Fn TIMEOUT_INITIALIZER "void (*fn)(void *)" "void *arg" 75.Sh DESCRIPTION 76The 77.Nm timeout 78API provides a mechanism to execute a function at a given time. 79The granularity of the time is limited by the granularity of the 80.Xr hardclock 9 81timer which executes 82.Xr hz 9 83times a second. 84.Pp 85It is the responsibility of the caller to provide these functions with 86pre-allocated timeout structures. 87.Pp 88The function 89.Fn timeout_set 90prepares the timeout structure 91.Fa to 92to be used in future calls to 93.Fn timeout_add 94and 95.Fn timeout_del . 96The timeout will be prepared to call the function specified by the 97.Fa fn 98argument with a 99.Fa void * 100argument given in the 101.Fa arg 102argument. 103Once initialized, the 104.Fa to 105structure can be used repeatedly in 106.Fn timeout_add 107and 108.Fn timeout_del 109and does not need to be reinitialized unless 110the function called and/or its argument must change. 111.Pp 112The function 113.Fn timeout_add 114schedules the execution of the 115.Fa to 116timeout in at least 117.Fa ticks Ns /hz 118seconds. 119Negative values of 120.Fa ticks 121are illegal. 122If the value is 123.Sq 0 124it will, in the current implementation, be treated as 125.Sq 1 , 126but in the future it might cause an immediate timeout. 127The timeout in the 128.Fa to 129argument must be already initialized by 130.Fn timeout_set 131and may not be used in calls to 132.Fn timeout_set 133until it has timed out or been removed with 134.Fn timeout_del . 135If the timeout in the 136.Fa to 137argument is already scheduled, the old execution time will be 138replaced by the new one. 139.Pp 140The function 141.Fn timeout_del 142will cancel the timeout in the argument 143.Fa to . 144If the timeout has already executed or has never been added 145the call will have no effect. 146.Pp 147The 148.Fn timeout_pending 149macro can be used to check if a timeout is scheduled to run. 150.Pp 151The 152.Fn timeout_initialized 153macro can be used to check if a timeout has been initialized. 154.Pp 155The 156.Fn timeout_triggered 157macro can be used to check if a timeout is running or has been run. 158The 159.Fn timeout_add 160and 161.Fn timeout_del 162functions clear the triggered state for that timeout. 163.Pp 164When possible, use the 165.Fn timeout_add_tv , 166.Fn timeout_add_ts , 167.Fn timeout_add_bt , 168.Fn timeout_add_sec , 169.Fn timeout_add_msec , 170.Fn timeout_add_usec , 171and 172.Fn timeout_add_nsec 173functions instead of 174.Fn timeout_add . 175Those functions add a timeout whilst converting the time specified 176by the respective types. 177They also defer the timeout handler for at least one tick if called 178with a positive value. 179.Pp 180A timeout declaration can be initialised with the 181.Fn TIMEOUT_INITIALIZER 182macro. 183The timeout will be prepared to call the function specified by the 184.Fa fn 185argument with the 186.Fa void * 187argument given in 188.Fa arg . 189.Sh CONTEXT 190.Fn timeout_set 191can be called during autoconf, from process context, or from interrupt 192context. 193.Pp 194.Fn timeout_add , 195.Fn timeout_add_sec , 196.Fn timeout_add_msec , 197.Fn timeout_add_nsec , 198.Fn timeout_add_usec , 199.Fn timeout_add_tv , 200.Fn timeout_add_ts , 201.Fn timeout_add_bt , 202.Fn timeout_del , 203.Fn timeout_pending , 204.Fn timeout_initialized , 205.Fn timeout_triggered 206can be called during autoconf, from process context, or from any 207interrupt context at or below 208.Dv IPL_CLOCK . 209.Pp 210When the timeout runs, the 211.Fa fn 212argument to 213.Fn timeout_set 214will be called in an interrupt context at 215.Dv IPL_SOFTCLOCK . 216.Sh RETURN VALUES 217.Fn timeout_add , 218.Fn timeout_add_sec , 219.Fn timeout_add_msec , 220.Fn timeout_add_nsec , 221.Fn timeout_add_usec , 222.Fn timeout_add_tv , 223.Fn timeout_add_ts , 224and 225.Fn timeout_add_bt 226will return 1 if the timeout 227.Fa to 228was added to the timeout schedule or 0 if it was already queued. 229.Pp 230.Fn timeout_del 231will return 1 if the timeout 232.Fa to 233was removed from the pending timeout schedule or 0 if it was not 234currently queued. 235.Sh CODE REFERENCES 236These functions are implemented in the file 237.Pa sys/kern/kern_timeout.c . 238.Sh SEE ALSO 239.Xr hz 9 , 240.Xr splclock 9 , 241.Xr tsleep 9 , 242.Xr tvtohz 9 243