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.2 2003/06/17 04:37:01 dillon 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 149at 150.Fn splsoftclock . 151Thus they are protected from re-entrancy. 152.Pp 153The functions 154.Fn callout_init , 155.Fn callout_stop 156and 157.Fn callout_reset 158are low-level routines for clients who wish to allocate their own 159callout structures. 160.Pp 161The function 162.Fn callout_init 163initializes a callout so it can be passed to 164.Fn callout_stop 165or 166.Fn callout_reset 167without any side effects. 168.Pp 169The function 170.Fn callout_stop 171cancels a callout if it is currently pending. 172If the callout is pending, then 173.Fn callout_stop 174will return a non-zero value. 175If the callout has already been serviced or is currently being serviced, 176then zero will be returned. 177.Pp 178The function 179.Fn callout_reset 180first calls 181.Fn callout_stop 182to disestablish the callout, and then establishes a new callout in the 183same manner as 184.Fn timeout . 185.Sh RETURN VALUES 186The 187.Fn timeout 188function returns a 189.Ft struct callout_handle 190that can be passed to 191.Fn untimeout . 192The 193.Fn callout_stop 194function returns non-zero if the callout is still pending or zero otherwise. 195.Sh HISTORY 196The current timeout and untimeout routines are based on the work of 197.An Adam M. Costello 198and 199.An George Varghese , 200published in a technical report entitled 201.%T "Redesigning the BSD Callout and Timer Facilities" 202and modified slightly for inclusion in 203.Fx 204by 205.An Justin T. Gibbs . 206The original work on the data structures used in this implementation 207was published by 208.An G. Varghese 209and 210.An A. Lauck 211in the paper 212.%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility" 213in the 214.%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" . 215The current implementation replaces the long standing 216.Bx 217linked list 218callout mechanism which offered O(n) insertion and removal running time 219but did not generate or require handles for untimeout operations. 220