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.
376 Align the timeouts, if possible, to
382 .Fn callout_reset_curcpu
384 .Fn callout_schedule_curcpu
388 .Fn callout_schedule_on
389 using the current CPU as the target CPU.
392 .Fn callout_pending ,
395 .Fn callout_deactivate
396 provide access to the current state of the callout.
397 Careful use of these macros can avoid many of the race conditions
398 that are inherent in asynchronous timer facilities; see
399 .Sx "Avoiding Race Conditions"
400 below for further details.
403 macro checks whether a callout is
405 a callout is considered
407 when a timeout has been set but the time has not yet arrived.
408 Note that once the timeout time arrives and the callout subsystem
409 starts to process this callout,
413 even though the callout function may not have finished (or even begun)
417 macro checks whether a callout is marked as
420 .Fn callout_deactivate
421 macro clears the callout's
424 The callout subsystem marks a callout as
426 when a timeout is set and it clears the
434 clear it when a callout expires normally via the execution of the
436 .Ss "Avoiding Race Conditions"
437 The callout subsystem invokes callout functions from its own timer
439 Without some kind of synchronization it is possible that a callout
440 function will be invoked concurrently with an attempt to stop or reset
441 the callout by another thread.
442 In particular, since callout functions typically acquire a mutex as
443 their first action, the callout function may have already been invoked,
444 but be blocked waiting for that mutex at the time that another thread
445 tries to reset or stop the callout.
447 The callout subsystem provides a number of mechanisms to address these
448 synchronization concerns:
449 .Bl -enum -offset indent
451 If the callout has an associated mutex that was specified using the
453 function (or implicitly specified as the
461 then this mutex is used to avoid the race conditions.
462 The associated mutex must be acquired by the caller before calling
466 and it is guaranteed that the callout will be correctly stopped
467 or reset as expected.
468 Note that it is still necessary to use
470 before destroying the callout or its associated mutex.
472 The return value from
476 indicates whether or not the callout was removed.
477 If it is known that the callout was set and the callout function has
478 not yet executed, then a return value of
480 indicates that the callout function is about to be called.
482 .Bd -literal -offset indent
483 if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) {
484 if (callout_stop(&sc->sc_callout)) {
485 sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING;
486 /* successfully stopped */
489 * callout has expired and callout
490 * function is about to be executed
497 .Fn callout_pending ,
500 .Fn callout_deactivate
501 macros can be used together to work around the race conditions.
502 When a callout's timeout is set, the callout subsystem marks the
507 When the timeout time arrives, the callout subsystem begins processing
508 the callout by first clearing the
511 It then invokes the callout function without changing the
513 flag, and does not clear the
515 flag even after the callout function returns.
516 The mechanism described here requires the callout function itself to
520 .Fn callout_deactivate
526 functions always clear both the
530 flags before returning.
532 The callout function should first check the
534 flag and return without action if
538 This indicates that the callout was rescheduled using
540 just before the callout function was invoked.
545 then the callout function should also return without action.
546 This indicates that the callout has been stopped.
547 Finally, the callout function should call
548 .Fn callout_deactivate
553 .Bd -literal -offset indent
554 mtx_lock(&sc->sc_mtx);
555 if (callout_pending(&sc->sc_callout)) {
556 /* callout was reset */
557 mtx_unlock(&sc->sc_mtx);
560 if (!callout_active(&sc->sc_callout)) {
561 /* callout was stopped */
562 mtx_unlock(&sc->sc_mtx);
565 callout_deactivate(&sc->sc_callout);
566 /* rest of callout function */
569 Together with appropriate synchronization, such as the mutex used above,
570 this approach permits the
574 functions to be used at any time without races.
576 .Bd -literal -offset indent
577 mtx_lock(&sc->sc_mtx);
578 callout_stop(&sc->sc_callout);
579 /* The callout is effectively stopped now. */
582 If the callout is still pending then these functions operate normally,
583 but if processing of the callout has already begun then the tests in
584 the callout function cause it to return without further action.
585 Synchronization between the callout function and other code ensures that
586 stopping or resetting the callout will never be attempted while the
587 callout function is past the
588 .Fn callout_deactivate
591 The above technique additionally ensures that the
593 flag always reflects whether the callout is effectively enabled or
597 returns false, then the callout is effectively disabled, since even if
598 the callout subsystem is actually just about to invoke the callout
599 function, the callout function will return without action.
602 There is one final race condition that must be considered when a
603 callout is being stopped for the last time.
604 In this case it may not be safe to let the callout function itself
605 detect that the callout was stopped, since it may need to access
606 data objects that have already been destroyed or recycled.
607 To ensure that the callout is completely finished, a call to
614 .Ft struct callout_handle
615 that can be passed to
621 functions return non-zero if the callout was still pending when it was
622 called or zero otherwise.
624 The current timeout and untimeout routines are based on the work of
627 .An George Varghese ,
628 published in a technical report entitled
629 .%T "Redesigning the BSD Callout and Timer Facilities"
630 and modified slightly for inclusion in
633 .An Justin T. Gibbs .
634 The original work on the data structures used in this implementation
640 .%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility"
642 .%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" .
643 The current implementation replaces the long standing
646 callout mechanism which offered O(n) insertion and removal running time
647 but did not generate or require handles for untimeout operations.