1.\" $NetBSD: callout.9,v 1.9 2003/04/16 13:35:25 wiz 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 February 3, 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_INITIALIZER , 47.Nm CALLOUT_INITIALIZER_SETFUNC 48.Nd execute a function after a specified length of time 49.Sh SYNOPSIS 50.In sys/callout.h 51.Ft void 52.Fn "callout_init" "struct callout *c" 53.Ft void 54.Fn "callout_reset" "struct callout *c" "int ticks" \ 55 "void (*func)(void *)" "void *arg" 56.Ft void 57.Fn "callout_schedule" "struct callout *c" "int ticks" 58.Ft void 59.Fn "callout_setfunc" "struct callout *c" "void (*func)(void *)" "void *arg" 60.Ft void 61.Fn "callout_stop" "struct callout *c" 62.Ft int 63.Fn "callout_pending" "struct callout *c" 64.Ft int 65.Fn "callout_expired" "struct callout *c" 66.Fd CALLOUT_INITIALIZER 67.Pp 68.Fd CALLOUT_INITIALIZER_SETFUNC(func, arg) 69.Sh DESCRIPTION 70The 71.Nm callout 72facility provides a mechanism to execute a function at a given time. 73The timer is based on the hardclock timer which ticks 74.Dv hz 75times per second. 76The function is called at softclock interrupt level. 77.Pp 78Clients of the 79.Nm callout 80facility are responsible for providing pre-allocated 81callout structures, or 82.Dq handles . 83The 84.Nm callout 85facility replaces the historic 86.Bx 87functions 88.Fn timeout 89and 90.Fn untimeout . 91.Pp 92The 93.Fn callout_init 94function initializes the callout handle 95.Fa c 96for use. 97If it is inconvenient to call 98.Fn callout_init , 99statically-allocated callout handles may be initialized by assigning 100the value 101.Dv CALLOUT_INITIALIZER 102to them. 103.Pp 104The 105.Fn callout_reset 106function resets and starts the timer associated with the callout handle 107.Fa c . 108When the timer expires after 109.Fa ticks Ns No /hz 110seconds, the function specified by 111.Fa func 112will be called with the argument 113.Fa arg . 114If the timer associated with the callout handle is already running, 115the callout will simply be rescheduled to execute at the newly specified 116time. 117Once the timer is started, the callout handle is marked as 118.Em PENDING . 119Once the timer expires, 120the handle is marked at 121.Em EXPIRED 122and the 123.Em PENDING 124status is cleared. 125.Pp 126The 127.Fn callout_setfunc 128function initializes the callout handle 129.Fa c 130for use and sets the function and argument to 131.Fa func 132and 133.Fa arg 134respectively. 135If a callout will always be used with the same function and argument, 136then 137.Fn callout_setfunc 138used in conjunction with 139.Fn callout_schedule 140is slightly more efficient than using 141.Fn callout_init 142and 143.Fn callout_reset . 144If it is inconvenient to call 145.Fn callout_setfunc , 146statically-allocated callout handles may be initialized by assigning 147the value 148.Dv CALLOUT_INITIALIZER_SETFUNC 149to them, passing the function and argument to the initializer. 150.Pp 151The 152.Fn callout_stop 153function stops the timer associated the callout handle 154.Fa c . 155The 156.Em PENDING 157status for the callout handle is cleared. 158The 159.Em EXPIRED 160status is not affected. 161It is safe to call 162.Fn callout_stop 163on a callout handle that is not pending, so long as it is initialized. 164.Pp 165The 166.Fn callout_pending 167function tests the 168.Em PENDING 169status of the callout handle 170.Fa c . 171A 172.Em PENDING 173callout is one that has been started and whose function has not yet 174been called. 175Note that it is possible for a callout's timer to have expired without 176its function being called if interrupt level has not dropped low enough 177to let softclock interrupts through. 178Note that it is only safe to test 179.Em PENDING 180status when at softclock interrupt level or higher. 181.Pp 182The 183.Fn callout_expired 184function tests to see if the callout's timer has expired and its 185function called. 186.Sh SEE ALSO 187.Xr hz 9 188.Sh HISTORY 189The 190.Nm callout 191facility was implemented by Artur Grabowski and Thomas Nordin, based 192on the work of G. Varghese and A. Lauck, described in the paper 193Hashed and Hierarchical Timing Wheels: Data Structures for the 194Efficient Implementation of a Timer Facility 195in the Proceedings of the 11th ACM Annual Symposium on Operating System 196Principles, Austin, Texas, November 1987. 197It was adapted to the 198.Nx 199kernel by Jason R. Thorpe. 200