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.2 2003/06/17 04:37:01 dillon 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
151 Thus they are protected from re-entrancy.
158 are low-level routines for clients who wish to allocate their own
163 initializes a callout so it can be passed to
167 without any side effects.
171 cancels a callout if it is currently pending.
172 If the callout is pending, then
174 will return a non-zero value.
175 If the callout has already been serviced or is currently being serviced,
176 then zero will be returned.
182 to disestablish the callout, and then establishes a new callout in the
189 .Ft struct callout_handle
190 that can be passed to
194 function returns non-zero if the callout is still pending or zero otherwise.
196 The current timeout and untimeout routines are based on the work of
199 .An George Varghese ,
200 published in a technical report entitled
201 .%T "Redesigning the BSD Callout and Timer Facilities"
202 and modified slightly for inclusion in
205 .An Justin T. Gibbs .
206 The original work on the data structures used in this implementation
212 .%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility"
214 .%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" .
215 The current implementation replaces the long standing
218 callout mechanism which offered O(n) insertion and removal running time
219 but did not generate or require handles for untimeout operations.