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.
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
22 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
38 .Nm callout_handle_init ,
40 .Nm callout_init_mtx ,
45 .Nm callout_schedule ,
48 .Nm callout_deactivate
49 .Nd execute a function after a specified length of time
55 typedef void timeout_t (void *);
57 .Ft struct callout_handle
58 .Fn timeout "timeout_t *func" "void *arg" "int ticks"
60 .Fn callout_handle_init "struct callout_handle *handle"
63 struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle)
66 .Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle"
68 .Fn callout_init "struct callout *c" "int mpsafe"
70 .Fn callout_init_mtx "struct callout *c" "struct mtx *mtx" "int flags"
72 .Fn callout_init_rw "struct callout *c" "struct rwlock *rw" "int flags"
74 .Fn callout_stop "struct callout *c"
76 .Fn callout_drain "struct callout *c"
78 .Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg"
80 .Fn callout_schedule "struct callout *c" "int ticks"
82 .Fn callout_pending "struct callout *c"
84 .Fn callout_active "struct callout *c"
85 .Fn callout_deactivate "struct callout *c"
89 schedules a call to the function given by the argument
94 Non-positive values of
96 are silently converted to the value
99 should be a pointer to a function that takes a
106 as its only argument.
107 The return value from
110 .Ft struct callout_handle
111 which can be used in conjunction with the
113 function to request that a scheduled timeout be canceled.
116 call is the old style and new code should use the
121 .Fn callout_handle_init
122 can be used to initialize a handle to a state which will cause
125 with that handle to return with no side
128 Assigning a callout handle the value of
129 .Fn CALLOUT_HANDLE_INITIALIZER
130 performs the same function as
131 .Fn callout_handle_init
132 and is provided for use on statically declared or global callout handles.
136 cancels the timeout associated with
142 arguments to validate the handle.
143 If the handle does not correspond to a timeout with
150 must be initialized by a previous call to
152 .Fn callout_handle_init ,
153 or assigned the value of
154 .Fn CALLOUT_HANDLE_INITIALIZER "&handle"
155 before being passed to
157 The behavior of calling
159 with an uninitialized handle
163 call is the old style and new code should use the
167 As handles are recycled by the system, it is possible (although unlikely)
168 that a handle from one invocation of
170 may match the handle of another invocation of
172 if both calls used the same function pointer and argument, and the first
173 timeout is expired or canceled before the second call.
174 The timeout facility offers O(1) running time for
178 Timeouts are executed from
183 Thus they are protected from re-entrancy.
187 .Fn callout_init_mtx ,
188 .Fn callout_init_rw ,
194 are low-level routines for clients who wish to allocate their own
199 initializes a callout so it can be passed to
205 without any side effects.
209 the callout structure is not considered to be
210 .Dq multi-processor safe ;
212 the Giant lock will be acquired before calling the callout function,
213 and released when the callout function returns.
217 function may be used as an alternative to
221 specifies a mutex that is to be acquired by the callout subsystem
222 before calling the callout function, and released when the callout
227 .Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED"
228 .It Dv CALLOUT_RETURNUNLOCKED
229 The callout function will release
231 itself, so the callout subsystem should not attempt to unlock it
232 after the callout function returns.
237 function serves the need of using rwlocks in conjunction with callouts.
238 The function does basically the same as
240 with the possibility of specifying an extra
243 The usable lock classes are currently limited to mutexes and rwlocks,
244 because callout handlers run in softclock swi, so they cannot sleep nor
245 acquire sleepable locks like sx or lockmgr.
249 .Bl -tag -width ".Dv CALLOUT_SHAREDLOCK"
250 .It Dv CALLOUT_SHAREDLOCK
251 The lock is only acquired in read mode when running the callout handler.
252 It has no effects when used in conjunction with
258 cancels a callout if it is currently pending.
259 If the callout is pending, then
261 will return a non-zero value.
262 If the callout is not set, has already been serviced or is currently
263 being serviced, then zero will be returned.
264 If the callout has an associated mutex, then that mutex must be
265 held when this function is called.
271 except that it will wait for the callout to be completed if it is
273 This function MUST NOT be called while holding any
274 locks on which the callout might block, or deadlock will result.
275 Note that if the callout subsystem has already begun processing this
276 callout, then the callout function may be invoked during the execution of
278 However, the callout subsystem does guarantee that the callout will be
285 first performs the equivalent of
287 to disestablish the callout, and then establishes a new callout in the
290 If there was already a pending callout and it was rescheduled, then
292 will return a non-zero value.
293 If the callout has an associated mutex, then that mutex must be
294 held when this function is called.
297 (re)schedules an existing callout for a new period of time;
298 it is equivalent to calling
304 parameters extracted from the callout structure (though possibly with
308 .Fn callout_pending ,
311 .Fn callout_deactivate
312 provide access to the current state of the callout.
313 Careful use of these macros can avoid many of the race conditions
314 that are inherent in asynchronous timer facilities; see
315 .Sx "Avoiding Race Conditions"
316 below for further details.
319 macro checks whether a callout is
321 a callout is considered
323 when a timeout has been set but the time has not yet arrived.
324 Note that once the timeout time arrives and the callout subsystem
325 starts to process this callout,
329 even though the callout function may not have finished (or even begun)
333 macro checks whether a callout is marked as
336 .Fn callout_deactivate
337 macro clears the callout's
340 The callout subsystem marks a callout as
342 when a timeout is set and it clears the
350 clear it when a callout expires normally via the execution of the
352 .Ss "Avoiding Race Conditions"
353 The callout subsystem invokes callout functions from its own timer
355 Without some kind of synchronization it is possible that a callout
356 function will be invoked concurrently with an attempt to stop or reset
357 the callout by another thread.
358 In particular, since callout functions typically acquire a mutex as
359 their first action, the callout function may have already been invoked,
360 but be blocked waiting for that mutex at the time that another thread
361 tries to reset or stop the callout.
363 The callout subsystem provides a number of mechanisms to address these
364 synchronization concerns:
365 .Bl -enum -offset indent
367 If the callout has an associated mutex that was specified using the
369 function (or implicitly specified as the
377 then this mutex is used to avoid the race conditions.
378 The associated mutex must be acquired by the caller before calling
382 and it is guaranteed that the callout will be correctly stopped
383 or reset as expected.
384 Note that it is still necessary to use
386 before destroying the callout or its associated mutex.
388 The return value from
392 indicates whether or not the callout was removed.
393 If it is known that the callout was set and the callout function has
394 not yet executed, then a return value of
396 indicates that the callout function is about to be called.
398 .Bd -literal -offset indent
399 if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) {
400 if (callout_stop(&sc->sc_callout)) {
401 sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING;
402 /* successfully stopped */
405 * callout has expired and callout
406 * function is about to be executed
413 .Fn callout_pending ,
416 .Fn callout_deactivate
417 macros can be used together to work around the race conditions.
418 When a callout's timeout is set, the callout subsystem marks the
423 When the timeout time arrives, the callout subsystem begins processing
424 the callout by first clearing the
427 It then invokes the callout function without changing the
429 flag, and does not clear the
431 flag even after the callout function returns.
432 The mechanism described here requires the callout function itself to
436 .Fn callout_deactivate
442 functions always clear both the
446 flags before returning.
448 The callout function should first check the
450 flag and return without action if
454 This indicates that the callout was rescheduled using
456 just before the callout function was invoked.
461 then the callout function should also return without action.
462 This indicates that the callout has been stopped.
463 Finally, the callout function should call
464 .Fn callout_deactivate
469 .Bd -literal -offset indent
470 mtx_lock(&sc->sc_mtx);
471 if (callout_pending(&sc->sc_callout)) {
472 /* callout was reset */
473 mtx_unlock(&sc->sc_mtx);
476 if (!callout_active(&sc->sc_callout)) {
477 /* callout was stopped */
478 mtx_unlock(&sc->sc_mtx);
481 callout_deactivate(&sc->sc_callout);
482 /* rest of callout function */
485 Together with appropriate synchronization, such as the mutex used above,
486 this approach permits the
490 functions to be used at any time without races.
492 .Bd -literal -offset indent
493 mtx_lock(&sc->sc_mtx);
494 callout_stop(&sc->sc_callout);
495 /* The callout is effectively stopped now. */
498 If the callout is still pending then these functions operate normally,
499 but if processing of the callout has already begun then the tests in
500 the callout function cause it to return without further action.
501 Synchronization between the callout function and other code ensures that
502 stopping or resetting the callout will never be attempted while the
503 callout function is past the
504 .Fn callout_deactivate
507 The above technique additionally ensures that the
509 flag always reflects whether the callout is effectively enabled or
513 returns false, then the callout is effectively disabled, since even if
514 the callout subsystem is actually just about to invoke the callout
515 function, the callout function will return without action.
518 There is one final race condition that must be considered when a
519 callout is being stopped for the last time.
520 In this case it may not be safe to let the callout function itself
521 detect that the callout was stopped, since it may need to access
522 data objects that have already been destroyed or recycled.
523 To ensure that the callout is completely finished, a call to
530 .Ft struct callout_handle
531 that can be passed to
537 functions return non-zero if the callout was still pending when it was
538 called or zero otherwise.
540 The current timeout and untimeout routines are based on the work of
543 .An George Varghese ,
544 published in a technical report entitled
545 .%T "Redesigning the BSD Callout and Timer Facilities"
546 and modified slightly for inclusion in
549 .An Justin T. Gibbs .
550 The original work on the data structures used in this implementation
556 .%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility"
558 .%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" .
559 The current implementation replaces the long standing
562 callout mechanism which offered O(n) insertion and removal running time
563 but did not generate or require handles for untimeout operations.