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