1.\" $NetBSD: callout.9,v 1.14 2005/03/04 05:53:19 mycroft 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 March 4, 2005 38.Dt CALLOUT 9 39.Os 40.Sh NAME 41.Nm callout_init , 42.Nm callout_reset , 43.Nm callout_schedule , 44.Nm callout_setfunc , 45.Nm callout_stop , 46.Nm callout_expired , 47.Nm callout_invoking , 48.Nm callout_ack , 49.Nm CALLOUT_INITIALIZER , 50.Nm CALLOUT_INITIALIZER_SETFUNC 51.Nd execute a function after a specified length of time 52.Sh SYNOPSIS 53.In sys/callout.h 54.Ft void 55.Fn "callout_init" "struct callout *c" 56.Ft void 57.Fn "callout_reset" "struct callout *c" "int ticks" \ 58 "void (*func)(void *)" "void *arg" 59.Ft void 60.Fn "callout_schedule" "struct callout *c" "int ticks" 61.Ft void 62.Fn "callout_setfunc" "struct callout *c" "void (*func)(void *)" "void *arg" 63.Ft void 64.Fn "callout_stop" "struct callout *c" 65.Ft int 66.Fn "callout_pending" "struct callout *c" 67.Ft int 68.Fn "callout_expired" "struct callout *c" 69.Ft int 70.Fn "callout_active" "struct callout *c" 71.Ft int 72.Fn "callout_invoking" "struct callout *c" 73.Ft void 74.Fn "callout_ack" "struct callout *c" 75.Fd CALLOUT_INITIALIZER 76.Pp 77.Fn CALLOUT_INITIALIZER_SETFUNC "func" "arg" 78.Sh DESCRIPTION 79The 80.Nm callout 81facility provides a mechanism to execute a function at a given time. 82The timer is based on the hardclock timer which ticks 83.Dv hz 84times per second. 85The function is called at softclock interrupt level. 86.Pp 87Clients of the 88.Nm callout 89facility are responsible for providing pre-allocated 90callout structures, or 91.Dq handles . 92The 93.Nm callout 94facility replaces the historic 95.Bx 96functions 97.Fn timeout 98and 99.Fn untimeout . 100.Pp 101The 102.Fn callout_init 103function initializes the callout handle 104.Fa c 105for use. 106If it is inconvenient to call 107.Fn callout_init , 108statically-allocated callout handles may be initialized by assigning 109the value 110.Dv CALLOUT_INITIALIZER 111to them. 112.Pp 113The 114.Fn callout_reset 115function resets and starts the timer associated with the callout handle 116.Fa c . 117When the timer expires after 118.Fa ticks Ns No /hz 119seconds, the function specified by 120.Fa func 121will be called with the argument 122.Fa arg . 123If the timer associated with the callout handle is already running, 124the callout will simply be rescheduled to execute at the newly specified 125time. 126Once the timer is started, the callout handle is marked as 127.Em PENDING . 128Once the timer expires, 129the handle is marked as 130.Em EXPIRED 131and 132.Em INVOKING , 133and the 134.Em PENDING 135status is cleared. 136.Pp 137The 138.Fn callout_setfunc 139function sets the function and argument of the callout handle 140.Fa c 141to 142.Fa func 143and 144.Fa arg 145respectively. 146The callout handle must already be initialized. 147If a callout will always be used with the same function and argument, 148then 149.Fn callout_setfunc 150used in conjunction with 151.Fn callout_schedule 152is slightly more efficient than using 153.Fn callout_reset . 154If it is inconvenient to call 155.Fn callout_setfunc , 156statically-allocated callout handles may be initialized by assigning 157the value 158.Dv CALLOUT_INITIALIZER_SETFUNC 159to them, passing the function and argument to the initializer. 160.Pp 161The 162.Fn callout_stop 163function stops the timer associated the callout handle 164.Fa c . 165The 166.Em PENDING 167and 168.Em EXPIRED 169status for the callout handle is cleared. 170It is safe to call 171.Fn callout_stop 172on a callout handle that is not pending, so long as it is initialized. 173.Pp 174The 175.Fn callout_pending 176function tests the 177.Em PENDING 178status of the callout handle 179.Fa c . 180A 181.Em PENDING 182callout is one that has been started and whose function has not yet 183been called. 184Note that it is possible for a callout's timer to have expired without 185its function being called if interrupt level has not dropped low enough 186to let softclock interrupts through. 187Note that it is only safe to test 188.Em PENDING 189status when at softclock interrupt level or higher. 190.Pp 191The 192.Fn callout_expired 193function tests to see if the callout's timer has expired and its 194function called. 195.Pp 196The 197.Fn callout_active 198function returns true if a timer has been started but not explicitly stopped, 199even if it has already fired. 200.Fn callout_active foo 201is logically the same as 202.Fn callout_pending foo 203|| 204.Fn callout_expired foo ; 205it is implemented as a separate function for compatibility with 206.Fx 207and for the special case of 208.Fn TCP_TIMER_ISARMED . 209Its use is not recommended. 210.Pp 211The 212.Fn callout_invoking 213function tests the 214.Em INVOKING 215status of the callout handle 216.Fa c . 217This flag is set just before a callout's function is being called. 218Since the priority level is lowered prior to invocation of the 219callout function, other pending higher-priority code may run before 220the callout function is allowed to run. 221This may create a race condition if this higher-priority code 222deallocates storage containing one or more callout structures whose 223callout functions are about to be run. 224In such cases, one technique to prevent references to deallocated 225storage would be to test whether any callout functions are in the 226.Em INVOKING 227state using 228.Fn callout_invoking , 229and if so, to mark the data structure and defer storage 230deallocation until the callout function is allowed to run. 231For this handshake protocol to work, the callout function will 232have to use the 233.Fn callout_ack 234function to clear this flag. 235.Pp 236The 237.Fn callout_ack 238function clears the 239.Em INVOKING 240state in the callout handle 241.Fa c . 242This is used in situations where it is necessary to protect against 243the race condition described under 244.Fn callout_invoking . 245.Sh SEE ALSO 246.Xr hz 9 247.Sh HISTORY 248The 249.Nm callout 250facility was implemented by Artur Grabowski and Thomas Nordin, based 251on the work of G. Varghese and A. Lauck, described in the paper 252Hashed and Hierarchical Timing Wheels: Data Structures for the 253Efficient Implementation of a Timer Facility 254in the Proceedings of the 11th ACM Annual Symposium on Operating System 255Principles, Austin, Texas, November 1987. 256It was adapted to the 257.Nx 258kernel by Jason R. Thorpe. 259