1.\" $NetBSD: callout.9,v 1.17 2007/10/16 09:17:44 joerg Exp $ 2.\" 3.\" Copyright (c) 2000, 2003 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jason R. Thorpe. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd October 16, 2007 38.Dt CALLOUT 9 39.Os 40.Sh NAME 41.Nm callout_init , 42.Nm callout_destroy , 43.Nm callout_reset , 44.Nm callout_schedule , 45.Nm callout_setfunc , 46.Nm callout_stop , 47.Nm callout_expired , 48.Nm callout_invoking , 49.Nm callout_ack 50.Nd execute a function after a specified length of time 51.Sh SYNOPSIS 52.In sys/callout.h 53.Ft void 54.Fn "callout_init" "callout_t *c" "u_int flags" 55.Ft void 56.Fn "callout_destroy" "callout_t *c" 57.Ft void 58.Fn "callout_reset" "callout_t *c" "int ticks" \ 59 "void (*func)(void *)" "void *arg" 60.Ft void 61.Fn "callout_schedule" "callout_t *c" "int ticks" 62.Ft void 63.Fn "callout_setfunc" "callout_t *c" "void (*func)(void *)" "void *arg" 64.Ft bool 65.Fn "callout_stop" "callout_t *c" 66.Ft bool 67.Fn "callout_pending" "callout_t *c" 68.Ft bool 69.Fn "callout_expired" "callout_t *c" 70.Ft bool 71.Fn "callout_active" "callout_t *c" 72.Ft bool 73.Fn "callout_invoking" "callout_t *c" 74.Ft bool 75.Fn "callout_ack" "callout_t *c" 76.Sh DESCRIPTION 77The 78.Nm callout 79facility provides a mechanism to execute a function at a given time. 80The timer is based on the hardclock timer which ticks 81.Dv hz 82times per second. 83The function is called at softclock interrupt level. 84.Pp 85Clients of the 86.Nm callout 87facility are responsible for providing pre-allocated 88callout structures, or 89.Dq handles . 90The 91.Nm callout 92facility replaces the historic 93.Ux 94functions 95.Fn timeout 96and 97.Fn untimeout . 98.Pp 99The 100.Fn callout_init 101function initializes the callout handle 102.Fa c 103for use. 104No operations can be performed on the callout before it is initialized. 105Currently, the 106.Fa flags 107argument must be specified as zero (0). 108.Pp 109.Fn callout_destroy 110destroys the callout, preventing further use. 111It is provided as a diagnostic facility intended to catch bugs. 112To ensure future compatibility, 113.Fn callout_destroy 114should always be called when the callout is no longer required (for instance, 115when a device is being detached). 116.Pp 117The 118.Fn callout_reset 119function resets and starts the timer associated with the callout handle 120.Fa c . 121When the timer expires after 122.Fa ticks Ns No /hz 123seconds, the function specified by 124.Fa func 125will be called with the argument 126.Fa arg . 127If the timer associated with the callout handle is already running, 128the callout will simply be rescheduled to execute at the newly specified 129time. 130Once the timer is started, the callout handle is marked as 131.Em PENDING . 132Once the timer expires, 133the handle is marked as 134.Em EXPIRED 135and 136.Em INVOKING , 137and the 138.Em PENDING 139status is cleared. 140.Pp 141The 142.Fn callout_setfunc 143function sets the function and argument of the callout handle 144.Fa c 145to 146.Fa func 147and 148.Fa arg 149respectively. 150The callout handle must already be initialized. 151If a callout will always be used with the same function and argument, 152then 153.Fn callout_setfunc 154used in conjunction with 155.Fn callout_schedule 156is slightly more efficient than using 157.Fn callout_reset . 158.Pp 159The 160.Fn callout_stop 161function stops the timer associated the callout handle 162.Fa c . 163The 164.Em PENDING 165and 166.Em EXPIRED 167status for the callout handle is cleared. 168It is safe to call 169.Fn callout_stop 170on a callout handle that is not pending, so long as it is initialized. 171. Fn callout_stop 172will return a non-zero value if the callout was 173.Em EXPIRED . 174.Pp 175The 176.Fn callout_pending 177function tests the 178.Em PENDING 179status of the callout handle 180.Fa c . 181A 182.Em PENDING 183callout is one that has been started and whose function has not yet 184been called. 185Note that it is possible for a callout's timer to have expired without 186its function being called if interrupt level has not dropped low enough 187to let softclock interrupts through. 188Note that it is only safe to test 189.Em PENDING 190status when at softclock interrupt level or higher. 191.Pp 192The 193.Fn callout_expired 194function tests to see if the callout's timer has expired and its 195function called. 196.Pp 197The 198.Fn callout_active 199function returns true if a timer has been started but not explicitly stopped, 200even if it has already fired. 201.Fn callout_active foo 202is logically the same as 203.Fn callout_pending foo 204|| 205.Fn callout_expired foo ; 206it is implemented as a separate function for compatibility with 207.Fx 208and for the special case of 209.Fn TCP_TIMER_ISARMED . 210Its use is not recommended. 211.Pp 212The 213.Fn callout_invoking 214function tests the 215.Em INVOKING 216status of the callout handle 217.Fa c . 218This flag is set just before a callout's function is being called. 219Since the priority level is lowered prior to invocation of the 220callout function, other pending higher-priority code may run before 221the callout function is allowed to run. 222This may create a race condition if this higher-priority code 223deallocates storage containing one or more callout structures whose 224callout functions are about to be run. 225In such cases, one technique to prevent references to deallocated 226storage would be to test whether any callout functions are in the 227.Em INVOKING 228state using 229.Fn callout_invoking , 230and if so, to mark the data structure and defer storage 231deallocation until the callout function is allowed to run. 232For this handshake protocol to work, the callout function will 233have to use the 234.Fn callout_ack 235function to clear this flag. 236.Pp 237The 238.Fn callout_ack 239function clears the 240.Em INVOKING 241state in the callout handle 242.Fa c . 243This is used in situations where it is necessary to protect against 244the race condition described under 245.Fn callout_invoking . 246.Sh SEE ALSO 247.Xr hz 9 248.Sh HISTORY 249The 250.Nm callout 251facility was implemented by Artur Grabowski and Thomas Nordin, based 252on the work of G. Varghese and A. Lauck, described in the paper 253Hashed and Hierarchical Timing Wheels: Data Structures for the 254Efficient Implementation of a Timer Facility 255in the Proceedings of the 11th ACM Annual Symposium on Operating System 256Principles, Austin, Texas, November 1987. 257It was adapted to the 258.Nx 259kernel by Jason R. Thorpe. 260