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"
106 .Fn callout_deactivate "struct callout *c"
110 schedules a call to the function given by the argument
115 Non-positive values of
117 are silently converted to the value
120 should be a pointer to a function that takes a
127 as its only argument.
128 The return value from
131 .Ft struct callout_handle
132 which can be used in conjunction with the
134 function to request that a scheduled timeout be canceled.
137 call is the old style and new code should use the
142 .Fn callout_handle_init
143 can be used to initialize a handle to a state which will cause
146 with that handle to return with no side
149 Assigning a callout handle the value of
150 .Fn CALLOUT_HANDLE_INITIALIZER
151 performs the same function as
152 .Fn callout_handle_init
153 and is provided for use on statically declared or global callout handles.
157 cancels the timeout associated with
163 arguments to validate the handle.
164 If the handle does not correspond to a timeout with
171 must be initialized by a previous call to
173 .Fn callout_handle_init ,
174 or assigned the value of
175 .Fn CALLOUT_HANDLE_INITIALIZER "&handle"
176 before being passed to
178 The behavior of calling
180 with an uninitialized handle
184 call is the old style and new code should use the
188 As handles are recycled by the system, it is possible (although unlikely)
189 that a handle from one invocation of
191 may match the handle of another invocation of
193 if both calls used the same function pointer and argument, and the first
194 timeout is expired or canceled before the second call.
195 The timeout facility offers O(1) running time for
199 Timeouts are executed from
204 Thus they are protected from re-entrancy.
208 .Fn callout_init_mtx ,
209 .Fn callout_init_rm ,
210 .Fn callout_init_rw ,
216 are low-level routines for clients who wish to allocate their own
221 initializes a callout so it can be passed to
227 without any side effects.
231 the callout structure is not considered to be
232 .Dq multi-processor safe ;
234 the Giant lock will be acquired before calling the callout function,
235 and released when the callout function returns.
239 function may be used as an alternative to
243 specifies a mutex that is to be acquired by the callout subsystem
244 before calling the callout function, and released when the callout
249 .Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED"
250 .It Dv CALLOUT_RETURNUNLOCKED
251 The callout function will release
253 itself, so the callout subsystem should not attempt to unlock it
254 after the callout function returns.
261 fuctions serve the need of using rwlocks and rmlocks in conjunction
263 The functions do the same as
265 with the possibility of specifying an extra
272 argument is specified, the lock should be created without passing the
275 The usable lock classes are currently limited to mutexes, rwlocks and
276 non-sleepable rmlocks, because callout handlers run in softclock swi,
277 so they cannot sleep nor acquire sleepable locks like sx or lockmgr.
281 .Bl -tag -width ".Dv CALLOUT_SHAREDLOCK"
282 .It Dv CALLOUT_SHAREDLOCK
283 The lock is only acquired in read mode when running the callout handler.
284 It has no effects when used in conjunction with
290 cancels a callout if it is currently pending.
291 If the callout is pending, then
293 will return a non-zero value.
294 If the callout is not set, has already been serviced or is currently
295 being serviced, then zero will be returned.
296 If the callout has an associated mutex, then that mutex must be
297 held when this function is called.
303 except that it will wait for the callout to be completed if it is
305 This function MUST NOT be called while holding any
306 locks on which the callout might block, or deadlock will result.
307 Note that if the callout subsystem has already begun processing this
308 callout, then the callout function may be invoked during the execution of
310 However, the callout subsystem does guarantee that the callout will be
317 first performs the equivalent of
319 to disestablish the callout, and then establishes a new callout in the
322 If there was already a pending callout and it was rescheduled, then
324 will return a non-zero value.
325 If the callout has an associated mutex, then that mutex must be
326 held when this function is called.
329 (re)schedules an existing callout for a new period of time;
330 it is equivalent to calling
336 parameters extracted from the callout structure (though possibly with
342 .Fn callout_schedule_on
347 but take an extra parameter specifying the target CPU for the callout.
350 .Fn callout_reset_sbt_on
351 allows to get higher time resolution, taking relative or absolute time
352 and precision instead of relative ticks count.
353 If specified time is in past, it will be silently converted to present
354 to run handler as soon as possible.
359 .Bl -tag -width ".Dv C_DIRECT_EXEC"
363 argument as absolute time of the event since boot, or relative time otherwise.
365 Run handler directly from hardware interrupt context instead of softclock swi.
366 It is faster, but puts more constraints on handlers.
367 Handlers may use only spin mutexes for locking, and they must be fast because
368 they run with absolute priority.
370 Specifies relative event time precision as binary logarithm of time interval
371 divided by acceptable time deviation: 1 -- 1/2, 2 -- 1/4, etc.
372 Smaller value allows to aggregate more events in one timer interrupt to
373 reduce processing overhead and power consumption.
377 .Fn callout_reset_curcpu
379 .Fn callout_schedule_curcpu
383 .Fn callout_schedule_on
384 using the current CPU as the target CPU.
387 .Fn callout_pending ,
390 .Fn callout_deactivate
391 provide access to the current state of the callout.
392 Careful use of these macros can avoid many of the race conditions
393 that are inherent in asynchronous timer facilities; see
394 .Sx "Avoiding Race Conditions"
395 below for further details.
398 macro checks whether a callout is
400 a callout is considered
402 when a timeout has been set but the time has not yet arrived.
403 Note that once the timeout time arrives and the callout subsystem
404 starts to process this callout,
408 even though the callout function may not have finished (or even begun)
412 macro checks whether a callout is marked as
415 .Fn callout_deactivate
416 macro clears the callout's
419 The callout subsystem marks a callout as
421 when a timeout is set and it clears the
429 clear it when a callout expires normally via the execution of the
431 .Ss "Avoiding Race Conditions"
432 The callout subsystem invokes callout functions from its own timer
434 Without some kind of synchronization it is possible that a callout
435 function will be invoked concurrently with an attempt to stop or reset
436 the callout by another thread.
437 In particular, since callout functions typically acquire a mutex as
438 their first action, the callout function may have already been invoked,
439 but be blocked waiting for that mutex at the time that another thread
440 tries to reset or stop the callout.
442 The callout subsystem provides a number of mechanisms to address these
443 synchronization concerns:
444 .Bl -enum -offset indent
446 If the callout has an associated mutex that was specified using the
448 function (or implicitly specified as the
456 then this mutex is used to avoid the race conditions.
457 The associated mutex must be acquired by the caller before calling
461 and it is guaranteed that the callout will be correctly stopped
462 or reset as expected.
463 Note that it is still necessary to use
465 before destroying the callout or its associated mutex.
467 The return value from
471 indicates whether or not the callout was removed.
472 If it is known that the callout was set and the callout function has
473 not yet executed, then a return value of
475 indicates that the callout function is about to be called.
477 .Bd -literal -offset indent
478 if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) {
479 if (callout_stop(&sc->sc_callout)) {
480 sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING;
481 /* successfully stopped */
484 * callout has expired and callout
485 * function is about to be executed
492 .Fn callout_pending ,
495 .Fn callout_deactivate
496 macros can be used together to work around the race conditions.
497 When a callout's timeout is set, the callout subsystem marks the
502 When the timeout time arrives, the callout subsystem begins processing
503 the callout by first clearing the
506 It then invokes the callout function without changing the
508 flag, and does not clear the
510 flag even after the callout function returns.
511 The mechanism described here requires the callout function itself to
515 .Fn callout_deactivate
521 functions always clear both the
525 flags before returning.
527 The callout function should first check the
529 flag and return without action if
533 This indicates that the callout was rescheduled using
535 just before the callout function was invoked.
540 then the callout function should also return without action.
541 This indicates that the callout has been stopped.
542 Finally, the callout function should call
543 .Fn callout_deactivate
548 .Bd -literal -offset indent
549 mtx_lock(&sc->sc_mtx);
550 if (callout_pending(&sc->sc_callout)) {
551 /* callout was reset */
552 mtx_unlock(&sc->sc_mtx);
555 if (!callout_active(&sc->sc_callout)) {
556 /* callout was stopped */
557 mtx_unlock(&sc->sc_mtx);
560 callout_deactivate(&sc->sc_callout);
561 /* rest of callout function */
564 Together with appropriate synchronization, such as the mutex used above,
565 this approach permits the
569 functions to be used at any time without races.
571 .Bd -literal -offset indent
572 mtx_lock(&sc->sc_mtx);
573 callout_stop(&sc->sc_callout);
574 /* The callout is effectively stopped now. */
577 If the callout is still pending then these functions operate normally,
578 but if processing of the callout has already begun then the tests in
579 the callout function cause it to return without further action.
580 Synchronization between the callout function and other code ensures that
581 stopping or resetting the callout will never be attempted while the
582 callout function is past the
583 .Fn callout_deactivate
586 The above technique additionally ensures that the
588 flag always reflects whether the callout is effectively enabled or
592 returns false, then the callout is effectively disabled, since even if
593 the callout subsystem is actually just about to invoke the callout
594 function, the callout function will return without action.
597 There is one final race condition that must be considered when a
598 callout is being stopped for the last time.
599 In this case it may not be safe to let the callout function itself
600 detect that the callout was stopped, since it may need to access
601 data objects that have already been destroyed or recycled.
602 To ensure that the callout is completely finished, a call to
609 .Ft struct callout_handle
610 that can be passed to
616 functions return non-zero if the callout was still pending when it was
617 called or zero otherwise.
619 The current timeout and untimeout routines are based on the work of
622 .An George Varghese ,
623 published in a technical report entitled
624 .%T "Redesigning the BSD Callout and Timer Facilities"
625 and modified slightly for inclusion in
628 .An Justin T. Gibbs .
629 The original work on the data structures used in this implementation
635 .%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility"
637 .%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" .
638 The current implementation replaces the long standing
641 callout mechanism which offered O(n) insertion and removal running time
642 but did not generate or require handles for untimeout operations.