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 ,
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_drain "struct callout *c"
75 .Fn callout_handle_init "struct callout_handle *handle"
77 struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle);
80 .Fn callout_init "struct callout *c" "int mpsafe"
82 .Fn callout_init_mtx "struct callout *c" "struct mtx *mtx" "int flags"
84 .Fn callout_init_rm "struct callout *c" "struct rmlock *rm" "int flags"
86 .Fn callout_init_rw "struct callout *c" "struct rwlock *rw" "int flags"
88 .Fn callout_pending "struct callout *c"
90 .Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg"
92 .Fo callout_reset_curcpu
93 .Fa "struct callout *c"
100 .Fa "struct callout *c"
102 .Fa "timeout_t *func"
107 .Fo callout_reset_sbt
108 .Fa "struct callout *c"
111 .Fa "timeout_t *func"
116 .Fo callout_reset_sbt_curcpu
117 .Fa "struct callout *c"
120 .Fa "timeout_t *func"
125 .Fo callout_reset_sbt_on
126 .Fa "struct callout *c"
129 .Fa "timeout_t *func"
135 .Fn callout_schedule "struct callout *c" "int ticks"
137 .Fn callout_schedule_curcpu "struct callout *c" "int ticks"
139 .Fn callout_schedule_on "struct callout *c" "int ticks" "int cpu"
141 .Fo callout_schedule_sbt
142 .Fa "struct callout *c"
148 .Fo callout_schedule_sbt_curcpu
149 .Fa "struct callout *c"
155 .Fo callout_schedule_sbt_on
156 .Fa "struct callout *c"
163 .Fn callout_stop "struct callout *c"
167 .Fa "sbintime_t precision"
169 .Fa "sbintime_t *sbt_res"
170 .Fa "sbintime_t *precision_res"
172 .Ft struct callout_handle
173 .Fn timeout "timeout_t *func" "void *arg" "int ticks"
175 .Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle"
179 API is used to schedule a call to an arbitrary function at a specific
181 Consumers of this API are required to allocate a callout structure
183 for each pending function invocation.
184 This structure stores state about the pending function invocation including
185 the function to be called and the time at which the function should be invoked.
186 Pending function calls can be cancelled or rescheduled to a different time.
188 a callout structure may be reused to schedule a new function call after a
189 scheduled call is completed.
191 Callouts only provide a single-shot mode.
192 If a consumer requires a periodic timer,
193 it must explicitly reschedule each function call.
194 This is normally done by rescheduling the subsequent call within the called
197 Callout functions must not sleep.
198 They may not acquire sleepable locks,
199 wait on condition variables,
200 perform blocking allocation requests,
201 or invoke any other action that might sleep.
203 Each callout structure must be initialized by
205 .Fn callout_init_mtx ,
206 .Fn callout_init_rm ,
209 before it is passed to any of the other callout functions.
212 function initializes a callout structure in
214 that is not associated with a specific lock.
218 the callout structure is not considered to be
219 .Dq multi-processor safe ;
220 and the Giant lock will be acquired before calling the callout function
221 and released when the callout function returns.
224 .Fn callout_init_mtx ,
225 .Fn callout_init_rm ,
228 functions initialize a callout structure in
230 that is associated with a specific lock.
231 The lock is specified by the
237 The associated lock must be held while stopping or rescheduling the
239 The callout subsystem acquires the associated lock before calling the
240 callout function and releases it after the function returns.
241 If the callout was cancelled while the callout subsystem waited for the
243 the callout function is not called,
244 and the associated lock is released.
245 This ensures that stopping or rescheduling the callout will abort any
246 previously scheduled invocation.
248 Only regular mutexes may be used with
249 .Fn callout_init_mtx ;
250 spin mutexes are not supported.
251 A sleepable read-mostly lock
253 one initialized with the
258 .Fn callout_init_rm .
259 Similarly, other sleepable lock types such as
263 cannot be used with callouts because sleeping is not permitted in
264 the callout subsystem.
269 .Fn callout_init_mtx ,
270 .Fn callout_init_rm ,
272 .Fn callout_init_rw :
273 .Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED"
274 .It Dv CALLOUT_RETURNUNLOCKED
275 The callout function will release the associated lock itself,
276 so the callout subsystem should not attempt to unlock it
277 after the callout function returns.
278 .It Dv CALLOUT_SHAREDLOCK
279 The lock is only acquired in read mode when running the callout handler.
280 This flag is ignored by
281 .Fn callout_init_mtx .
288 if it is currently pending.
289 If the callout is pending, then
291 returns a non-zero value.
292 If the callout is not set,
293 has already been serviced,
294 or is currently being serviced,
295 then zero will be returned.
296 If the callout has an associated lock,
297 then that lock must be held when this function is called.
303 except that it will wait for the callout
305 to complete if it is already in progress.
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 before
312 However, the callout subsystem does guarantee that the callout will be
321 function families schedule a future function invocation for callout
325 already has a pending callout,
326 it is cancelled before the new invocation is scheduled.
327 These functions return a non-zero value if a pending callout was cancelled
328 and zero if there was no pending callout.
329 If the callout has an associated lock,
330 then that lock must be held when any of these functions are called.
332 The time at which the callout function will be invoked is determined by
344 the callout is scheduled to execute after
347 Non-positive values of
349 are silently converted to the value
357 arguments provide more control over the scheduled time including
358 support for higher resolution times,
359 specifying the precision of the scheduled time,
360 and setting an absolute deadline instead of a relative timeout.
361 The callout is scheduled to execute in a time window which begins at
362 the time specified in
364 and extends for the amount of time specified in
368 specifies a time in the past,
369 the window is adjusted to start at the current time.
372 allows the callout subsystem to coalesce callouts scheduled close to each
373 other into fewer timer interrupts,
374 reducing processing overhead and power consumption.
377 may be specified to adjust the interpretation of
381 .Bl -tag -width ".Dv C_DIRECT_EXEC"
385 argument as an absolute time since boot.
388 is treated as a relative amount of time,
392 Run the handler directly from hardware interrupt context instead of from the
394 This reduces latency and overhead, but puts more constraints on the callout
396 Callout functions run in this context may use only spin mutexes for locking
397 and should be as small as possible because they run with absolute priority.
399 Specifies relative event time precision as binary logarithm of time interval
400 divided by acceptable time deviation: 1 -- 1/2, 2 -- 1/4, etc.
401 Note that the larger of
403 or this value is used as the length of the time window.
405 .Pq which result in larger time intervals
406 allow the callout subsystem to aggregate more events in one timer interrupt.
410 argument specifies the absolute time at which the callout should be run,
413 argument specifies the requested precision, which will not be
414 adjusted during the scheduling process.
419 values should be calculated by an earlier call to
421 which uses the user-supplied
428 Align the timeouts to
437 argument which identifies the function to be called when the time expires.
438 It must be a pointer to a function that takes a single
445 as its only argument.
452 arguments from the previous callout.
455 functions must always be called to initialize
461 functions can be used.
463 The callout subsystem provides a softclock thread for each CPU in the system.
464 Callouts are assigned to a single CPU and are executed by the softclock thread
467 callouts are assigned to CPU 0.
469 .Fn callout_reset_on ,
470 .Fn callout_reset_sbt_on ,
471 .Fn callout_schedule_on
473 .Fn callout_schedule_sbt_on
474 functions assign the callout to CPU
477 .Fn callout_reset_curcpu ,
478 .Fn callout_reset_sbt_curpu ,
479 .Fn callout_schedule_curcpu
481 .Fn callout_schedule_sbt_curcpu
482 functions assign the callout to the current CPU.
485 .Fn callout_reset_sbt ,
488 .Fn callout_schedule_sbt
489 functions schedule the callout to execute in the softclock thread of the CPU
490 to which it is currently assigned.
492 Softclock threads are not pinned to their respective CPUs by default.
493 The softclock thread for CPU 0 can be pinned to CPU 0 by setting the
494 .Va kern.pin_default_swi
495 loader tunable to a non-zero value.
496 Softclock threads for CPUs other than zero can be pinned to their
497 respective CPUs by setting the
498 .Va kern.pin_pcpu_swi
499 loader tunable to a non-zero value.
502 .Fn callout_pending ,
505 .Fn callout_deactivate
506 provide access to the current state of the callout.
509 macro checks whether a callout is
511 a callout is considered
513 when a timeout has been set but the time has not yet arrived.
514 Note that once the timeout time arrives and the callout subsystem
515 starts to process this callout,
519 even though the callout function may not have finished
524 macro checks whether a callout is marked as
527 .Fn callout_deactivate
528 macro clears the callout's
531 The callout subsystem marks a callout as
533 when a timeout is set and it clears the
541 clear it when a callout expires normally via the execution of the
546 function may be used to pre-calculate the absolute time at which the
547 timeout should be run and the precision of the scheduled run time
548 according to the required time
552 and additional adjustments requested by the
555 Flags accepted by the
557 function are the same as flags for the
560 The resulting time is assigned to the variable pointed to by the
562 argument, and the resulting precision is assigned to
564 When passing the results to
570 to avoid incorrect re-adjustment.
571 The function is intended for situations where precise time of the callout
572 run should be known in advance, since
573 trying to read this time from the callout structure itself after a
576 .Ss "Avoiding Race Conditions"
577 The callout subsystem invokes callout functions from its own thread
579 Without some kind of synchronization,
580 it is possible that a callout
581 function will be invoked concurrently with an attempt to stop or reset
582 the callout by another thread.
583 In particular, since callout functions typically acquire a lock as
584 their first action, the callout function may have already been invoked,
585 but is blocked waiting for that lock at the time that another thread
586 tries to reset or stop the callout.
588 There are three main techniques for addressing these
589 synchronization concerns.
590 The first approach is preferred as it is the simplest:
591 .Bl -enum -offset indent
593 Callouts can be associated with a specific lock when they are initialized
595 .Fn callout_init_mtx ,
596 .Fn callout_init_rm ,
598 .Fn callout_init_rw .
599 When a callout is associated with a lock,
600 the callout subsystem acquires the lock before the callout function is
602 This allows the callout subsystem to transparently handle races between
603 callout cancellation,
606 Note that the associated lock must be acquired before calling
612 functions to provide this safety.
614 A callout initialized via
618 set to zero is implicitly associated with the
623 is held when cancelling or rescheduling the callout,
624 then its use will prevent races with the callout function.
626 The return value from
635 indicates whether or not the callout was removed.
636 If it is known that the callout was set and the callout function has
637 not yet executed, then a return value of
639 indicates that the callout function is about to be called.
641 .Bd -literal -offset indent
642 if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) {
643 if (callout_stop(&sc->sc_callout)) {
644 sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING;
645 /* successfully stopped */
648 * callout has expired and callout
649 * function is about to be executed
656 .Fn callout_pending ,
659 .Fn callout_deactivate
660 macros can be used together to work around the race conditions.
661 When a callout's timeout is set, the callout subsystem marks the
666 When the timeout time arrives, the callout subsystem begins processing
667 the callout by first clearing the
670 It then invokes the callout function without changing the
672 flag, and does not clear the
674 flag even after the callout function returns.
675 The mechanism described here requires the callout function itself to
679 .Fn callout_deactivate
685 functions always clear both the
689 flags before returning.
691 The callout function should first check the
693 flag and return without action if
697 This indicates that the callout was rescheduled using
699 just before the callout function was invoked.
704 then the callout function should also return without action.
705 This indicates that the callout has been stopped.
706 Finally, the callout function should call
707 .Fn callout_deactivate
712 .Bd -literal -offset indent
713 mtx_lock(&sc->sc_mtx);
714 if (callout_pending(&sc->sc_callout)) {
715 /* callout was reset */
716 mtx_unlock(&sc->sc_mtx);
719 if (!callout_active(&sc->sc_callout)) {
720 /* callout was stopped */
721 mtx_unlock(&sc->sc_mtx);
724 callout_deactivate(&sc->sc_callout);
725 /* rest of callout function */
728 Together with appropriate synchronization, such as the mutex used above,
729 this approach permits the
733 functions to be used at any time without races.
735 .Bd -literal -offset indent
736 mtx_lock(&sc->sc_mtx);
737 callout_stop(&sc->sc_callout);
738 /* The callout is effectively stopped now. */
741 If the callout is still pending then these functions operate normally,
742 but if processing of the callout has already begun then the tests in
743 the callout function cause it to return without further action.
744 Synchronization between the callout function and other code ensures that
745 stopping or resetting the callout will never be attempted while the
746 callout function is past the
747 .Fn callout_deactivate
750 The above technique additionally ensures that the
752 flag always reflects whether the callout is effectively enabled or
756 returns false, then the callout is effectively disabled, since even if
757 the callout subsystem is actually just about to invoke the callout
758 function, the callout function will return without action.
761 There is one final race condition that must be considered when a
762 callout is being stopped for the last time.
763 In this case it may not be safe to let the callout function itself
764 detect that the callout was stopped, since it may need to access
765 data objects that have already been destroyed or recycled.
766 To ensure that the callout is completely finished, a call to
770 a callout should always be drained prior to destroying its associated lock
771 or releasing the storage for the callout structure.
774 The functions below are a legacy API that will be removed in a future release.
775 New code should not use these routines.
780 schedules a call to the function given by the argument
785 Non-positive values of
787 are silently converted to the value
790 should be a pointer to a function that takes a
797 as its only argument.
798 The return value from
801 .Ft struct callout_handle
802 which can be used in conjunction with the
804 function to request that a scheduled timeout be canceled.
807 .Fn callout_handle_init
808 can be used to initialize a handle to a state which will cause
811 with that handle to return with no side
814 Assigning a callout handle the value of
815 .Fn CALLOUT_HANDLE_INITIALIZER
816 performs the same function as
817 .Fn callout_handle_init
818 and is provided for use on statically declared or global callout handles.
822 cancels the timeout associated with
828 arguments to validate the handle.
829 If the handle does not correspond to a timeout with
836 must be initialized by a previous call to
838 .Fn callout_handle_init ,
839 or assigned the value of
840 .Fn CALLOUT_HANDLE_INITIALIZER "&handle"
841 before being passed to
843 The behavior of calling
845 with an uninitialized handle
848 As handles are recycled by the system, it is possible (although unlikely)
849 that a handle from one invocation of
851 may match the handle of another invocation of
853 if both calls used the same function pointer and argument, and the first
854 timeout is expired or canceled before the second call.
855 The timeout facility offers O(1) running time for
859 Timeouts are executed from
864 Thus they are protected from re-entrancy.
868 macro returns the state of a callout's
874 macro returns the state of a callout's
882 function families return non-zero if the callout was pending before the new
883 function invocation was scheduled.
889 functions return non-zero if the callout was still pending when it was
890 called or zero otherwise.
894 .Ft struct callout_handle
895 that can be passed to
898 The current timeout and untimeout routines are based on the work of
901 .An George Varghese ,
902 published in a technical report entitled
903 .%T "Redesigning the BSD Callout and Timer Facilities"
904 and modified slightly for inclusion in
907 .An Justin T. Gibbs .
908 The original work on the data structures used in this implementation
914 .%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility"
916 .%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" .
917 The current implementation replaces the long standing
920 callout mechanism which offered O(n) insertion and removal running time
921 but did not generate or require handles for untimeout operations.