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