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