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.
45 .Nm callout_handle_init ,
47 .Nm callout_init_mtx ,
53 .Nm callout_deactivate
54 .Nd execute a function after a specified length of time
60 typedef void timeout_t (void *);
62 .Ft struct callout_handle
63 .Fn timeout "timeout_t *func" "void *arg" "int ticks"
65 .Fn callout_handle_init "struct callout_handle *handle"
68 struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle)
71 .Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle"
73 .Fn callout_init "struct callout *c" "int mpsafe"
75 .Fn callout_init_mtx "struct callout *c" "struct mtx *mtx" "int flags"
77 .Fn callout_stop "struct callout *c"
79 .Fn callout_drain "struct callout *c"
81 .Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg"
83 .Fn callout_pending "struct callout *c"
85 .Fn callout_active "struct callout *c"
86 .Fn callout_deactivate "struct callout *c"
90 schedules a call to the function given by the argument
95 Non-positive values of
97 are silently converted to the value
100 should be a pointer to a function that takes a
107 as its only argument.
108 The return value from
111 .Ft struct callout_handle
112 which can be used in conjunction with the
114 function to request that a scheduled timeout be canceled.
117 call is the old style and new code should use the
122 .Fn callout_handle_init
123 can be used to initialize a handle to a state which will cause
126 with that handle to return with no side
129 Assigning a callout handle the value of
130 .Fn CALLOUT_HANDLE_INITIALIZER
131 performs the same function as
132 .Fn callout_handle_init
133 and is provided for use on statically declared or global callout handles.
137 cancels the timeout associated with
143 arguments to validate the handle.
144 If the handle does not correspond to a timeout with
151 must be initialized by a previous call to
153 .Fn callout_handle_init ,
154 or assigned the value of
155 .Fn CALLOUT_HANDLE_INITIALIZER "&handle"
156 before being passed to
158 The behavior of calling
160 with an uninitialized handle
164 call is the old style and new code should use the
168 As handles are recycled by the system, it is possible (although unlikely)
169 that a handle from one invocation of
171 may match the handle of another invocation of
173 if both calls used the same function pointer and argument, and the first
174 timeout is expired or canceled before the second call.
175 The timeout facility offers O(1) running time for
179 Timeouts are executed from
184 Thus they are protected from re-entrancy.
188 .Fn callout_init_mtx ,
193 are low-level routines for clients who wish to allocate their own
198 initializes a callout so it can be passed to
203 without any side effects.
207 the callout structure is not considered to be
208 .Dq multi-processor safe ;
210 the Giant lock will be acquired before calling the callout function,
211 and released when the callout function returns.
215 function may be used as an alternative to
219 specifies a mutex that is to be acquired by the callout subsystem
220 before calling the callout function, and released when the callout
225 .Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED"
226 .It Dv CALLOUT_RETURNUNLOCKED
227 The callout function will release
229 itself, so the callout subsystem should not attempt to unlock it
230 after the callout function returns.
235 cancels a callout if it is currently pending.
236 If the callout is pending, then
238 will return a non-zero value.
239 If the callout is not set, has already been serviced or is currently
240 being serviced, then zero will be returned.
241 If the callout has an associated mutex, then that mutex must be
242 held when this function is called.
248 except that it will wait for the callout to be completed if it is
250 This function MUST NOT be called while holding any
251 locks on which the callout might block, or deadlock will result.
252 Note that if the callout subsystem has already begun processing this
253 callout, then the callout function may be invoked during the execution of
255 However, the callout subsystem does guarantee that the callout will be
262 first performs the equivalent of
264 to disestablish the callout, and then establishes a new callout in the
267 If there was already a pending callout and it was rescheduled, then
269 will return a non-zero value.
270 If the callout has an associated mutex, then that mutex must be
271 held when this function is called.
274 .Fn callout_pending ,
277 .Fn callout_deactivate
278 provide access to the current state of the callout.
279 Careful use of these macros can avoid many of the race conditions
280 that are inherent in asynchronous timer facilities; see
281 .Sx "Avoiding Race Conditions"
282 below for further details.
285 macro checks whether a callout is
287 a callout is considered
289 when a timeout has been set but the time has not yet arrived.
290 Note that once the timeout time arrives and the callout subsystem
291 starts to process this callout,
295 even though the callout function may not have finished (or even begun)
299 macro checks whether a callout is marked as
302 .Fn callout_deactivate
303 macro clears the callout's
306 The callout subsystem marks a callout as
308 when a timeout is set and it clears the
316 clear it when a callout expires normally via the execution of the
318 .Ss "Avoiding Race Conditions"
319 The callout subsystem invokes callout functions from its own timer
321 Without some kind of synchronization it is possible that a callout
322 function will be invoked concurrently with an attempt to stop or reset
323 the callout by another thread.
324 In particular, since callout functions typically acquire a mutex as
325 their first action, the callout function may have already been invoked,
326 but be blocked waiting for that mutex at the time that another thread
327 tries to reset or stop the callout.
329 The callout subsystem provides a number of mechanisms to address these
330 synchronization concerns:
331 .Bl -enum -offset indent
333 If the callout has an associated mutex that was specified using the
335 function (or implicitly specified as the
343 then this mutex is used to avoid the race conditions.
344 The associated mutex must be acquired by the caller before calling
348 and it is guaranteed that the callout will be correctly stopped
349 or reset as expected.
350 Note that it is still necessary to use
352 before destroying the callout or its associated mutex.
354 The return value from
358 indicates whether or not the callout was removed.
359 If it is known that the callout was set and the callout function has
360 not yet executed, then a return value of
362 indicates that the callout function is about to be called.
364 .Bd -literal -offset indent
365 if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) {
366 if (callout_stop(&sc->sc_callout)) {
367 sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING;
368 /* successfully stopped */
371 * callout has expired and callout
372 * function is about to be executed
379 .Fn callout_pending ,
382 .Fn callout_deactivate
383 macros can be used together to work around the race conditions.
384 When a callout's timeout is set, the callout subsystem marks the
389 When the timeout time arrives, the callout subsystem begins processing
390 the callout by first clearing the
393 It then invokes the callout function without changing the
395 flag, and does not clear the
397 flag even after the callout function returns.
398 The mechanism described here requires the callout function itself to
402 .Fn callout_deactivate
408 functions always clear both the
412 flags before returning.
414 The callout function should first check the
416 flag and return without action if
420 This indicates that the callout was rescheduled using
422 just before the callout function was invoked.
427 then the callout function should also return without action.
428 This indicates that the callout has been stopped.
429 Finally, the callout function should call
430 .Fn callout_deactivate
435 .Bd -literal -offset indent
436 mtx_lock(&sc->sc_mtx);
437 if (callout_pending(&sc->sc_callout)) {
438 /* callout was reset */
439 mtx_unlock(&sc->sc_mtx);
442 if (!callout_active(&sc->sc_callout)) {
443 /* callout was stopped */
444 mtx_unlock(&sc->sc_mtx);
447 callout_deactivate(&sc->sc_callout);
448 /* rest of callout function */
451 Together with appropriate synchronization, such as the mutex used above,
452 this approach permits the
456 functions to be used at any time without races.
458 .Bd -literal -offset indent
459 mtx_lock(&sc->sc_mtx);
460 callout_stop(&sc->sc_callout);
461 /* The callout is effectively stopped now. */
464 If the callout is still pending then these functions operate normally,
465 but if processing of the callout has already begun then the tests in
466 the callout function cause it to return without further action.
467 Synchronization between the callout function and other code ensures that
468 stopping or resetting the callout will never be attempted while the
469 callout function is past the
470 .Fn callout_deactivate
473 The above technique additionally ensures that the
475 flag always reflects whether the callout is effectively enabled or
479 returns false, then the callout is effectively disabled, since even if
480 the callout subsystem is actually just about to invoke the callout
481 function, the callout function will return without action.
484 There is one final race condition that must be considered when a
485 callout is being stopped for the last time.
486 In this case it may not be safe to let the callout function itself
487 detect that the callout was stopped, since it may need to access
488 data objects that have already been destroyed or recycled.
489 To ensure that the callout is completely finished, a call to
496 .Ft struct callout_handle
497 that can be passed to
503 functions return non-zero if the callout was still pending when it was
504 called or zero otherwise.
506 The current timeout and untimeout routines are based on the work of
509 .An George Varghese ,
510 published in a technical report entitled
511 .%T "Redesigning the BSD Callout and Timer Facilities"
512 and modified slightly for inclusion in
515 .An Justin T. Gibbs .
516 The original work on the data structures used in this implementation
522 .%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility"
524 .%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" .
525 The current implementation replaces the long standing
528 callout mechanism which offered O(n) insertion and removal running time
529 but did not generate or require handles for untimeout operations.