1.\" $NetBSD: callout.9,v 1.13 2003/10/27 16:52:01 thorpej 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 26, 2003 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_invoking" "struct callout *c" 71.Ft void 72.Fn "callout_ack" "struct callout *c" 73.Fd CALLOUT_INITIALIZER 74.Pp 75.Fn CALLOUT_INITIALIZER_SETFUNC "func" "arg" 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.Bx 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. 104If it is inconvenient to call 105.Fn callout_init , 106statically-allocated callout handles may be initialized by assigning 107the value 108.Dv CALLOUT_INITIALIZER 109to them. 110.Pp 111The 112.Fn callout_reset 113function resets and starts the timer associated with the callout handle 114.Fa c . 115When the timer expires after 116.Fa ticks Ns No /hz 117seconds, the function specified by 118.Fa func 119will be called with the argument 120.Fa arg . 121If the timer associated with the callout handle is already running, 122the callout will simply be rescheduled to execute at the newly specified 123time. 124Once the timer is started, the callout handle is marked as 125.Em PENDING . 126Once the timer expires, 127the handle is marked as 128.Em EXPIRED 129and 130.Em INVOKING , 131and the 132.Em PENDING 133status is cleared. 134.Pp 135The 136.Fn callout_setfunc 137function sets the function and argument of the callout handle 138.Fa c 139to 140.Fa func 141and 142.Fa arg 143respectively. 144The callout handle must already be initialized. 145If a callout will always be used with the same function and argument, 146then 147.Fn callout_setfunc 148used in conjunction with 149.Fn callout_schedule 150is slightly more efficient than using 151.Fn callout_reset . 152If it is inconvenient to call 153.Fn callout_setfunc , 154statically-allocated callout handles may be initialized by assigning 155the value 156.Dv CALLOUT_INITIALIZER_SETFUNC 157to them, passing the function and argument to the initializer. 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.Pp 172The 173.Fn callout_pending 174function tests the 175.Em PENDING 176status of the callout handle 177.Fa c . 178A 179.Em PENDING 180callout is one that has been started and whose function has not yet 181been called. 182Note that it is possible for a callout's timer to have expired without 183its function being called if interrupt level has not dropped low enough 184to let softclock interrupts through. 185Note that it is only safe to test 186.Em PENDING 187status when at softclock interrupt level or higher. 188.Pp 189The 190.Fn callout_expired 191function tests to see if the callout's timer has expired and its 192function called. 193.Pp 194The 195.Fn callout_invoking 196function tests the 197.Em INVOKING 198status of the callout handle 199.Fa c . 200This flag is set just before a callout's function is being called. 201Since the priority level is lowered prior to invocation of the 202callout function, other pending higher-priority code may run before 203the callout function is allowed to run. 204This may create a race condition if this higher-priority code 205deallocates storage containing one or more callout structures whose 206callout functions are about to be run. 207In such cases, one technique to prevent references to deallocated 208storage would be to test whether any callout functions are in the 209.Em INVOKING 210state using 211.Fn callout_invoking , 212and if so, to mark the data structure and defer storage 213deallocation until the callout function is allowed to run. 214For this handshake protocol to work, the callout function will 215have to use the 216.Fn callout_ack 217function to clear this flag. 218.Pp 219The 220.Fn callout_ack 221function clears the 222.Em INVOKING 223state in the callout handle 224.Fa c . 225This is used in situations where it is necessary to protect against 226the race condition described under 227.Fn callout_invoking . 228.Sh SEE ALSO 229.Xr hz 9 230.Sh HISTORY 231The 232.Nm callout 233facility was implemented by Artur Grabowski and Thomas Nordin, based 234on the work of G. Varghese and A. Lauck, described in the paper 235Hashed and Hierarchical Timing Wheels: Data Structures for the 236Efficient Implementation of a Timer Facility 237in the Proceedings of the 11th ACM Annual Symposium on Operating System 238Principles, Austin, Texas, November 1987. 239It was adapted to the 240.Nx 241kernel by Jason R. Thorpe. 242