1.\" $NetBSD: callout.9,v 1.18 2007/12/29 09:41:10 wiz 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 December 29, 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. 105If the 106.Fa flags 107argument is 108.Dv CALLOUT_MPSAFE , 109the handler will be called without getting the global kernel lock. 110In this case it should only use functions that are multiprocessor 111safe. 112.Pp 113.Fn callout_destroy 114destroys the callout, preventing further use. 115It is provided as a diagnostic facility intended to catch bugs. 116To ensure future compatibility, 117.Fn callout_destroy 118should always be called when the callout is no longer required (for instance, 119when a device is being detached). 120.Pp 121The 122.Fn callout_reset 123function resets and starts the timer associated with the callout handle 124.Fa c . 125When the timer expires after 126.Fa ticks Ns No /hz 127seconds, the function specified by 128.Fa func 129will be called with the argument 130.Fa arg . 131If the timer associated with the callout handle is already running, 132the callout will simply be rescheduled to execute at the newly specified 133time. 134Once the timer is started, the callout handle is marked as 135.Em PENDING . 136Once the timer expires, 137the handle is marked as 138.Em EXPIRED 139and 140.Em INVOKING , 141and the 142.Em PENDING 143status is cleared. 144.Pp 145The 146.Fn callout_setfunc 147function sets the function and argument of the callout handle 148.Fa c 149to 150.Fa func 151and 152.Fa arg 153respectively. 154The callout handle must already be initialized. 155If a callout will always be used with the same function and argument, 156then 157.Fn callout_setfunc 158used in conjunction with 159.Fn callout_schedule 160is slightly more efficient than using 161.Fn callout_reset . 162.Pp 163The 164.Fn callout_stop 165function stops the timer associated the callout handle 166.Fa c . 167The 168.Em PENDING 169and 170.Em EXPIRED 171status for the callout handle is cleared. 172It is safe to call 173.Fn callout_stop 174on a callout handle that is not pending, so long as it is initialized. 175. Fn callout_stop 176will return a non-zero value if the callout was 177.Em EXPIRED . 178.Pp 179The 180.Fn callout_pending 181function tests the 182.Em PENDING 183status of the callout handle 184.Fa c . 185A 186.Em PENDING 187callout is one that has been started and whose function has not yet 188been called. 189Note that it is possible for a callout's timer to have expired without 190its function being called if interrupt level has not dropped low enough 191to let softclock interrupts through. 192Note that it is only safe to test 193.Em PENDING 194status when at softclock interrupt level or higher. 195.Pp 196The 197.Fn callout_expired 198function tests to see if the callout's timer has expired and its 199function called. 200.Pp 201The 202.Fn callout_active 203function returns true if a timer has been started but not explicitly stopped, 204even if it has already fired. 205.Fn callout_active foo 206is logically the same as 207.Fn callout_pending foo 208|| 209.Fn callout_expired foo ; 210it is implemented as a separate function for compatibility with 211.Fx 212and for the special case of 213.Fn TCP_TIMER_ISARMED . 214Its use is not recommended. 215.Pp 216The 217.Fn callout_invoking 218function tests the 219.Em INVOKING 220status of the callout handle 221.Fa c . 222This flag is set just before a callout's function is being called. 223Since the priority level is lowered prior to invocation of the 224callout function, other pending higher-priority code may run before 225the callout function is allowed to run. 226This may create a race condition if this higher-priority code 227deallocates storage containing one or more callout structures whose 228callout functions are about to be run. 229In such cases, one technique to prevent references to deallocated 230storage would be to test whether any callout functions are in the 231.Em INVOKING 232state using 233.Fn callout_invoking , 234and if so, to mark the data structure and defer storage 235deallocation until the callout function is allowed to run. 236For this handshake protocol to work, the callout function will 237have to use the 238.Fn callout_ack 239function to clear this flag. 240.Pp 241The 242.Fn callout_ack 243function clears the 244.Em INVOKING 245state in the callout handle 246.Fa c . 247This is used in situations where it is necessary to protect against 248the race condition described under 249.Fn callout_invoking . 250.Sh SEE ALSO 251.Xr hz 9 252.Sh HISTORY 253The 254.Nm callout 255facility was implemented by Artur Grabowski and Thomas Nordin, based 256on the work of G. Varghese and A. Lauck, described in the paper 257Hashed and Hierarchical Timing Wheels: Data Structures for the 258Efficient Implementation of a Timer Facility 259in the Proceedings of the 11th ACM Annual Symposium on Operating System 260Principles, Austin, Texas, November 1987. 261It was adapted to the 262.Nx 263kernel by Jason R. Thorpe. 264