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.
35 .Nm callout_deactivate ,
42 .Nm callout_reset_bycpu ,
44 .Nm callout_stop_async ,
47 .Nd execute a function after a specified length of time
53 typedef void timeout_t (void *);
56 .Fn callout_active "struct callout *c"
58 .Fn callout_deactivate "struct callout *c"
60 .Fn callout_drain "struct callout *c"
62 .Fn callout_init "struct callout *c" "int mpsafe"
64 .Fn callout_init_lk "struct callout *c" "struct lock *lk"
66 .Fn callout_pending "struct callout *c"
68 .Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg"
70 .Fo callout_reset_bycpu
71 .Fa "struct callout *c"
78 .Fn callout_stop "struct callout *c"
80 .Fn callout_stop_async "struct callout *c"
82 .Fn callout_cancel "struct callout *c"
84 .Fn callout_terminate "struct callout *c"
88 API is used to schedule a call to an arbitrary function at a specific
90 Consumers of this API are required to allocate a callout structure
92 for each pending function invocation.
93 This structure stores state about the pending function invocation including
94 the function to be called and the time at which the function should be invoked.
95 Pending function calls can be cancelled or rescheduled to a different time.
97 a callout structure may be reused to schedule a new function call after a
98 scheduled call is completed.
100 Callouts only provide a single-shot mode.
101 If a consumer requires a periodic timer,
102 it must explicitly reschedule each function call.
103 This is normally done by rescheduling the subsequent call within the called
108 callout functions must not sleep.
109 They may not acquire sleepable locks,
110 wait on condition variables,
111 perform blocking allocation requests,
112 or invoke any other action that might sleep.
115 all callout functions are executed from a common kernel thread on the
116 target cpu and may block as long as deadlocks are avoided. But generally
117 speaking, callout functions should run in as short a time as possible
118 as they can add lag to other unrelated callouts.
120 Each callout structure must be initialized by
122 .Fn callout_init_mp ,
125 before it is passed to any of the other callout functions.
130 functions initialize a callout structure in
132 that is not associated with a specific lock.
133 The former will hold the mp_lock across callback. However, it is deprecated
134 and should not be used in new code.
136 should be used for any new code.
140 function initialize a callout structure in
142 that is associated with a specific lock.
145 the associated lock should be held while stopping or rescheduling the
149 the same is true, but is not a requirement.
151 The callout subsystem acquires the associated lock before calling the
152 callout function and releases it after the function returns.
153 If the callout was cancelled while the callout subsystem waited for the
155 the callout function is not called,
156 and the associated lock is released.
157 This ensures that stopping or rescheduling the callout will abort any
158 previously scheduled invocation.
164 if it is currently pending.
165 If the callout is pending and successfully stopped, then
167 returns a value of one.
170 if the callout is not set, or
171 has already been serviced, then
172 negative one is returned.
175 if the callout is not set, or
176 has already been serviced, then
178 If the callout is currently being serviced and cannot be stopped,
179 then zero will be returned.
180 If the callout is currently being serviced and cannot be stopped, and at the
181 same time a next invocation of the same callout is also scheduled, then
183 unschedules the next run and returns zero.
186 if the callout has an associated lock,
187 then that lock must be held when this function is called.
190 if the callout has an associated lock,
191 then that lock should be held when this function is called
192 to avoid races, but does not have to be.
196 the stop operation is guaranteed to be synchronous if the callout
198 .Fn callout_init_lk .
201 .Fn callout_stop_async
204 but does not block and allows the STOP operation to be asynchronous,
205 meaning that the callout structure may still be relevant after the
206 function returns. This situation can occur if the callback was
207 in-progress at the time the stop was issued.
211 synchronously cancels a callout and returns a value similar to that
215 overrides all other operations while it is in-progress.
218 .Fn callout_terminate
219 synchronously cancels a callout and informs the system that the
220 callout structure will no longer be referenced. This function will
221 clear the initialization flag and any further use of the callout structure
222 will panic the system until it is next initialized. The callout structure
223 can be safely freed after this function returns, assuming other program
224 references to it have been removed.
230 except that it will wait for the callout
232 to complete if it is already in progress.
233 This function MUST NOT be called while holding any
234 locks on which the callout might block, or deadlock will result.
235 Note that if the callout subsystem has already begun processing this
236 callout, then the callout function may be invoked before
239 However, the callout subsystem does guarantee that the callout will be
246 function schedules a future function invocation for callout
250 already has a pending callout,
251 it is cancelled before the new invocation is scheduled.
254 these functions return a value of one if a pending callout was cancelled
255 and zero if there was no pending callout.
256 If the callout has an associated lock,
257 then that lock must be held when any of these functions are called.
260 these functions return void.
261 If the callout has an associated lock,
262 then that lock should generally be held when any of these functions are
263 called, but the API will work either way.
264 If a callout is already in-progress, this function's parameters will be
265 applied when the in-progress callback returns, if not overridden from
268 The time at which the callout function will be invoked is determined by
272 The callout is scheduled to execute after
275 Non-positive values of
277 are silently converted to the value
281 .Fn callout_reset_bycpu
282 function schedules the callout to occur on the target cpu. The
285 function schedules the callout to occur on the current cpu.
290 argument which identifies the function to be called when the time expires.
291 It must be a pointer to a function that takes a single
298 as its only argument.
300 The callout subsystem provides a softclock thread for each CPU in the system.
301 Callouts are assigned to a single CPU and are executed by the softclock thread
303 The callouts are assigned to the current cpu or to a specific cpu
304 depending on the call.
307 .Fn callout_pending ,
310 .Fn callout_deactivate
311 provide access to the current state of the callout.
314 macro checks whether a callout is
316 a callout is considered
318 when a timeout has been set but the time has not yet arrived.
319 Note that once the timeout time arrives and the callout subsystem
320 starts to process this callout,
324 even though the callout function may not have finished
329 macro checks whether a callout is marked as
332 .Fn callout_deactivate
333 macro clears the callout's
336 The callout subsystem marks a callout as
338 when a timeout is set and it clears the
346 clear it when a callout expires normally via the execution of the
349 There are three main techniques for addressing these
350 synchronization concerns.
351 The first approach is preferred as it is the simplest:
352 .Bl -enum -offset indent
354 Callouts can be associated with a specific lock when they are initialized
357 When a callout is associated with a lock,
358 the callout subsystem acquires the lock before the callout function is
360 This allows the callout subsystem to transparently handle races between
361 callout cancellation,
364 Note that the associated lock must be acquired before calling
368 functions to provide this safety.
371 .Fn callout_pending ,
374 .Fn callout_deactivate
375 macros can be used together to work around the race conditions,
376 but the interpretation of these calls can be confusing and it
377 is recommended that a different, caller-specific method be used to
378 determine whether a race condition is present.
380 When a callout's timeout is set, the callout subsystem marks the
385 When the timeout time arrives, the callout subsystem begins processing
386 the callout by first clearing the
389 It then invokes the callout function without changing the
391 flag, and does not clear the
393 flag even after the callout function returns.
394 The mechanism described here requires the callout function itself to
398 .Fn callout_deactivate
404 functions always clear both the
408 flags before returning.
410 The callout function should first check the
412 flag and return without action if
416 This indicates that the callout was rescheduled using
418 just before the callout function was invoked.
423 then the callout function should also return without action.
424 This indicates that the callout has been stopped.
425 Finally, the callout function should call
426 .Fn callout_deactivate
431 .Bd -literal -offset indent
432 lockmgr(&sc->sc_lock, LK_EXCLUSIVE);
433 if (callout_pending(&sc->sc_callout)) {
434 /* callout was reset */
435 lockmgr(&sc->sc_lock, LK_RELEASE);
438 if (!callout_active(&sc->sc_callout)) {
439 /* callout was stopped */
440 lockmgr(&sc->sc_lock, LK_RELEASE);
443 callout_deactivate(&sc->sc_callout);
444 /* rest of callout function */
447 Together with appropriate synchronization, such as the lock used above,
448 this approach permits the
452 functions to be used at any time without races.
454 .Bd -literal -offset indent
455 lockmgr(&sc->sc_mtx, LK_EXCLUSIVE);
456 callout_stop(&sc->sc_callout);
457 /* The callout is effectively stopped now. */
460 If the callout is still pending then these functions operate normally,
461 but if processing of the callout has already begun then the tests in
462 the callout function cause it to return without further action.
463 Synchronization between the callout function and other code ensures that
464 stopping or resetting the callout will never be attempted while the
465 callout function is past the
466 .Fn callout_deactivate
469 The above technique additionally ensures that the
471 flag always reflects whether the callout is effectively enabled or
475 returns false, then the callout is effectively disabled, since even if
476 the callout subsystem is actually just about to invoke the callout
477 function, the callout function will return without action.
480 There is one final race condition that must be considered when a
481 callout is being stopped for the last time.
482 In this case it may not be safe to let the callout function itself
483 detect that the callout was stopped, since it may need to access
484 data objects that have already been destroyed or recycled.
485 To ensure that the callout is completely inactive, a call to
488 .Fn callout_terminate
493 macro returns the state of a callout's
499 macro returns the state of a callout's
507 functions return a value of one if the callout was removed by the
508 function, or zero if the callout could not be stopped or was not running
511 The original work on the data structures used in this implementation
517 .%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility"
519 .%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" .
520 The current implementation replaces the long standing
523 callout mechanism which offered O(n) insertion and removal running time
524 but did not generate or require handles for untimeout operations.
528 the entire API was reformulated by Matthew Dillon for optimal SMP
529 operation, uses much larger rings, and is capable of queueing one
530 operation concurrent with an in-progress callback without blocking.