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