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