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