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 ,
46 .Nm callout_reset_on ,
47 .Nm callout_reset_curcpu ,
48 .Nm callout_reset_sbt ,
49 .Nm callout_reset_sbt_on ,
50 .Nm callout_reset_sbt_curcpu ,
51 .Nm callout_schedule ,
52 .Nm callout_schedule_on ,
53 .Nm callout_schedule_curcpu ,
56 .Nm callout_deactivate
57 .Nd execute a function after a specified length of time
62 typedef void timeout_t (void *);
64 .Ft struct callout_handle
65 .Fn timeout "timeout_t *func" "void *arg" "int ticks"
67 .Fn callout_handle_init "struct callout_handle *handle"
69 struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle);
72 .Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle"
74 .Fn callout_init "struct callout *c" "int mpsafe"
76 .Fn callout_init_mtx "struct callout *c" "struct mtx *mtx" "int flags"
78 .Fn callout_init_rm "struct callout *c" "struct rmlock *rm" "int flags"
80 .Fn callout_init_rw "struct callout *c" "struct rwlock *rw" "int flags"
82 .Fn callout_stop "struct callout *c"
84 .Fn callout_drain "struct callout *c"
86 .Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg"
88 .Fn callout_reset_on "struct callout *c" "int ticks" "timeout_t *func" \
91 .Fn callout_reset_sbt_on "struct callout *c" "sbintime_t sbt" \
92 "sbintime_t pr" "timeout_t *func" "void *arg" "int cpu" "int flags"
94 .Fn callout_reset_curcpu "struct callout *c" "int ticks" "timeout_t *func" \
97 .Fn callout_schedule "struct callout *c" "int ticks"
99 .Fn callout_schedule_on "struct callout *c" "int ticks" "int cpu"
101 .Fn callout_schedule_curcpu "struct callout *c" "int ticks"
103 .Fn callout_pending "struct callout *c"
105 .Fn callout_active "struct callout *c"
107 .Fn callout_deactivate "struct callout *c"
111 schedules a call to the function given by the argument
116 Non-positive values of
118 are silently converted to the value
121 should be a pointer to a function that takes a
128 as its only argument.
129 The return value from
132 .Ft struct callout_handle
133 which can be used in conjunction with the
135 function to request that a scheduled timeout be canceled.
138 call is the old style and new code should use the
143 .Fn callout_handle_init
144 can be used to initialize a handle to a state which will cause
147 with that handle to return with no side
150 Assigning a callout handle the value of
151 .Fn CALLOUT_HANDLE_INITIALIZER
152 performs the same function as
153 .Fn callout_handle_init
154 and is provided for use on statically declared or global callout handles.
158 cancels the timeout associated with
164 arguments to validate the handle.
165 If the handle does not correspond to a timeout with
172 must be initialized by a previous call to
174 .Fn callout_handle_init ,
175 or assigned the value of
176 .Fn CALLOUT_HANDLE_INITIALIZER "&handle"
177 before being passed to
179 The behavior of calling
181 with an uninitialized handle
185 call is the old style and new code should use the
189 As handles are recycled by the system, it is possible (although unlikely)
190 that a handle from one invocation of
192 may match the handle of another invocation of
194 if both calls used the same function pointer and argument, and the first
195 timeout is expired or canceled before the second call.
196 The timeout facility offers O(1) running time for
200 Timeouts are executed from
205 Thus they are protected from re-entrancy.
209 .Fn callout_init_mtx ,
210 .Fn callout_init_rm ,
211 .Fn callout_init_rw ,
217 are low-level routines for clients who wish to allocate their own
222 initializes a callout so it can be passed to
228 without any side effects.
232 the callout structure is not considered to be
233 .Dq multi-processor safe ;
235 the Giant lock will be acquired before calling the callout function,
236 and released when the callout function returns.
240 function may be used as an alternative to
244 specifies a mutex that is to be acquired by the callout subsystem
245 before calling the callout function, and released when the callout
250 .Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED"
251 .It Dv CALLOUT_RETURNUNLOCKED
252 The callout function will release
254 itself, so the callout subsystem should not attempt to unlock it
255 after the callout function returns.
262 fuctions serve the need of using rwlocks and rmlocks in conjunction
264 The functions do the same as
266 with the possibility of specifying an extra
273 argument is specified, the lock should be created without passing the
276 The usable lock classes are currently limited to mutexes, rwlocks and
277 non-sleepable rmlocks, because callout handlers run in softclock swi,
278 so they cannot sleep nor acquire sleepable locks like sx or lockmgr.
282 .Bl -tag -width ".Dv CALLOUT_SHAREDLOCK"
283 .It Dv CALLOUT_SHAREDLOCK
284 The lock is only acquired in read mode when running the callout handler.
285 It has no effects when used in conjunction with
291 cancels a callout if it is currently pending.
292 If the callout is pending, then
294 will return a non-zero value.
295 If the callout is not set, has already been serviced or is currently
296 being serviced, then zero will be returned.
297 If the callout has an associated mutex, then that mutex must be
298 held when this function is called.
304 except that it will wait for the callout to be completed if it is
306 This function MUST NOT be called while holding any
307 locks on which the callout might block, or deadlock will result.
308 Note that if the callout subsystem has already begun processing this
309 callout, then the callout function may be invoked during the execution of
311 However, the callout subsystem does guarantee that the callout will be
318 first performs the equivalent of
320 to disestablish the callout, and then establishes a new callout in the
323 If there was already a pending callout and it was rescheduled, then
325 will return a non-zero value.
326 If the callout has an associated mutex, then that mutex must be
327 held when this function is called.
330 (re)schedules an existing callout for a new period of time;
331 it is equivalent to calling
337 parameters extracted from the callout structure (though possibly with
343 .Fn callout_schedule_on
348 but take an extra parameter specifying the target CPU for the callout.
351 .Fn callout_reset_sbt_on
352 allows to get higher time resolution, taking relative or absolute time
353 and precision instead of relative ticks count.
354 If specified time is in past, it will be silently converted to present
355 to run handler as soon as possible.
360 .Bl -tag -width ".Dv C_DIRECT_EXEC"
364 argument as absolute time of the event since boot, or relative time otherwise.
366 Run handler directly from hardware interrupt context instead of softclock swi.
367 It is faster, but puts more constraints on handlers.
368 Handlers may use only spin mutexes for locking, and they must be fast because
369 they run with absolute priority.
371 Specifies relative event time precision as binary logarithm of time interval
372 divided by acceptable time deviation: 1 -- 1/2, 2 -- 1/4, etc.
373 Smaller value allows to aggregate more events in one timer interrupt to
374 reduce processing overhead and power consumption.
378 .Fn callout_reset_curcpu
380 .Fn callout_schedule_curcpu
384 .Fn callout_schedule_on
385 using the current CPU as the target CPU.
388 .Fn callout_pending ,
391 .Fn callout_deactivate
392 provide access to the current state of the callout.
393 Careful use of these macros can avoid many of the race conditions
394 that are inherent in asynchronous timer facilities; see
395 .Sx "Avoiding Race Conditions"
396 below for further details.
399 macro checks whether a callout is
401 a callout is considered
403 when a timeout has been set but the time has not yet arrived.
404 Note that once the timeout time arrives and the callout subsystem
405 starts to process this callout,
409 even though the callout function may not have finished (or even begun)
413 macro checks whether a callout is marked as
416 .Fn callout_deactivate
417 macro clears the callout's
420 The callout subsystem marks a callout as
422 when a timeout is set and it clears the
430 clear it when a callout expires normally via the execution of the
432 .Ss "Avoiding Race Conditions"
433 The callout subsystem invokes callout functions from its own timer
435 Without some kind of synchronization it is possible that a callout
436 function will be invoked concurrently with an attempt to stop or reset
437 the callout by another thread.
438 In particular, since callout functions typically acquire a mutex as
439 their first action, the callout function may have already been invoked,
440 but be blocked waiting for that mutex at the time that another thread
441 tries to reset or stop the callout.
443 The callout subsystem provides a number of mechanisms to address these
444 synchronization concerns:
445 .Bl -enum -offset indent
447 If the callout has an associated mutex that was specified using the
449 function (or implicitly specified as the
457 then this mutex is used to avoid the race conditions.
458 The associated mutex must be acquired by the caller before calling
462 and it is guaranteed that the callout will be correctly stopped
463 or reset as expected.
464 Note that it is still necessary to use
466 before destroying the callout or its associated mutex.
468 The return value from
472 indicates whether or not the callout was removed.
473 If it is known that the callout was set and the callout function has
474 not yet executed, then a return value of
476 indicates that the callout function is about to be called.
478 .Bd -literal -offset indent
479 if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) {
480 if (callout_stop(&sc->sc_callout)) {
481 sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING;
482 /* successfully stopped */
485 * callout has expired and callout
486 * function is about to be executed
493 .Fn callout_pending ,
496 .Fn callout_deactivate
497 macros can be used together to work around the race conditions.
498 When a callout's timeout is set, the callout subsystem marks the
503 When the timeout time arrives, the callout subsystem begins processing
504 the callout by first clearing the
507 It then invokes the callout function without changing the
509 flag, and does not clear the
511 flag even after the callout function returns.
512 The mechanism described here requires the callout function itself to
516 .Fn callout_deactivate
522 functions always clear both the
526 flags before returning.
528 The callout function should first check the
530 flag and return without action if
534 This indicates that the callout was rescheduled using
536 just before the callout function was invoked.
541 then the callout function should also return without action.
542 This indicates that the callout has been stopped.
543 Finally, the callout function should call
544 .Fn callout_deactivate
549 .Bd -literal -offset indent
550 mtx_lock(&sc->sc_mtx);
551 if (callout_pending(&sc->sc_callout)) {
552 /* callout was reset */
553 mtx_unlock(&sc->sc_mtx);
556 if (!callout_active(&sc->sc_callout)) {
557 /* callout was stopped */
558 mtx_unlock(&sc->sc_mtx);
561 callout_deactivate(&sc->sc_callout);
562 /* rest of callout function */
565 Together with appropriate synchronization, such as the mutex used above,
566 this approach permits the
570 functions to be used at any time without races.
572 .Bd -literal -offset indent
573 mtx_lock(&sc->sc_mtx);
574 callout_stop(&sc->sc_callout);
575 /* The callout is effectively stopped now. */
578 If the callout is still pending then these functions operate normally,
579 but if processing of the callout has already begun then the tests in
580 the callout function cause it to return without further action.
581 Synchronization between the callout function and other code ensures that
582 stopping or resetting the callout will never be attempted while the
583 callout function is past the
584 .Fn callout_deactivate
587 The above technique additionally ensures that the
589 flag always reflects whether the callout is effectively enabled or
593 returns false, then the callout is effectively disabled, since even if
594 the callout subsystem is actually just about to invoke the callout
595 function, the callout function will return without action.
598 There is one final race condition that must be considered when a
599 callout is being stopped for the last time.
600 In this case it may not be safe to let the callout function itself
601 detect that the callout was stopped, since it may need to access
602 data objects that have already been destroyed or recycled.
603 To ensure that the callout is completely finished, a call to
610 .Ft struct callout_handle
611 that can be passed to
617 functions return non-zero if the callout was still pending when it was
618 called or zero otherwise.
620 The current timeout and untimeout routines are based on the work of
623 .An George Varghese ,
624 published in a technical report entitled
625 .%T "Redesigning the BSD Callout and Timer Facilities"
626 and modified slightly for inclusion in
629 .An Justin T. Gibbs .
630 The original work on the data structures used in this implementation
636 .%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility"
638 .%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" .
639 The current implementation replaces the long standing
642 callout mechanism which offered O(n) insertion and removal running time
643 but did not generate or require handles for untimeout operations.