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.
37 .Nm callout_deactivate ,
39 .Nm callout_handle_init ,
41 .Nm callout_init_mtx ,
46 .Nm callout_reset_curcpu ,
47 .Nm callout_reset_on ,
48 .Nm callout_reset_sbt ,
49 .Nm callout_reset_sbt_curcpu ,
50 .Nm callout_reset_sbt_on ,
51 .Nm callout_schedule ,
52 .Nm callout_schedule_curcpu ,
53 .Nm callout_schedule_on ,
57 .Nd execute a function after a specified length of time
62 typedef void timeout_t (void *);
65 .Fn callout_active "struct callout *c"
67 .Fn callout_deactivate "struct callout *c"
69 .Fn callout_drain "struct callout *c"
71 .Fn callout_handle_init "struct callout_handle *handle"
73 struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle);
76 .Fn callout_init "struct callout *c" "int mpsafe"
78 .Fn callout_init_mtx "struct callout *c" "struct mtx *mtx" "int flags"
80 .Fn callout_init_rm "struct callout *c" "struct rmlock *rm" "int flags"
82 .Fn callout_init_rw "struct callout *c" "struct rwlock *rw" "int flags"
84 .Fn callout_pending "struct callout *c"
86 .Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg"
88 .Fn callout_reset_curcpu "struct callout *c" "int ticks" "timeout_t *func" \
91 .Fn callout_reset_on "struct callout *c" "int ticks" "timeout_t *func" \
94 .Fn callout_reset_sbt "struct callout *c" "sbintime_t sbt" \
95 "sbintime_t pr" "timeout_t *func" "void *arg" "int flags"
97 .Fn callout_reset_sbt_curcpu "struct callout *c" "sbintime_t sbt" \
98 "sbintime_t pr" "timeout_t *func" "void *arg" "int flags"
100 .Fn callout_reset_sbt_on "struct callout *c" "sbintime_t sbt" \
101 "sbintime_t pr" "timeout_t *func" "void *arg" "int cpu" "int flags"
103 .Fn callout_schedule "struct callout *c" "int ticks"
105 .Fn callout_schedule_curcpu "struct callout *c" "int ticks"
107 .Fn callout_schedule_on "struct callout *c" "int ticks" "int cpu"
109 .Fn callout_stop "struct callout *c"
110 .Ft struct callout_handle
111 .Fn timeout "timeout_t *func" "void *arg" "int ticks"
113 .Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle"
117 API is used to schedule a call to an arbitrary function at a specific
119 Consumers of this API are required to allocate a callout structure
121 for each pending function invocation.
122 This structure stores state about the pending function invocation including
123 the function to be called and the time at which the function should be invoked.
124 Pending function calls can be cancelled or rescheduled to a different time.
126 a callout structure may be reused to schedule a new function call after a
127 scheduled call is completed.
129 Callouts only provide a single-shot mode.
130 If a consumer requires a periodic timer,
131 it must explicitly reschedule each function call.
132 This is normally done by rescheduling the subsequent call within the called
135 Callout functions must not sleep.
136 They may not acquire sleepable locks,
137 wait on condition variables,
138 perform blocking allocation requests,
139 or invoke any other action that might sleep.
141 Each callout structure must be initialized by
143 .Fn callout_init_mtx ,
144 .Fn callout_init_rm ,
147 before it is passed to any of the other callout functions.
150 function initializes a callout structure in
152 that is not associated with a specific lock.
156 the callout structure is not considered to be
157 .Dq multi-processor safe ;
158 and the Giant lock will be acquired before calling the callout function
159 and released when the callout function returns.
162 .Fn callout_init_mtx ,
163 .Fn callout_init_rm ,
166 functions initialize a callout structure in
168 that is associated with a specific lock.
169 The lock is specified by the
175 The associated lock must be held while stopping or rescheduling the
177 The callout subsystem acquires the associated lock before calling the
178 callout function and releases it after the function returns.
179 If the callout was cancelled while the callout subsystem waited for the
181 the callout function is not called,
182 and the associated lock is released.
183 This ensures that stopping or rescheduling the callout will abort any
184 previously scheduled invocation.
186 Only regular mutexes may be used with
187 .Fn callout_init_mtx ;
188 spin mutexes are not supported.
189 A sleepable read-mostly lock
191 one initialized with the
196 .Fn callout_init_rm .
197 Similarly, other sleepable lock types such as
201 cannot be used with callouts because sleeping is not permitted in
202 the callout subsystem.
207 .Fn callout_init_mtx ,
208 .Fn callout_init_rm ,
210 .Fn callout_init_rw :
211 .Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED"
212 .It Dv CALLOUT_RETURNUNLOCKED
213 The callout function will release the associated lock itself,
214 so the callout subsystem should not attempt to unlock it
215 after the callout function returns.
216 .It Dv CALLOUT_SHAREDLOCK
217 The lock is only acquired in read mode when running the callout handler.
218 This flag is ignored by
219 .Fn callout_init_mtx .
226 if it is currently pending.
227 If the callout is pending, then
229 returns a non-zero value.
230 If the callout is not set,
231 has already been serviced,
232 or is currently being serviced,
233 then zero will be returned.
234 If the callout has an associated lock,
235 then that lock must be held when this function is called.
241 except that it will wait for the callout
243 to complete if it is already in progress.
244 This function MUST NOT be called while holding any
245 locks on which the callout might block, or deadlock will result.
246 Note that if the callout subsystem has already begun processing this
247 callout, then the callout function may be invoked before
250 However, the callout subsystem does guarantee that the callout will be
259 function families schedule a future function invocation for callout
263 already has a pending callout,
264 it is cancelled before the new invocation is scheduled.
265 These functions return a non-zero value if a pending callout was cancelled
266 and zero if there was no pending callout.
267 If the callout has an associated lock,
268 then that lock must be held when any of these functions are called.
270 The time at which the callout function will be invoked is determined by
282 the callout is scheduled to execute after
285 Non-positive values of
287 are silently converted to the value
295 arguments provide more control over the scheduled time including
296 support for higher resolution times,
297 specifying the precision of the scheduled time,
298 and setting an absolute deadline instead of a relative timeout.
299 The callout is scheduled to execute in a time window which begins at
300 the time specified in
302 and extends for the amount of time specified in
306 specifies a time in the past,
307 the window is adjusted to start at the current time.
310 allows the callout subsystem to coalesce callouts scheduled close to each
311 other into fewer timer interrupts,
312 reducing processing overhead and power consumption.
315 may be specified to adjust the interpretation of
319 .Bl -tag -width ".Dv C_DIRECT_EXEC"
323 argument as an absolute time since boot.
326 is treated as a relative amount of time,
330 Run the handler directly from hardware interrupt context instead of from the
332 This reduces latency and overhead, but puts more constraints on the callout
334 Callout functions run in this context may use only spin mutexes for locking
335 and should be as small as possible because they run with absolute priority.
337 Specifies relative event time precision as binary logarithm of time interval
338 divided by acceptable time deviation: 1 -- 1/2, 2 -- 1/4, etc.
339 Note that the larger of
341 or this value is used as the length of the time window.
343 .Pq which result in larger time intervals
344 allow the callout subsystem to aggregate more events in one timer interrupt.
346 Align the timeouts to
355 argument which identifies the function to be called when the time expires.
356 It must be a pointer to a function that takes a single
363 as its only argument.
370 arguments from the previous callout.
373 functions must always be called to initialize
379 functions can be used.
381 The callout subsystem provides a softclock thread for each CPU in the system.
382 Callouts are assigned to a single CPU and are executed by the softclock thread
385 callouts are assigned to CPU 0.
387 .Fn callout_reset_on ,
388 .Fn callout_reset_sbt_on ,
390 .Fn callout_schedule_on
391 functions assign the callout to CPU
394 .Fn callout_reset_curcpu ,
395 .Fn callout_reset_sbt_curpu ,
397 .Fn callout_schedule_curcpu
398 functions assign the callout to the current CPU.
401 .Fn callout_reset_sbt ,
404 functions schedule the callout to execute in the softclock thread of the CPU
405 to which it is currently assigned.
407 Softclock threads are not pinned to their respective CPUs by default.
408 The softclock thread for CPU 0 can be pinned to CPU 0 by setting the
409 .Va kern.pin_default_swi
410 loader tunable to a non-zero value.
411 Softclock threads for CPUs other than zero can be pinned to their
412 respective CPUs by setting the
413 .Va kern.pin_pcpu_swi
414 loader tunable to a non-zero value.
417 .Fn callout_pending ,
420 .Fn callout_deactivate
421 provide access to the current state of the callout.
424 macro checks whether a callout is
426 a callout is considered
428 when a timeout has been set but the time has not yet arrived.
429 Note that once the timeout time arrives and the callout subsystem
430 starts to process this callout,
434 even though the callout function may not have finished
439 macro checks whether a callout is marked as
442 .Fn callout_deactivate
443 macro clears the callout's
446 The callout subsystem marks a callout as
448 when a timeout is set and it clears the
456 clear it when a callout expires normally via the execution of the
458 .Ss "Avoiding Race Conditions"
459 The callout subsystem invokes callout functions from its own thread
461 Without some kind of synchronization,
462 it is possible that a callout
463 function will be invoked concurrently with an attempt to stop or reset
464 the callout by another thread.
465 In particular, since callout functions typically acquire a lock as
466 their first action, the callout function may have already been invoked,
467 but is blocked waiting for that lock at the time that another thread
468 tries to reset or stop the callout.
470 There are three main techniques for addressing these
471 synchronization concerns.
472 The first approach is preferred as it is the simplest:
473 .Bl -enum -offset indent
475 Callouts can be associated with a specific lock when they are initialized
477 .Fn callout_init_mtx ,
478 .Fn callout_init_rm ,
480 .Fn callout_init_rw .
481 When a callout is associated with a lock,
482 the callout subsystem acquires the lock before the callout function is
484 This allows the callout subsystem to transparently handle races between
485 callout cancellation,
488 Note that the associated lock must be acquired before calling
494 functions to provide this safety.
496 A callout initialized via
500 set to zero is implicitly associated with the
505 is held when cancelling or rescheduling the callout,
506 then its use will prevent races with the callout function.
508 The return value from
517 indicates whether or not the callout was removed.
518 If it is known that the callout was set and the callout function has
519 not yet executed, then a return value of
521 indicates that the callout function is about to be called.
523 .Bd -literal -offset indent
524 if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) {
525 if (callout_stop(&sc->sc_callout)) {
526 sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING;
527 /* successfully stopped */
530 * callout has expired and callout
531 * function is about to be executed
538 .Fn callout_pending ,
541 .Fn callout_deactivate
542 macros can be used together to work around the race conditions.
543 When a callout's timeout is set, the callout subsystem marks the
548 When the timeout time arrives, the callout subsystem begins processing
549 the callout by first clearing the
552 It then invokes the callout function without changing the
554 flag, and does not clear the
556 flag even after the callout function returns.
557 The mechanism described here requires the callout function itself to
561 .Fn callout_deactivate
567 functions always clear both the
571 flags before returning.
573 The callout function should first check the
575 flag and return without action if
579 This indicates that the callout was rescheduled using
581 just before the callout function was invoked.
586 then the callout function should also return without action.
587 This indicates that the callout has been stopped.
588 Finally, the callout function should call
589 .Fn callout_deactivate
594 .Bd -literal -offset indent
595 mtx_lock(&sc->sc_mtx);
596 if (callout_pending(&sc->sc_callout)) {
597 /* callout was reset */
598 mtx_unlock(&sc->sc_mtx);
601 if (!callout_active(&sc->sc_callout)) {
602 /* callout was stopped */
603 mtx_unlock(&sc->sc_mtx);
606 callout_deactivate(&sc->sc_callout);
607 /* rest of callout function */
610 Together with appropriate synchronization, such as the mutex used above,
611 this approach permits the
615 functions to be used at any time without races.
617 .Bd -literal -offset indent
618 mtx_lock(&sc->sc_mtx);
619 callout_stop(&sc->sc_callout);
620 /* The callout is effectively stopped now. */
623 If the callout is still pending then these functions operate normally,
624 but if processing of the callout has already begun then the tests in
625 the callout function cause it to return without further action.
626 Synchronization between the callout function and other code ensures that
627 stopping or resetting the callout will never be attempted while the
628 callout function is past the
629 .Fn callout_deactivate
632 The above technique additionally ensures that the
634 flag always reflects whether the callout is effectively enabled or
638 returns false, then the callout is effectively disabled, since even if
639 the callout subsystem is actually just about to invoke the callout
640 function, the callout function will return without action.
643 There is one final race condition that must be considered when a
644 callout is being stopped for the last time.
645 In this case it may not be safe to let the callout function itself
646 detect that the callout was stopped, since it may need to access
647 data objects that have already been destroyed or recycled.
648 To ensure that the callout is completely finished, a call to
652 a callout should always be drained prior to destroying its associated lock
653 or releasing the storage for the callout structure.
656 The functions below are a legacy API that will be removed in a future release.
657 New code should not use these routines.
662 schedules a call to the function given by the argument
667 Non-positive values of
669 are silently converted to the value
672 should be a pointer to a function that takes a
679 as its only argument.
680 The return value from
683 .Ft struct callout_handle
684 which can be used in conjunction with the
686 function to request that a scheduled timeout be canceled.
689 .Fn callout_handle_init
690 can be used to initialize a handle to a state which will cause
693 with that handle to return with no side
696 Assigning a callout handle the value of
697 .Fn CALLOUT_HANDLE_INITIALIZER
698 performs the same function as
699 .Fn callout_handle_init
700 and is provided for use on statically declared or global callout handles.
704 cancels the timeout associated with
710 arguments to validate the handle.
711 If the handle does not correspond to a timeout with
718 must be initialized by a previous call to
720 .Fn callout_handle_init ,
721 or assigned the value of
722 .Fn CALLOUT_HANDLE_INITIALIZER "&handle"
723 before being passed to
725 The behavior of calling
727 with an uninitialized handle
730 As handles are recycled by the system, it is possible (although unlikely)
731 that a handle from one invocation of
733 may match the handle of another invocation of
735 if both calls used the same function pointer and argument, and the first
736 timeout is expired or canceled before the second call.
737 The timeout facility offers O(1) running time for
741 Timeouts are executed from
746 Thus they are protected from re-entrancy.
750 macro returns the state of a callout's
756 macro returns the state of a callout's
764 function families return non-zero if the callout was pending before the new
765 function invocation was scheduled.
771 functions return non-zero if the callout was still pending when it was
772 called or zero otherwise.
776 .Ft struct callout_handle
777 that can be passed to
780 The current timeout and untimeout routines are based on the work of
783 .An George Varghese ,
784 published in a technical report entitled
785 .%T "Redesigning the BSD Callout and Timer Facilities"
786 and modified slightly for inclusion in
789 .An Justin T. Gibbs .
790 The original work on the data structures used in this implementation
796 .%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility"
798 .%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" .
799 The current implementation replaces the long standing
802 callout mechanism which offered O(n) insertion and removal running time
803 but did not generate or require handles for untimeout operations.