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 ,
45 .Nm callout_schedule ,
48 .Nm callout_deactivate
49 .Nd execute a function after a specified length of time
54 typedef void timeout_t (void *);
56 .Ft struct callout_handle
57 .Fn timeout "timeout_t *func" "void *arg" "int ticks"
59 .Fn callout_handle_init "struct callout_handle *handle"
61 struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle)
64 .Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle"
66 .Fn callout_init "struct callout *c" "int mpsafe"
68 .Fn callout_init_mtx "struct callout *c" "struct mtx *mtx" "int flags"
70 .Fn callout_init_rw "struct callout *c" "struct rwlock *rw" "int flags"
72 .Fn callout_stop "struct callout *c"
74 .Fn callout_drain "struct callout *c"
76 .Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg"
78 .Fn callout_schedule "struct callout *c" "int ticks"
80 .Fn callout_pending "struct callout *c"
82 .Fn callout_active "struct callout *c"
83 .Fn callout_deactivate "struct callout *c"
87 schedules a call to the function given by the argument
92 Non-positive values of
94 are silently converted to the value
97 should be a pointer to a function that takes a
104 as its only argument.
105 The return value from
108 .Ft struct callout_handle
109 which can be used in conjunction with the
111 function to request that a scheduled timeout be canceled.
114 call is the old style and new code should use the
119 .Fn callout_handle_init
120 can be used to initialize a handle to a state which will cause
123 with that handle to return with no side
126 Assigning a callout handle the value of
127 .Fn CALLOUT_HANDLE_INITIALIZER
128 performs the same function as
129 .Fn callout_handle_init
130 and is provided for use on statically declared or global callout handles.
134 cancels the timeout associated with
140 arguments to validate the handle.
141 If the handle does not correspond to a timeout with
148 must be initialized by a previous call to
150 .Fn callout_handle_init ,
151 or assigned the value of
152 .Fn CALLOUT_HANDLE_INITIALIZER "&handle"
153 before being passed to
155 The behavior of calling
157 with an uninitialized handle
161 call is the old style and new code should use the
165 As handles are recycled by the system, it is possible (although unlikely)
166 that a handle from one invocation of
168 may match the handle of another invocation of
170 if both calls used the same function pointer and argument, and the first
171 timeout is expired or canceled before the second call.
172 The timeout facility offers O(1) running time for
176 Timeouts are executed from
181 Thus they are protected from re-entrancy.
185 .Fn callout_init_mtx ,
186 .Fn callout_init_rw ,
192 are low-level routines for clients who wish to allocate their own
197 initializes a callout so it can be passed to
203 without any side effects.
207 the callout structure is not considered to be
208 .Dq multi-processor safe ;
210 the Giant lock will be acquired before calling the callout function,
211 and released when the callout function returns.
215 function may be used as an alternative to
219 specifies a mutex that is to be acquired by the callout subsystem
220 before calling the callout function, and released when the callout
225 .Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED"
226 .It Dv CALLOUT_RETURNUNLOCKED
227 The callout function will release
229 itself, so the callout subsystem should not attempt to unlock it
230 after the callout function returns.
235 function serves the need of using rwlocks in conjunction with callouts.
236 The function does basically the same as
238 with the possibility of specifying an extra
241 The usable lock classes are currently limited to mutexes and rwlocks,
242 because callout handlers run in softclock swi, so they cannot sleep nor
243 acquire sleepable locks like sx or lockmgr.
247 .Bl -tag -width ".Dv CALLOUT_SHAREDLOCK"
248 .It Dv CALLOUT_SHAREDLOCK
249 The lock is only acquired in read mode when running the callout handler.
250 It has no effects when used in conjunction with
256 cancels a callout if it is currently pending.
257 If the callout is pending, then
259 will return a non-zero value.
260 If the callout is not set, has already been serviced or is currently
261 being serviced, then zero will be returned.
262 If the callout has an associated mutex, then that mutex must be
263 held when this function is called.
269 except that it will wait for the callout to be completed if it is
271 This function MUST NOT be called while holding any
272 locks on which the callout might block, or deadlock will result.
273 Note that if the callout subsystem has already begun processing this
274 callout, then the callout function may be invoked during the execution of
276 However, the callout subsystem does guarantee that the callout will be
283 first performs the equivalent of
285 to disestablish the callout, and then establishes a new callout in the
288 If there was already a pending callout and it was rescheduled, then
290 will return a non-zero value.
291 If the callout has an associated mutex, then that mutex must be
292 held when this function is called.
295 (re)schedules an existing callout for a new period of time;
296 it is equivalent to calling
302 parameters extracted from the callout structure (though possibly with
306 .Fn callout_pending ,
309 .Fn callout_deactivate
310 provide access to the current state of the callout.
311 Careful use of these macros can avoid many of the race conditions
312 that are inherent in asynchronous timer facilities; see
313 .Sx "Avoiding Race Conditions"
314 below for further details.
317 macro checks whether a callout is
319 a callout is considered
321 when a timeout has been set but the time has not yet arrived.
322 Note that once the timeout time arrives and the callout subsystem
323 starts to process this callout,
327 even though the callout function may not have finished (or even begun)
331 macro checks whether a callout is marked as
334 .Fn callout_deactivate
335 macro clears the callout's
338 The callout subsystem marks a callout as
340 when a timeout is set and it clears the
348 clear it when a callout expires normally via the execution of the
350 .Ss "Avoiding Race Conditions"
351 The callout subsystem invokes callout functions from its own timer
353 Without some kind of synchronization it is possible that a callout
354 function will be invoked concurrently with an attempt to stop or reset
355 the callout by another thread.
356 In particular, since callout functions typically acquire a mutex as
357 their first action, the callout function may have already been invoked,
358 but be blocked waiting for that mutex at the time that another thread
359 tries to reset or stop the callout.
361 The callout subsystem provides a number of mechanisms to address these
362 synchronization concerns:
363 .Bl -enum -offset indent
365 If the callout has an associated mutex that was specified using the
367 function (or implicitly specified as the
375 then this mutex is used to avoid the race conditions.
376 The associated mutex must be acquired by the caller before calling
380 and it is guaranteed that the callout will be correctly stopped
381 or reset as expected.
382 Note that it is still necessary to use
384 before destroying the callout or its associated mutex.
386 The return value from
390 indicates whether or not the callout was removed.
391 If it is known that the callout was set and the callout function has
392 not yet executed, then a return value of
394 indicates that the callout function is about to be called.
396 .Bd -literal -offset indent
397 if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) {
398 if (callout_stop(&sc->sc_callout)) {
399 sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING;
400 /* successfully stopped */
403 * callout has expired and callout
404 * function is about to be executed
411 .Fn callout_pending ,
414 .Fn callout_deactivate
415 macros can be used together to work around the race conditions.
416 When a callout's timeout is set, the callout subsystem marks the
421 When the timeout time arrives, the callout subsystem begins processing
422 the callout by first clearing the
425 It then invokes the callout function without changing the
427 flag, and does not clear the
429 flag even after the callout function returns.
430 The mechanism described here requires the callout function itself to
434 .Fn callout_deactivate
440 functions always clear both the
444 flags before returning.
446 The callout function should first check the
448 flag and return without action if
452 This indicates that the callout was rescheduled using
454 just before the callout function was invoked.
459 then the callout function should also return without action.
460 This indicates that the callout has been stopped.
461 Finally, the callout function should call
462 .Fn callout_deactivate
467 .Bd -literal -offset indent
468 mtx_lock(&sc->sc_mtx);
469 if (callout_pending(&sc->sc_callout)) {
470 /* callout was reset */
471 mtx_unlock(&sc->sc_mtx);
474 if (!callout_active(&sc->sc_callout)) {
475 /* callout was stopped */
476 mtx_unlock(&sc->sc_mtx);
479 callout_deactivate(&sc->sc_callout);
480 /* rest of callout function */
483 Together with appropriate synchronization, such as the mutex used above,
484 this approach permits the
488 functions to be used at any time without races.
490 .Bd -literal -offset indent
491 mtx_lock(&sc->sc_mtx);
492 callout_stop(&sc->sc_callout);
493 /* The callout is effectively stopped now. */
496 If the callout is still pending then these functions operate normally,
497 but if processing of the callout has already begun then the tests in
498 the callout function cause it to return without further action.
499 Synchronization between the callout function and other code ensures that
500 stopping or resetting the callout will never be attempted while the
501 callout function is past the
502 .Fn callout_deactivate
505 The above technique additionally ensures that the
507 flag always reflects whether the callout is effectively enabled or
511 returns false, then the callout is effectively disabled, since even if
512 the callout subsystem is actually just about to invoke the callout
513 function, the callout function will return without action.
516 There is one final race condition that must be considered when a
517 callout is being stopped for the last time.
518 In this case it may not be safe to let the callout function itself
519 detect that the callout was stopped, since it may need to access
520 data objects that have already been destroyed or recycled.
521 To ensure that the callout is completely finished, a call to
528 .Ft struct callout_handle
529 that can be passed to
535 functions return non-zero if the callout was still pending when it was
536 called or zero otherwise.
538 The current timeout and untimeout routines are based on the work of
541 .An George Varghese ,
542 published in a technical report entitled
543 .%T "Redesigning the BSD Callout and Timer Facilities"
544 and modified slightly for inclusion in
547 .An Justin T. Gibbs .
548 The original work on the data structures used in this implementation
554 .%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility"
556 .%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" .
557 The current implementation replaces the long standing
560 callout mechanism which offered O(n) insertion and removal running time
561 but did not generate or require handles for untimeout operations.