1.\" $NetBSD: callout.9,v 1.6 2002/02/13 08:18:38 ross Exp $ 2.\" 3.\" Copyright (c) 2000 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 21, 2000 38.Dt CALLOUT 9 39.Os 40.Sh NAME 41.Nm callout_init , 42.Nm callout_reset , 43.Nm callout_stop 44.Nd execute a function after a specified length of time 45.Sh SYNOPSIS 46.Fd #include \*[Lt]sys/callout.h\*[Gt] 47.Ft void 48.Fn "callout_init" "struct callout *c" 49.Ft void 50.Fn "callout_reset" "struct callout *c" "int ticks" \ 51 "void (*func)(void *)" "void *arg" 52.Ft void 53.Fn "callout_stop" "struct callout *c" 54.Ft int 55.Fn "callout_active" "struct callout *c" 56.Ft int 57.Fn "callout_pending" "struct callout *c" 58.Ft int 59.Fn "callout_expired" "struct callout *c" 60.Ft void 61.Fn "callout_deactivate" "struct callout *c" 62.Sh DESCRIPTION 63The 64.Nm callout 65facility provides a mechanism to execute a function at a given time. 66The timer is based on the hardclock timer which ticks 67.Dv hz 68times per second. The function is called at softclock interrupt level. 69.Pp 70Clients of the 71.Nm callout 72facility are responsible for providing pre-allocated 73callout structures, or 74.Dq handles . 75The 76.Nm callout 77facility replaces the historic 78.Bx 79functions 80.Fn timeout 81and 82.Fn untimeout . 83.Pp 84The 85.Fn callout_init 86function initializes the callout handle 87.Fa c 88for use. If it is inconvenient to call 89.Fn callout_init , 90statically-allocated callout handles may be initialized by assigning 91the value 92.Dv CALLOUT_INITIALIZER 93to them. 94.Pp 95The 96.Fn callout_reset 97function starts (or resets) the timer associated with the callout handle 98.Fa c . 99When the timer expires after 100.Fa ticks Ns No /hz 101seconds, the function specified by 102.Fa func 103will be called with the argument 104.Fa arg . 105Note that if the timer associated with the callout handle is already running, 106it will be implicitly stopped before being reset. 107Once the timer is started, the callout handle is marked as 108.Em ACTIVE 109and 110.Em PENDING . 111Once the timer expires, 112.Em PENDING 113status is cleared. Expiration of the timer does not affect 114.Em ACTIVE 115status. 116.Pp 117The 118.Fn callout_stop 119function stops the timer associated the callout handle 120.Fa c . 121The 122.Em ACTIVE 123and 124.Em PENDING 125status for the callout handle is cleared. It is safe to call 126.Fn callout_stop 127on a callout handle that is not active, so long as it is initialized. 128.Pp 129The 130.Fn callout_active 131function tests the 132.Em ACTIVE 133status of the callout handle 134.Fa c . 135An 136.Em ACTIVE 137callout is one that has been started but not explicitly stopped. 138Testing 139.Em ACTIVE 140status is a way to determine if a callout has been started. Once the 141callout fires, the executed function may clear 142.Em ACTIVE 143status. See 144.Fn callout_deactivate 145below. 146.Pp 147The 148.Fn callout_pending 149function tests the 150.Em PENDING 151status of the callout handle 152.Fa c . 153A 154.Em PENDING 155callout is one that has been started and whose function has not yet 156been called. Note that it is possible for a callout's timer to have 157expired without its function being called if interrupt level has not 158dropped low enough to let softclock interrupts through. Note that it 159is only safe to test 160.Em PENDING 161status when at softclock interrupt level or higher. 162.Pp 163The 164.Fn callout_expired 165function tests the opposite of 166.Fn callout_pending . 167That is to say that 168.Fn callout_expired 169returns true when the callout function has been called. 170.Pp 171The 172.Fn callout_deactivate 173function clears the 174.Em ACTIVE 175status of the callout handle 176.Fa c . 177Note that is only safe to call 178.Fn callout_deactivate 179if the callout function has already been executed, i.e. the callout 180is no longer 181.Em PENDING . 182.Sh SEE ALSO 183.Xr hz 9 184.Sh HISTORY 185The 186.Nm callout 187facility is based on the work of Adam M. Costello and George Varghese, 188published in a technical report entitled 189.Dq Redesigning the BSD Callout and Timer Facilities , 190and Justin Gibbs's subsequent integration into 191.Fx . 192It was modified for 193.Nx 194by Jason R. Thorpe, who also added optional statistics gathering and 195an alternate sorting mode for the callwheel. 196.Pp 197The original work on the data structures used in this implementation was 198published by G. Varghese and A. Lauck in the paper 199Hashed and Hierarchical Timing Wheels: Data Structures for the 200Efficient Implementation of a Timer Facility 201in the Proceedings of the 11th ACM Annual Symposium on Operating System 202Principles, Austin, Texas, November 1987. 203