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.
32 .Dd September 14, 2015
37 .Nm callout_deactivate ,
38 .Nm callout_async_drain ,
40 .Nm callout_handle_init ,
42 .Nm callout_init_mtx ,
47 .Nm callout_reset_curcpu ,
48 .Nm callout_reset_on ,
49 .Nm callout_reset_sbt ,
50 .Nm callout_reset_sbt_curcpu ,
51 .Nm callout_reset_sbt_on ,
52 .Nm callout_schedule ,
53 .Nm callout_schedule_curcpu ,
54 .Nm callout_schedule_on ,
55 .Nm callout_schedule_sbt ,
56 .Nm callout_schedule_sbt_curcpu ,
57 .Nm callout_schedule_sbt_on ,
61 .Nd execute a function after a specified length of time
66 typedef void timeout_t (void *);
69 .Fn callout_active "struct callout *c"
71 .Fn callout_deactivate "struct callout *c"
73 .Fn callout_async_drain "struct callout *c" "timeout_t *drain"
75 .Fn callout_drain "struct callout *c"
77 .Fn callout_handle_init "struct callout_handle *handle"
79 struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle);
82 .Fn callout_init "struct callout *c" "int mpsafe"
84 .Fn callout_init_mtx "struct callout *c" "struct mtx *mtx" "int flags"
86 .Fn callout_init_rm "struct callout *c" "struct rmlock *rm" "int flags"
88 .Fn callout_init_rw "struct callout *c" "struct rwlock *rw" "int flags"
90 .Fn callout_pending "struct callout *c"
92 .Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg"
94 .Fn callout_reset_curcpu "struct callout *c" "int ticks" "timeout_t *func" \
97 .Fn callout_reset_on "struct callout *c" "int ticks" "timeout_t *func" \
100 .Fn callout_reset_sbt "struct callout *c" "sbintime_t sbt" \
101 "sbintime_t pr" "timeout_t *func" "void *arg" "int flags"
103 .Fn callout_reset_sbt_curcpu "struct callout *c" "sbintime_t sbt" \
104 "sbintime_t pr" "timeout_t *func" "void *arg" "int flags"
106 .Fn callout_reset_sbt_on "struct callout *c" "sbintime_t sbt" \
107 "sbintime_t pr" "timeout_t *func" "void *arg" "int cpu" "int flags"
109 .Fn callout_schedule "struct callout *c" "int ticks"
111 .Fn callout_schedule_curcpu "struct callout *c" "int ticks"
113 .Fn callout_schedule_on "struct callout *c" "int ticks" "int cpu"
115 .Fn callout_schedule_sbt "struct callout *c" "sbintime_t sbt" \
116 "sbintime_t pr" "int flags"
118 .Fn callout_schedule_sbt_curcpu "struct callout *c" "sbintime_t sbt" \
119 "sbintime_t pr" "int flags"
121 .Fn callout_schedule_sbt_on "struct callout *c" "sbintime_t sbt" \
122 "sbintime_t pr" "int cpu" "int flags"
124 .Fn callout_stop "struct callout *c"
125 .Ft struct callout_handle
126 .Fn timeout "timeout_t *func" "void *arg" "int ticks"
128 .Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle"
132 API is used to schedule a call to an arbitrary function at a specific
134 Consumers of this API are required to allocate a callout structure
136 for each pending function invocation.
137 This structure stores state about the pending function invocation including
138 the function to be called and the time at which the function should be invoked.
139 Pending function calls can be cancelled or rescheduled to a different time.
141 a callout structure may be reused to schedule a new function call after a
142 scheduled call is completed.
144 Callouts only provide a single-shot mode.
145 If a consumer requires a periodic timer,
146 it must explicitly reschedule each function call.
147 This is normally done by rescheduling the subsequent call within the called
150 Callout functions must not sleep.
151 They may not acquire sleepable locks,
152 wait on condition variables,
153 perform blocking allocation requests,
154 or invoke any other action that might sleep.
156 Each callout structure must be initialized by
158 .Fn callout_init_mtx ,
159 .Fn callout_init_rm ,
162 before it is passed to any of the other callout functions.
165 function initializes a callout structure in
167 that is not associated with a specific lock.
171 the callout structure is not considered to be
172 .Dq multi-processor safe ;
173 and the Giant lock will be acquired before calling the callout function
174 and released when the callout function returns.
177 .Fn callout_init_mtx ,
178 .Fn callout_init_rm ,
181 functions initialize a callout structure in
183 that is associated with a specific lock.
184 The lock is specified by the
190 The associated lock must be held while stopping or rescheduling the
192 The callout subsystem acquires the associated lock before calling the
193 callout function and releases it after the function returns.
194 If the callout was cancelled while the callout subsystem waited for the
196 the callout function is not called,
197 and the associated lock is released.
198 This ensures that stopping or rescheduling the callout will abort any
199 previously scheduled invocation.
201 Only regular mutexes may be used with
202 .Fn callout_init_mtx ;
203 spin mutexes are not supported.
204 A sleepable read-mostly lock
206 one initialized with the
211 .Fn callout_init_rm .
212 Similarly, other sleepable lock types such as
216 cannot be used with callouts because sleeping is not permitted in
217 the callout subsystem.
222 .Fn callout_init_mtx ,
223 .Fn callout_init_rm ,
225 .Fn callout_init_rw :
226 .Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED"
227 .It Dv CALLOUT_RETURNUNLOCKED
228 The callout function will release the associated lock itself,
229 so the callout subsystem should not attempt to unlock it
230 after the callout function returns.
231 .It Dv CALLOUT_SHAREDLOCK
232 The lock is only acquired in read mode when running the callout handler.
233 This flag is ignored by
234 .Fn callout_init_mtx .
241 if it is currently pending.
242 If the callout is pending and successfully stopped, then
244 returns a value of one.
245 If the callout is not set, or
246 has already been serviced, then
247 negative one is returned.
248 If the callout is currently being serviced and cannot be stopped,
249 then zero will be returned.
250 If the callout has an associated lock,
251 then that lock must be held when this function is called.
254 .Fn callout_async_drain
259 .Fn callout_async_drain
260 returns zero it will arrange for the function
262 to be called using the same argument given to the
265 .Fn callout_async_drain
266 If the callout has an associated lock,
267 then that lock must be held when this function is called.
268 Note that when stopping multiple callouts that use the same lock it is possible
269 to get multiple return's of zero and multiple calls to the
271 function, depending upon which CPU's the callouts are running. The
273 function itself is called from the context of the completing callout
274 i.e. softclock or hardclock, just like a callout itself.
281 except that it will wait for the callout
283 to complete if it is already in progress.
284 This function MUST NOT be called while holding any
285 locks on which the callout might block, or deadlock will result.
286 Note that if the callout subsystem has already begun processing this
287 callout, then the callout function may be invoked before
290 However, the callout subsystem does guarantee that the callout will be
299 function families schedule a future function invocation for callout
303 already has a pending callout,
304 it is cancelled before the new invocation is scheduled.
305 These functions return a value of one if a pending callout was cancelled
306 and zero if there was no pending callout.
307 If the callout has an associated lock,
308 then that lock must be held when any of these functions are called.
310 The time at which the callout function will be invoked is determined by
322 the callout is scheduled to execute after
325 Non-positive values of
327 are silently converted to the value
335 arguments provide more control over the scheduled time including
336 support for higher resolution times,
337 specifying the precision of the scheduled time,
338 and setting an absolute deadline instead of a relative timeout.
339 The callout is scheduled to execute in a time window which begins at
340 the time specified in
342 and extends for the amount of time specified in
346 specifies a time in the past,
347 the window is adjusted to start at the current time.
350 allows the callout subsystem to coalesce callouts scheduled close to each
351 other into fewer timer interrupts,
352 reducing processing overhead and power consumption.
355 may be specified to adjust the interpretation of
359 .Bl -tag -width ".Dv C_DIRECT_EXEC"
363 argument as an absolute time since boot.
366 is treated as a relative amount of time,
370 Run the handler directly from hardware interrupt context instead of from the
372 This reduces latency and overhead, but puts more constraints on the callout
374 Callout functions run in this context may use only spin mutexes for locking
375 and should be as small as possible because they run with absolute priority.
377 Specifies relative event time precision as binary logarithm of time interval
378 divided by acceptable time deviation: 1 -- 1/2, 2 -- 1/4, etc.
379 Note that the larger of
381 or this value is used as the length of the time window.
383 .Pq which result in larger time intervals
384 allow the callout subsystem to aggregate more events in one timer interrupt.
386 Align the timeouts to
395 argument which identifies the function to be called when the time expires.
396 It must be a pointer to a function that takes a single
403 as its only argument.
410 arguments from the previous callout.
413 functions must always be called to initialize
419 functions can be used.
421 The callout subsystem provides a softclock thread for each CPU in the system.
422 Callouts are assigned to a single CPU and are executed by the softclock thread
425 callouts are assigned to CPU 0.
427 .Fn callout_reset_on ,
428 .Fn callout_reset_sbt_on ,
429 .Fn callout_schedule_on
431 .Fn callout_schedule_sbt_on
432 functions assign the callout to CPU
435 .Fn callout_reset_curcpu ,
436 .Fn callout_reset_sbt_curpu ,
437 .Fn callout_schedule_curcpu
439 .Fn callout_schedule_sbt_curcpu
440 functions assign the callout to the current CPU.
443 .Fn callout_reset_sbt ,
446 .Fn callout_schedule_sbt
447 functions schedule the callout to execute in the softclock thread of the CPU
448 to which it is currently assigned.
450 Softclock threads are not pinned to their respective CPUs by default.
451 The softclock thread for CPU 0 can be pinned to CPU 0 by setting the
452 .Va kern.pin_default_swi
453 loader tunable to a non-zero value.
454 Softclock threads for CPUs other than zero can be pinned to their
455 respective CPUs by setting the
456 .Va kern.pin_pcpu_swi
457 loader tunable to a non-zero value.
460 .Fn callout_pending ,
463 .Fn callout_deactivate
464 provide access to the current state of the callout.
467 macro checks whether a callout is
469 a callout is considered
471 when a timeout has been set but the time has not yet arrived.
472 Note that once the timeout time arrives and the callout subsystem
473 starts to process this callout,
477 even though the callout function may not have finished
482 macro checks whether a callout is marked as
485 .Fn callout_deactivate
486 macro clears the callout's
489 The callout subsystem marks a callout as
491 when a timeout is set and it clears the
499 clear it when a callout expires normally via the execution of the
501 .Ss "Avoiding Race Conditions"
502 The callout subsystem invokes callout functions from its own thread
504 Without some kind of synchronization,
505 it is possible that a callout
506 function will be invoked concurrently with an attempt to stop or reset
507 the callout by another thread.
508 In particular, since callout functions typically acquire a lock as
509 their first action, the callout function may have already been invoked,
510 but is blocked waiting for that lock at the time that another thread
511 tries to reset or stop the callout.
513 There are three main techniques for addressing these
514 synchronization concerns.
515 The first approach is preferred as it is the simplest:
516 .Bl -enum -offset indent
518 Callouts can be associated with a specific lock when they are initialized
520 .Fn callout_init_mtx ,
521 .Fn callout_init_rm ,
523 .Fn callout_init_rw .
524 When a callout is associated with a lock,
525 the callout subsystem acquires the lock before the callout function is
527 This allows the callout subsystem to transparently handle races between
528 callout cancellation,
531 Note that the associated lock must be acquired before calling
537 functions to provide this safety.
539 A callout initialized via
543 set to zero is implicitly associated with the
548 is held when cancelling or rescheduling the callout,
549 then its use will prevent races with the callout function.
551 The return value from
560 indicates whether or not the callout was removed.
561 If it is known that the callout was set and the callout function has
562 not yet executed, then a return value of
564 indicates that the callout function is about to be called.
566 .Bd -literal -offset indent
567 if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) {
568 if (callout_stop(&sc->sc_callout)) {
569 sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING;
570 /* successfully stopped */
573 * callout has expired and callout
574 * function is about to be executed
581 .Fn callout_pending ,
584 .Fn callout_deactivate
585 macros can be used together to work around the race conditions.
586 When a callout's timeout is set, the callout subsystem marks the
591 When the timeout time arrives, the callout subsystem begins processing
592 the callout by first clearing the
595 It then invokes the callout function without changing the
597 flag, and does not clear the
599 flag even after the callout function returns.
600 The mechanism described here requires the callout function itself to
604 .Fn callout_deactivate
610 functions always clear both the
614 flags before returning.
616 The callout function should first check the
618 flag and return without action if
622 This indicates that the callout was rescheduled using
624 just before the callout function was invoked.
629 then the callout function should also return without action.
630 This indicates that the callout has been stopped.
631 Finally, the callout function should call
632 .Fn callout_deactivate
637 .Bd -literal -offset indent
638 mtx_lock(&sc->sc_mtx);
639 if (callout_pending(&sc->sc_callout)) {
640 /* callout was reset */
641 mtx_unlock(&sc->sc_mtx);
644 if (!callout_active(&sc->sc_callout)) {
645 /* callout was stopped */
646 mtx_unlock(&sc->sc_mtx);
649 callout_deactivate(&sc->sc_callout);
650 /* rest of callout function */
653 Together with appropriate synchronization, such as the mutex used above,
654 this approach permits the
658 functions to be used at any time without races.
660 .Bd -literal -offset indent
661 mtx_lock(&sc->sc_mtx);
662 callout_stop(&sc->sc_callout);
663 /* The callout is effectively stopped now. */
666 If the callout is still pending then these functions operate normally,
667 but if processing of the callout has already begun then the tests in
668 the callout function cause it to return without further action.
669 Synchronization between the callout function and other code ensures that
670 stopping or resetting the callout will never be attempted while the
671 callout function is past the
672 .Fn callout_deactivate
675 The above technique additionally ensures that the
677 flag always reflects whether the callout is effectively enabled or
681 returns false, then the callout is effectively disabled, since even if
682 the callout subsystem is actually just about to invoke the callout
683 function, the callout function will return without action.
686 There is one final race condition that must be considered when a
687 callout is being stopped for the last time.
688 In this case it may not be safe to let the callout function itself
689 detect that the callout was stopped, since it may need to access
690 data objects that have already been destroyed or recycled.
691 To ensure that the callout is completely finished, a call to
695 a callout should always be drained prior to destroying its associated lock
696 or releasing the storage for the callout structure.
699 The functions below are a legacy API that will be removed in a future release.
700 New code should not use these routines.
705 schedules a call to the function given by the argument
710 Non-positive values of
712 are silently converted to the value
715 should be a pointer to a function that takes a
722 as its only argument.
723 The return value from
726 .Ft struct callout_handle
727 which can be used in conjunction with the
729 function to request that a scheduled timeout be canceled.
732 .Fn callout_handle_init
733 can be used to initialize a handle to a state which will cause
736 with that handle to return with no side
739 Assigning a callout handle the value of
740 .Fn CALLOUT_HANDLE_INITIALIZER
741 performs the same function as
742 .Fn callout_handle_init
743 and is provided for use on statically declared or global callout handles.
747 cancels the timeout associated with
753 arguments to validate the handle.
754 If the handle does not correspond to a timeout with
761 must be initialized by a previous call to
763 .Fn callout_handle_init ,
764 or assigned the value of
765 .Fn CALLOUT_HANDLE_INITIALIZER "&handle"
766 before being passed to
768 The behavior of calling
770 with an uninitialized handle
773 As handles are recycled by the system, it is possible (although unlikely)
774 that a handle from one invocation of
776 may match the handle of another invocation of
778 if both calls used the same function pointer and argument, and the first
779 timeout is expired or canceled before the second call.
780 The timeout facility offers O(1) running time for
784 Timeouts are executed from
789 Thus they are protected from re-entrancy.
793 macro returns the state of a callout's
799 macro returns the state of a callout's
807 function families return a value of one if the callout was pending before the new
808 function invocation was scheduled.
814 functions return a value of one if the callout was still pending when it was
815 called, a zero if the callout could not be stopped and a negative one is it
816 was either not running or haas already completed. The
819 .Ft struct callout_handle
820 that can be passed to
823 The current timeout and untimeout routines are based on the work of
826 .An George Varghese ,
827 published in a technical report entitled
828 .%T "Redesigning the BSD Callout and Timer Facilities"
829 and modified slightly for inclusion in
832 .An Justin T. Gibbs .
833 The original work on the data structures used in this implementation
839 .%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility"
841 .%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" .
842 The current implementation replaces the long standing
845 callout mechanism which offered O(n) insertion and removal running time
846 but did not generate or require handles for untimeout operations.