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 ,
54 .Nm callout_schedule_sbt ,
55 .Nm callout_schedule_sbt_curcpu ,
56 .Nm callout_schedule_sbt_on ,
60 .Nd execute a function after a specified length of time
65 typedef void timeout_t (void *);
68 .Fn callout_active "struct callout *c"
70 .Fn callout_deactivate "struct callout *c"
72 .Fn callout_drain "struct callout *c"
74 .Fn callout_handle_init "struct callout_handle *handle"
76 struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle);
79 .Fn callout_init "struct callout *c" "int mpsafe"
81 .Fn callout_init_mtx "struct callout *c" "struct mtx *mtx" "int flags"
83 .Fn callout_init_rm "struct callout *c" "struct rmlock *rm" "int flags"
85 .Fn callout_init_rw "struct callout *c" "struct rwlock *rw" "int flags"
87 .Fn callout_pending "struct callout *c"
89 .Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg"
91 .Fn callout_reset_curcpu "struct callout *c" "int ticks" "timeout_t *func" \
94 .Fn callout_reset_on "struct callout *c" "int ticks" "timeout_t *func" \
97 .Fn callout_reset_sbt "struct callout *c" "sbintime_t sbt" \
98 "sbintime_t pr" "timeout_t *func" "void *arg" "int flags"
100 .Fn callout_reset_sbt_curcpu "struct callout *c" "sbintime_t sbt" \
101 "sbintime_t pr" "timeout_t *func" "void *arg" "int flags"
103 .Fn callout_reset_sbt_on "struct callout *c" "sbintime_t sbt" \
104 "sbintime_t pr" "timeout_t *func" "void *arg" "int cpu" "int flags"
106 .Fn callout_schedule "struct callout *c" "int ticks"
108 .Fn callout_schedule_curcpu "struct callout *c" "int ticks"
110 .Fn callout_schedule_on "struct callout *c" "int ticks" "int cpu"
112 .Fn callout_schedule_sbt "struct callout *c" "sbintime_t sbt" \
113 "sbintime_t pr" "int flags"
115 .Fn callout_schedule_sbt_curcpu "struct callout *c" "sbintime_t sbt" \
116 "sbintime_t pr" "int flags"
118 .Fn callout_schedule_sbt_on "struct callout *c" "sbintime_t sbt" \
119 "sbintime_t pr" "int cpu" "int flags"
121 .Fn callout_stop "struct callout *c"
122 .Ft struct callout_handle
123 .Fn timeout "timeout_t *func" "void *arg" "int ticks"
125 .Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle"
129 API is used to schedule a call to an arbitrary function at a specific
131 Consumers of this API are required to allocate a callout structure
133 for each pending function invocation.
134 This structure stores state about the pending function invocation including
135 the function to be called and the time at which the function should be invoked.
136 Pending function calls can be cancelled or rescheduled to a different time.
138 a callout structure may be reused to schedule a new function call after a
139 scheduled call is completed.
141 Callouts only provide a single-shot mode.
142 If a consumer requires a periodic timer,
143 it must explicitly reschedule each function call.
144 This is normally done by rescheduling the subsequent call within the called
147 Callout functions must not sleep.
148 They may not acquire sleepable locks,
149 wait on condition variables,
150 perform blocking allocation requests,
151 or invoke any other action that might sleep.
153 Each callout structure must be initialized by
155 .Fn callout_init_mtx ,
156 .Fn callout_init_rm ,
159 before it is passed to any of the other callout functions.
162 function initializes a callout structure in
164 that is not associated with a specific lock.
168 the callout structure is not considered to be
169 .Dq multi-processor safe ;
170 and the Giant lock will be acquired before calling the callout function
171 and released when the callout function returns.
174 .Fn callout_init_mtx ,
175 .Fn callout_init_rm ,
178 functions initialize a callout structure in
180 that is associated with a specific lock.
181 The lock is specified by the
187 The associated lock must be held while stopping or rescheduling the
189 The callout subsystem acquires the associated lock before calling the
190 callout function and releases it after the function returns.
191 If the callout was cancelled while the callout subsystem waited for the
193 the callout function is not called,
194 and the associated lock is released.
195 This ensures that stopping or rescheduling the callout will abort any
196 previously scheduled invocation.
198 Only regular mutexes may be used with
199 .Fn callout_init_mtx ;
200 spin mutexes are not supported.
201 A sleepable read-mostly lock
203 one initialized with the
208 .Fn callout_init_rm .
209 Similarly, other sleepable lock types such as
213 cannot be used with callouts because sleeping is not permitted in
214 the callout subsystem.
219 .Fn callout_init_mtx ,
220 .Fn callout_init_rm ,
222 .Fn callout_init_rw :
223 .Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED"
224 .It Dv CALLOUT_RETURNUNLOCKED
225 The callout function will release the associated lock itself,
226 so the callout subsystem should not attempt to unlock it
227 after the callout function returns.
228 .It Dv CALLOUT_SHAREDLOCK
229 The lock is only acquired in read mode when running the callout handler.
230 This flag is ignored by
231 .Fn callout_init_mtx .
238 if it is currently pending.
239 If the callout is pending, then
241 returns a non-zero value.
242 If the callout is not set,
243 has already been serviced,
244 or is currently being serviced,
245 then zero will be returned.
246 If the callout has an associated lock,
247 then that lock must be held when this function is called.
253 except that it will wait for the callout
255 to complete if it is already in progress.
256 This function MUST NOT be called while holding any
257 locks on which the callout might block, or deadlock will result.
258 Note that if the callout subsystem has already begun processing this
259 callout, then the callout function may be invoked before
262 However, the callout subsystem does guarantee that the callout will be
271 function families schedule a future function invocation for callout
275 already has a pending callout,
276 it is cancelled before the new invocation is scheduled.
277 These functions return a non-zero value if a pending callout was cancelled
278 and zero if there was no pending callout.
279 If the callout has an associated lock,
280 then that lock must be held when any of these functions are called.
282 The time at which the callout function will be invoked is determined by
294 the callout is scheduled to execute after
297 Non-positive values of
299 are silently converted to the value
307 arguments provide more control over the scheduled time including
308 support for higher resolution times,
309 specifying the precision of the scheduled time,
310 and setting an absolute deadline instead of a relative timeout.
311 The callout is scheduled to execute in a time window which begins at
312 the time specified in
314 and extends for the amount of time specified in
318 specifies a time in the past,
319 the window is adjusted to start at the current time.
322 allows the callout subsystem to coalesce callouts scheduled close to each
323 other into fewer timer interrupts,
324 reducing processing overhead and power consumption.
327 may be specified to adjust the interpretation of
331 .Bl -tag -width ".Dv C_DIRECT_EXEC"
335 argument as an absolute time since boot.
338 is treated as a relative amount of time,
342 Run the handler directly from hardware interrupt context instead of from the
344 This reduces latency and overhead, but puts more constraints on the callout
346 Callout functions run in this context may use only spin mutexes for locking
347 and should be as small as possible because they run with absolute priority.
349 Specifies relative event time precision as binary logarithm of time interval
350 divided by acceptable time deviation: 1 -- 1/2, 2 -- 1/4, etc.
351 Note that the larger of
353 or this value is used as the length of the time window.
355 .Pq which result in larger time intervals
356 allow the callout subsystem to aggregate more events in one timer interrupt.
358 Align the timeouts to
367 argument which identifies the function to be called when the time expires.
368 It must be a pointer to a function that takes a single
375 as its only argument.
382 arguments from the previous callout.
385 functions must always be called to initialize
391 functions can be used.
393 The callout subsystem provides a softclock thread for each CPU in the system.
394 Callouts are assigned to a single CPU and are executed by the softclock thread
397 callouts are assigned to CPU 0.
399 .Fn callout_reset_on ,
400 .Fn callout_reset_sbt_on ,
401 .Fn callout_schedule_on
403 .Fn callout_schedule_sbt_on
404 functions assign the callout to CPU
407 .Fn callout_reset_curcpu ,
408 .Fn callout_reset_sbt_curpu ,
409 .Fn callout_schedule_curcpu
411 .Fn callout_schedule_sbt_curcpu
412 functions assign the callout to the current CPU.
415 .Fn callout_reset_sbt ,
418 .Fn callout_schedule_sbt
419 functions schedule the callout to execute in the softclock thread of the CPU
420 to which it is currently assigned.
422 Softclock threads are not pinned to their respective CPUs by default.
423 The softclock thread for CPU 0 can be pinned to CPU 0 by setting the
424 .Va kern.pin_default_swi
425 loader tunable to a non-zero value.
426 Softclock threads for CPUs other than zero can be pinned to their
427 respective CPUs by setting the
428 .Va kern.pin_pcpu_swi
429 loader tunable to a non-zero value.
432 .Fn callout_pending ,
435 .Fn callout_deactivate
436 provide access to the current state of the callout.
439 macro checks whether a callout is
441 a callout is considered
443 when a timeout has been set but the time has not yet arrived.
444 Note that once the timeout time arrives and the callout subsystem
445 starts to process this callout,
449 even though the callout function may not have finished
454 macro checks whether a callout is marked as
457 .Fn callout_deactivate
458 macro clears the callout's
461 The callout subsystem marks a callout as
463 when a timeout is set and it clears the
471 clear it when a callout expires normally via the execution of the
473 .Ss "Avoiding Race Conditions"
474 The callout subsystem invokes callout functions from its own thread
476 Without some kind of synchronization,
477 it is possible that a callout
478 function will be invoked concurrently with an attempt to stop or reset
479 the callout by another thread.
480 In particular, since callout functions typically acquire a lock as
481 their first action, the callout function may have already been invoked,
482 but is blocked waiting for that lock at the time that another thread
483 tries to reset or stop the callout.
485 There are three main techniques for addressing these
486 synchronization concerns.
487 The first approach is preferred as it is the simplest:
488 .Bl -enum -offset indent
490 Callouts can be associated with a specific lock when they are initialized
492 .Fn callout_init_mtx ,
493 .Fn callout_init_rm ,
495 .Fn callout_init_rw .
496 When a callout is associated with a lock,
497 the callout subsystem acquires the lock before the callout function is
499 This allows the callout subsystem to transparently handle races between
500 callout cancellation,
503 Note that the associated lock must be acquired before calling
509 functions to provide this safety.
511 A callout initialized via
515 set to zero is implicitly associated with the
520 is held when cancelling or rescheduling the callout,
521 then its use will prevent races with the callout function.
523 The return value from
532 indicates whether or not the callout was removed.
533 If it is known that the callout was set and the callout function has
534 not yet executed, then a return value of
536 indicates that the callout function is about to be called.
538 .Bd -literal -offset indent
539 if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) {
540 if (callout_stop(&sc->sc_callout)) {
541 sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING;
542 /* successfully stopped */
545 * callout has expired and callout
546 * function is about to be executed
553 .Fn callout_pending ,
556 .Fn callout_deactivate
557 macros can be used together to work around the race conditions.
558 When a callout's timeout is set, the callout subsystem marks the
563 When the timeout time arrives, the callout subsystem begins processing
564 the callout by first clearing the
567 It then invokes the callout function without changing the
569 flag, and does not clear the
571 flag even after the callout function returns.
572 The mechanism described here requires the callout function itself to
576 .Fn callout_deactivate
582 functions always clear both the
586 flags before returning.
588 The callout function should first check the
590 flag and return without action if
594 This indicates that the callout was rescheduled using
596 just before the callout function was invoked.
601 then the callout function should also return without action.
602 This indicates that the callout has been stopped.
603 Finally, the callout function should call
604 .Fn callout_deactivate
609 .Bd -literal -offset indent
610 mtx_lock(&sc->sc_mtx);
611 if (callout_pending(&sc->sc_callout)) {
612 /* callout was reset */
613 mtx_unlock(&sc->sc_mtx);
616 if (!callout_active(&sc->sc_callout)) {
617 /* callout was stopped */
618 mtx_unlock(&sc->sc_mtx);
621 callout_deactivate(&sc->sc_callout);
622 /* rest of callout function */
625 Together with appropriate synchronization, such as the mutex used above,
626 this approach permits the
630 functions to be used at any time without races.
632 .Bd -literal -offset indent
633 mtx_lock(&sc->sc_mtx);
634 callout_stop(&sc->sc_callout);
635 /* The callout is effectively stopped now. */
638 If the callout is still pending then these functions operate normally,
639 but if processing of the callout has already begun then the tests in
640 the callout function cause it to return without further action.
641 Synchronization between the callout function and other code ensures that
642 stopping or resetting the callout will never be attempted while the
643 callout function is past the
644 .Fn callout_deactivate
647 The above technique additionally ensures that the
649 flag always reflects whether the callout is effectively enabled or
653 returns false, then the callout is effectively disabled, since even if
654 the callout subsystem is actually just about to invoke the callout
655 function, the callout function will return without action.
658 There is one final race condition that must be considered when a
659 callout is being stopped for the last time.
660 In this case it may not be safe to let the callout function itself
661 detect that the callout was stopped, since it may need to access
662 data objects that have already been destroyed or recycled.
663 To ensure that the callout is completely finished, a call to
667 a callout should always be drained prior to destroying its associated lock
668 or releasing the storage for the callout structure.
671 The functions below are a legacy API that will be removed in a future release.
672 New code should not use these routines.
677 schedules a call to the function given by the argument
682 Non-positive values of
684 are silently converted to the value
687 should be a pointer to a function that takes a
694 as its only argument.
695 The return value from
698 .Ft struct callout_handle
699 which can be used in conjunction with the
701 function to request that a scheduled timeout be canceled.
704 .Fn callout_handle_init
705 can be used to initialize a handle to a state which will cause
708 with that handle to return with no side
711 Assigning a callout handle the value of
712 .Fn CALLOUT_HANDLE_INITIALIZER
713 performs the same function as
714 .Fn callout_handle_init
715 and is provided for use on statically declared or global callout handles.
719 cancels the timeout associated with
725 arguments to validate the handle.
726 If the handle does not correspond to a timeout with
733 must be initialized by a previous call to
735 .Fn callout_handle_init ,
736 or assigned the value of
737 .Fn CALLOUT_HANDLE_INITIALIZER "&handle"
738 before being passed to
740 The behavior of calling
742 with an uninitialized handle
745 As handles are recycled by the system, it is possible (although unlikely)
746 that a handle from one invocation of
748 may match the handle of another invocation of
750 if both calls used the same function pointer and argument, and the first
751 timeout is expired or canceled before the second call.
752 The timeout facility offers O(1) running time for
756 Timeouts are executed from
761 Thus they are protected from re-entrancy.
765 macro returns the state of a callout's
771 macro returns the state of a callout's
779 function families return non-zero if the callout was pending before the new
780 function invocation was scheduled.
786 functions return non-zero if the callout was still pending when it was
787 called or zero otherwise.
791 .Ft struct callout_handle
792 that can be passed to
795 The current timeout and untimeout routines are based on the work of
798 .An George Varghese ,
799 published in a technical report entitled
800 .%T "Redesigning the BSD Callout and Timer Facilities"
801 and modified slightly for inclusion in
804 .An Justin T. Gibbs .
805 The original work on the data structures used in this implementation
811 .%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility"
813 .%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" .
814 The current implementation replaces the long standing
817 callout mechanism which offered O(n) insertion and removal running time
818 but did not generate or require handles for untimeout operations.