1.\" $NetBSD: timeout.9,v 1.2 1996/06/23 22:32:34 pk Exp $ 2.\" 3.\" Copyright (c) 1996 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Paul Kranenburg. 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 REGENTS OR CONTRIBUTORS BE 29.\" 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.\" $FreeBSD: src/share/man/man9/timeout.9,v 1.9.2.6 2001/12/17 11:30:19 ru Exp $ 38.\" $DragonFly: src/share/man/man9/callout.9,v 1.3 2006/02/25 19:14:53 swildner Exp $ 39.\" 40.Dd September 10, 1996 41.Dt TIMEOUT 9 42.Os 43.Sh NAME 44.Nm timeout 45.Nd execute a function after a specified length of time 46.Sh SYNOPSIS 47.In sys/types.h 48.In sys/systm.h 49.Pp 50.Bd -literal 51typedef void timeout_t (void *); 52.Ed 53.Ft struct callout_handle 54.Fn timeout "timeout_t *func" "void *arg" "int ticks" 55.Ft void 56.Fn callout_handle_init "struct callout_handle *handle" 57.Pp 58.Bd -literal 59struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle) 60.Ed 61.Ft void 62.Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle" 63.Ft void 64.Fn callout_init "struct callout *c" 65.Ft int 66.Fn callout_stop "struct callout *c" 67.Ft void 68.Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg" 69.Sh DESCRIPTION 70The function 71.Fn timeout 72schedules a call to the function given by the argument 73.Fa func 74to take place after 75.Fa ticks Ns No /hz 76seconds. 77Non-positive values of 78.Fa ticks 79are silently converted to the value 80.Sq 1 . 81.Fa func 82should be a pointer to a function that takes a 83.Fa void * 84argument. 85Upon invocation, 86.Fa func 87will receive 88.Fa arg 89as its only argument. 90The return value from 91.Fn timeout 92is a 93.Ft struct callout_handle 94which can be used in conjunction with the 95.Fn untimeout 96function to request that a scheduled timeout be canceled. 97.Pp 98The function 99.Fn callout_handle_init 100can be used to initialize a handle to a state which will cause 101any calls to untimeout with that handle to return with no side 102effects. 103.Pp 104Assigning a callout handle the value of 105.Fn CALLOUT_HANDLE_INITIALIZER 106performs the same function as 107.Fn callout_handle_init 108and is provided for use on statically declared or global callout handles. 109.Pp 110The function 111.Fn untimeout 112cancels the timeout associated with 113.Fa handle 114using the 115.Fa func 116and 117.Fa arg 118arguments to validate the handle. 119If the handle does not correspond to a timeout with 120the function 121.Fa func 122taking the argument 123.Fa arg 124no action is taken. 125.Fa handle 126must be initialized by a previous call to 127.Fn timeout , 128.Fn callout_handle_init , 129or assigned the value of 130.Fn CALLOUT_HANDLE_INITIALIZER "&handle" 131before being passed to 132.Fn untimeout . 133The behavior of calling untimeout without a previously initialized handle 134is undefined. 135.Pp 136As handles are recycled by the system, it is possible (although unlikely) 137that a handle from one invocation of 138.Fn timeout 139may match the handle of another invocation of 140.Fn timeout 141if both calls used the same function pointer and argument, and the first 142timeout is expired or canceled before the second call. 143The timeout facility offers O(1) running time for 144.Fn timeout 145and 146.Fn untimeout . 147Timeouts are executed from 148.Fn softclock 149inside a critical section. 150Thus they are protected from re-entrancy. 151.Pp 152The functions 153.Fn callout_init , 154.Fn callout_stop 155and 156.Fn callout_reset 157are low-level routines for clients who wish to allocate their own 158callout structures. 159.Pp 160The function 161.Fn callout_init 162initializes a callout so it can be passed to 163.Fn callout_stop 164or 165.Fn callout_reset 166without any side effects. 167.Pp 168The function 169.Fn callout_stop 170cancels a callout if it is currently pending. 171If the callout is pending, then 172.Fn callout_stop 173will return a non-zero value. 174If the callout has already been serviced or is currently being serviced, 175then zero will be returned. 176.Pp 177The function 178.Fn callout_reset 179first calls 180.Fn callout_stop 181to disestablish the callout, and then establishes a new callout in the 182same manner as 183.Fn timeout . 184.Sh RETURN VALUES 185The 186.Fn timeout 187function returns a 188.Ft struct callout_handle 189that can be passed to 190.Fn untimeout . 191The 192.Fn callout_stop 193function returns non-zero if the callout is still pending or zero otherwise. 194.Sh HISTORY 195The current timeout and untimeout routines are based on the work of 196.An Adam M. Costello 197and 198.An George Varghese , 199published in a technical report entitled 200.%T "Redesigning the BSD Callout and Timer Facilities" 201and modified slightly for inclusion in 202.Fx 203by 204.An Justin T. Gibbs . 205The original work on the data structures used in this implementation 206was published by 207.An G. Varghese 208and 209.An A. Lauck 210in the paper 211.%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility" 212in the 213.%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" . 214The current implementation replaces the long standing 215.Bx 216linked list 217callout mechanism which offered O(n) insertion and removal running time 218but did not generate or require handles for untimeout operations. 219