1 .\" $NetBSD: timeout.9,v 1.2 1996/06/23 22:32:34 pk Exp $
3 .\" Copyright (c) 1996 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Paul Kranenburg.
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
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.
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.
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/Attic/timeout.9,v 1.3 2006/02/25 19:14:53 swildner Exp $
40 .Dd September 10, 1996
45 .Nd execute a function after a specified length of time
51 typedef void timeout_t (void *);
53 .Ft struct callout_handle
54 .Fn timeout "timeout_t *func" "void *arg" "int ticks"
56 .Fn callout_handle_init "struct callout_handle *handle"
59 struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle)
62 .Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle"
64 .Fn callout_init "struct callout *c"
66 .Fn callout_stop "struct callout *c"
68 .Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg"
72 schedules a call to the function given by the argument
77 Non-positive values of
79 are silently converted to the value
82 should be a pointer to a function that takes a
93 .Ft struct callout_handle
94 which can be used in conjunction with the
96 function to request that a scheduled timeout be canceled.
99 .Fn callout_handle_init
100 can be used to initialize a handle to a state which will cause
101 any calls to untimeout with that handle to return with no side
104 Assigning a callout handle the value of
105 .Fn CALLOUT_HANDLE_INITIALIZER
106 performs the same function as
107 .Fn callout_handle_init
108 and is provided for use on statically declared or global callout handles.
112 cancels the timeout associated with
118 arguments to validate the handle.
119 If the handle does not correspond to a timeout with
126 must be initialized by a previous call to
128 .Fn callout_handle_init ,
129 or assigned the value of
130 .Fn CALLOUT_HANDLE_INITIALIZER "&handle"
131 before being passed to
133 The behavior of calling untimeout without a previously initialized handle
136 As handles are recycled by the system, it is possible (although unlikely)
137 that a handle from one invocation of
139 may match the handle of another invocation of
141 if both calls used the same function pointer and argument, and the first
142 timeout is expired or canceled before the second call.
143 The timeout facility offers O(1) running time for
147 Timeouts are executed from
149 inside a critical section.
150 Thus they are protected from re-entrancy.
157 are low-level routines for clients who wish to allocate their own
162 initializes a callout so it can be passed to
166 without any side effects.
170 cancels a callout if it is currently pending.
171 If the callout is pending, then
173 will return a non-zero value.
174 If the callout has already been serviced or is currently being serviced,
175 then zero will be returned.
181 to disestablish the callout, and then establishes a new callout in the
188 .Ft struct callout_handle
189 that can be passed to
193 function returns non-zero if the callout is still pending or zero otherwise.
195 The current timeout and untimeout routines are based on the work of
198 .An George Varghese ,
199 published in a technical report entitled
200 .%T "Redesigning the BSD Callout and Timer Facilities"
201 and modified slightly for inclusion in
204 .An Justin T. Gibbs .
205 The original work on the data structures used in this implementation
211 .%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility"
213 .%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" .
214 The current implementation replaces the long standing
217 callout mechanism which offered O(n) insertion and removal running time
218 but did not generate or require handles for untimeout operations.