| blob | e6d911d2349b5d203d804c5522b78d9d7b43b921 |
1 .\" $NetBSD: timeout.9,v 1.2 1996/06/23 22:32:34 pk Exp $
2 .\"
3 .\" Copyright (c) 1996 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Paul Kranenburg.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
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.
17 .\" 3. All advertising materials mentioning features or use of this software
18 .\" must display the following acknowledgement:
19 .\" This product includes software developed by the NetBSD
20 .\" Foundation, Inc. and its contributors.
21 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
22 .\" contributors may be used to endorse or promote products derived
23 .\" from this software without specific prior written permission.
24 .\"
25 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
26 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
27 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
29 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
30 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
32 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
33 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35 .\" POSSIBILITY OF SUCH DAMAGE.
36 .\"
37 .\" $FreeBSD$
38 .\"
39 .Dd August 2, 2008
40 .Dt TIMEOUT 9
41 .Os
42 .Sh NAME
43 .Nm timeout ,
44 .Nm untimeout ,
45 .Nm callout_handle_init ,
46 .Nm callout_init ,
47 .Nm callout_init_mtx ,
48 .Nm callout_init_rw ,
49 .Nm callout_stop ,
50 .Nm callout_drain ,
51 .Nm callout_reset ,
52 .Nm callout_schedule ,
53 .Nm callout_pending ,
54 .Nm callout_active ,
55 .Nm callout_deactivate
56 .Nd execute a function after a specified length of time
57 .Sh SYNOPSIS
58 .In sys/types.h
59 .In sys/systm.h
60 .Pp
61 .Bd -literal
62 typedef void timeout_t (void *);
63 .Ed
64 .Ft struct callout_handle
65 .Fn timeout "timeout_t *func" "void *arg" "int ticks"
66 .Ft void
67 .Fn callout_handle_init "struct callout_handle *handle"
68 .Pp
69 .Bd -literal
70 struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle)
71 .Ed
72 .Ft void
73 .Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle"
74 .Ft void
75 .Fn callout_init "struct callout *c" "int mpsafe"
76 .Ft void
77 .Fn callout_init_mtx "struct callout *c" "struct mtx *mtx" "int flags"
78 .Ft void
79 .Fn callout_init_rw "struct callout *c" "struct rwlock *rw" "int flags"
80 .Ft int
81 .Fn callout_stop "struct callout *c"
82 .Ft int
83 .Fn callout_drain "struct callout *c"
84 .Ft int
85 .Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg"
86 .Ft int
87 .Fn callout_schedule "struct callout *c" "int ticks"
88 .Ft int
89 .Fn callout_pending "struct callout *c"
90 .Ft int
91 .Fn callout_active "struct callout *c"
92 .Fn callout_deactivate "struct callout *c"
93 .Sh DESCRIPTION
94 The function
95 .Fn timeout
96 schedules a call to the function given by the argument
97 .Fa func
98 to take place after
99 .Fa ticks Ns No /hz
100 seconds.
101 Non-positive values of
102 .Fa ticks
103 are silently converted to the value
104 .Sq 1 .
105 .Fa func
106 should be a pointer to a function that takes a
107 .Fa void *
108 argument.
109 Upon invocation,
110 .Fa func
111 will receive
112 .Fa arg
113 as its only argument.
114 The return value from
115 .Fn timeout
116 is a
117 .Ft struct callout_handle
118 which can be used in conjunction with the
119 .Fn untimeout
120 function to request that a scheduled timeout be canceled.
121 The
122 .Fn timeout
123 call is the old style and new code should use the
124 .Fn callout_*
125 functions.
126 .Pp
127 The function
128 .Fn callout_handle_init
129 can be used to initialize a handle to a state which will cause
130 any calls to
131 .Fn untimeout
132 with that handle to return with no side
133 effects.
134 .Pp
135 Assigning a callout handle the value of
136 .Fn CALLOUT_HANDLE_INITIALIZER
137 performs the same function as
138 .Fn callout_handle_init
139 and is provided for use on statically declared or global callout handles.
140 .Pp
141 The function
142 .Fn untimeout
143 cancels the timeout associated with
144 .Fa handle
145 using the
146 .Fa func
147 and
148 .Fa arg
149 arguments to validate the handle.
150 If the handle does not correspond to a timeout with
151 the function
152 .Fa func
153 taking the argument
154 .Fa arg
155 no action is taken.
156 .Fa handle
157 must be initialized by a previous call to
158 .Fn timeout ,
159 .Fn callout_handle_init ,
160 or assigned the value of
161 .Fn CALLOUT_HANDLE_INITIALIZER "&handle"
162 before being passed to
163 .Fn untimeout .
164 The behavior of calling
165 .Fn untimeout
166 with an uninitialized handle
167 is undefined.
168 The
169 .Fn untimeout
170 call is the old style and new code should use the
171 .Fn callout_*
172 functions.
173 .Pp
174 As handles are recycled by the system, it is possible (although unlikely)
175 that a handle from one invocation of
176 .Fn timeout
177 may match the handle of another invocation of
178 .Fn timeout
179 if both calls used the same function pointer and argument, and the first
180 timeout is expired or canceled before the second call.
181 The timeout facility offers O(1) running time for
182 .Fn timeout
183 and
184 .Fn untimeout .
185 Timeouts are executed from
186 .Fn softclock
187 with the
188 .Va Giant
189 lock held.
190 Thus they are protected from re-entrancy.
191 .Pp
192 The functions
193 .Fn callout_init ,
194 .Fn callout_init_mtx ,
195 .Fn callout_init_rw ,
196 .Fn callout_stop ,
197 .Fn callout_drain ,
198 .Fn callout_reset
199 and
200 .Fn callout_schedule
201 are low-level routines for clients who wish to allocate their own
202 callout structures.
203 .Pp
204 The function
205 .Fn callout_init
206 initializes a callout so it can be passed to
207 .Fn callout_stop ,
208 .Fn callout_drain ,
209 .Fn callout_reset
210 or
211 .Fn callout_schedule
212 without any side effects.
213 If the
214 .Fa mpsafe
215 argument is zero,
216 the callout structure is not considered to be
217 .Dq multi-processor safe ;
218 that is,
219 the Giant lock will be acquired before calling the callout function,
220 and released when the callout function returns.
221 .Pp
222 The
223 .Fn callout_init_mtx
224 function may be used as an alternative to
225 .Fn callout_init .
226 The parameter
227 .Fa mtx
228 specifies a mutex that is to be acquired by the callout subsystem
229 before calling the callout function, and released when the callout
230 function returns.
231 The following
232 .Fa flags
233 may be specified:
234 .Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED"
235 .It Dv CALLOUT_RETURNUNLOCKED
236 The callout function will release
237 .Fa mtx
238 itself, so the callout subsystem should not attempt to unlock it
239 after the callout function returns.
240 .El
241 .Pp
242 The
243 .Fn callout_init_rw
244 function serves the need of using rwlocks in conujunction with callouts.
245 The function does basically the same as
246 .Fn callout_init_mtx
247 with the possibility of specifying an extra
248 .Fa rw
249 argument.
250 The usable lock classes are currently limited to mutexes and rwlocks,
251 because callout handlers run in softclock swi, so they cannot sleep nor
252 acquire sleepable locks like sx or lockmgr.
253 The following
254 .Fa flags
255 may be specified:
256 .Bl -tag -width ".Dv CALLOUT_SHAREDLOCK"
257 .It Dv CALLOUT_SHAREDLOCK
258 The lock is only acquired in read mode when running the callout handler.
259 It has no effects when used in conjuction with
260 .Fa mtx .
261 .El
262 .Pp
263 The function
264 .Fn callout_stop
265 cancels a callout if it is currently pending.
266 If the callout is pending, then
267 .Fn callout_stop
268 will return a non-zero value.
269 If the callout is not set, has already been serviced or is currently
270 being serviced, then zero will be returned.
271 If the callout has an associated mutex, then that mutex must be
272 held when this function is called.
273 .Pp
274 The function
275 .Fn callout_drain
276 is identical to
277 .Fn callout_stop
278 except that it will wait for the callout to be completed if it is
279 already in progress.
280 This function MUST NOT be called while holding any
281 locks on which the callout might block, or deadlock will result.
282 Note that if the callout subsystem has already begun processing this
283 callout, then the callout function may be invoked during the execution of
284 .Fn callout_drain .
285 However, the callout subsystem does guarantee that the callout will be
286 fully stopped before
287 .Fn callout_drain
288 returns.
289 .Pp
290 The function
291 .Fn callout_reset
292 first performs the equivalent of
293 .Fn callout_stop
294 to disestablish the callout, and then establishes a new callout in the
295 same manner as
296 .Fn timeout .
297 If there was already a pending callout and it was rescheduled, then
298 .Fn callout_reset
299 will return a non-zero value.
300 If the callout has an associated mutex, then that mutex must be
301 held when this function is called.
302 The function
303 .Fn callout_schedule
304 (re)schedules an existing callout for a new period of time;
305 it is equivalent to calling
306 .Fn callout_reset
307 with the
308 .Fa func
309 and
310 .Fa arg
311 parameters extracted from the callout structure (though possibly with
312 lower overhead).
313 .Pp
314 The macros
315 .Fn callout_pending ,
316 .Fn callout_active
317 and
318 .Fn callout_deactivate
319 provide access to the current state of the callout.
320 Careful use of these macros can avoid many of the race conditions
321 that are inherent in asynchronous timer facilities; see
322 .Sx "Avoiding Race Conditions"
323 below for further details.
324 The
325 .Fn callout_pending
326 macro checks whether a callout is
327 .Em pending ;
328 a callout is considered
329 .Em pending
330 when a timeout has been set but the time has not yet arrived.
331 Note that once the timeout time arrives and the callout subsystem
332 starts to process this callout,
333 .Fn callout_pending
334 will return
335 .Dv FALSE
336 even though the callout function may not have finished (or even begun)
337 executing.
338 The
339 .Fn callout_active
340 macro checks whether a callout is marked as
341 .Em active ,
342 and the
343 .Fn callout_deactivate
344 macro clears the callout's
345 .Em active
346 flag.
347 The callout subsystem marks a callout as
348 .Em active
349 when a timeout is set and it clears the
350 .Em active
351 flag in
352 .Fn callout_stop
353 and
354 .Fn callout_drain ,
355 but it
356 .Em does not
357 clear it when a callout expires normally via the execution of the
358 callout function.
359 .Ss "Avoiding Race Conditions"
360 The callout subsystem invokes callout functions from its own timer
361 context.
362 Without some kind of synchronization it is possible that a callout
363 function will be invoked concurrently with an attempt to stop or reset
364 the callout by another thread.
365 In particular, since callout functions typically acquire a mutex as
366 their first action, the callout function may have already been invoked,
367 but be blocked waiting for that mutex at the time that another thread
368 tries to reset or stop the callout.
369 .Pp
370 The callout subsystem provides a number of mechanisms to address these
371 synchronization concerns:
372 .Bl -enum -offset indent
373 .It
374 If the callout has an associated mutex that was specified using the
375 .Fn callout_init_mtx
376 function (or implicitly specified as the
377 .Va Giant
378 mutex using
379 .Fn callout_init
380 with
381 .Fa mpsafe
382 set to
383 .Dv FALSE ) ,
384 then this mutex is used to avoid the race conditions.
385 The associated mutex must be acquired by the caller before calling
386 .Fn callout_stop
387 or
388 .Fn callout_reset
389 and it is guaranteed that the callout will be correctly stopped
390 or reset as expected.
391 Note that it is still necessary to use
392 .Fn callout_drain
393 before destroying the callout or its associated mutex.
394 .It
395 The return value from
396 .Fn callout_stop
397 and
398 .Fn callout_reset
399 indicates whether or not the callout was removed.
400 If it is known that the callout was set and the callout function has
401 not yet executed, then a return value of
402 .Dv FALSE
403 indicates that the callout function is about to be called.
404 For example:
405 .Bd -literal -offset indent
406 if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) {
407 if (callout_stop(&sc->sc_callout)) {
408 sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING;
409 /* successfully stopped */
410 } else {
411 /*
412 * callout has expired and callout
413 * function is about to be executed
414 */
415 }
416 }
417 .Ed
418 .It
419 The
420 .Fn callout_pending ,
421 .Fn callout_active
422 and
423 .Fn callout_deactivate
424 macros can be used together to work around the race conditions.
425 When a callout's timeout is set, the callout subsystem marks the
426 callout as both
427 .Em active
428 and
429 .Em pending .
430 When the timeout time arrives, the callout subsystem begins processing
431 the callout by first clearing the
432 .Em pending
433 flag.
434 It then invokes the callout function without changing the
435 .Em active
436 flag, and does not clear the
437 .Em active
438 flag even after the callout function returns.
439 The mechanism described here requires the callout function itself to
440 clear the
441 .Em active
442 flag using the
443 .Fn callout_deactivate
444 macro.
445 The
446 .Fn callout_stop
447 and
448 .Fn callout_drain
449 functions always clear both the
450 .Em active
451 and
452 .Em pending
453 flags before returning.
454 .Pp
455 The callout function should first check the
456 .Em pending
457 flag and return without action if
458 .Fn callout_pending
459 returns
460 .Dv TRUE .
461 This indicates that the callout was rescheduled using
462 .Fn callout_reset
463 just before the callout function was invoked.
464 If
465 .Fn callout_active
466 returns
467 .Dv FALSE
468 then the callout function should also return without action.
469 This indicates that the callout has been stopped.
470 Finally, the callout function should call
471 .Fn callout_deactivate
472 to clear the
473 .Em active
474 flag.
475 For example:
476 .Bd -literal -offset indent
477 mtx_lock(&sc->sc_mtx);
478 if (callout_pending(&sc->sc_callout)) {
479 /* callout was reset */
480 mtx_unlock(&sc->sc_mtx);
481 return;
482 }
483 if (!callout_active(&sc->sc_callout)) {
484 /* callout was stopped */
485 mtx_unlock(&sc->sc_mtx);
486 return;
487 }
488 callout_deactivate(&sc->sc_callout);
489 /* rest of callout function */
490 .Ed
491 .Pp
492 Together with appropriate synchronization, such as the mutex used above,
493 this approach permits the
494 .Fn callout_stop
495 and
496 .Fn callout_reset
497 functions to be used at any time without races.
498 For example:
499 .Bd -literal -offset indent
500 mtx_lock(&sc->sc_mtx);
501 callout_stop(&sc->sc_callout);
502 /* The callout is effectively stopped now. */
503 .Ed
504 .Pp
505 If the callout is still pending then these functions operate normally,
506 but if processing of the callout has already begun then the tests in
507 the callout function cause it to return without further action.
508 Synchronization between the callout function and other code ensures that
509 stopping or resetting the callout will never be attempted while the
510 callout function is past the
511 .Fn callout_deactivate
512 call.
513 .Pp
514 The above technique additionally ensures that the
515 .Em active
516 flag always reflects whether the callout is effectively enabled or
517 disabled.
518 If
519 .Fn callout_active
520 returns false, then the callout is effectively disabled, since even if
521 the callout subsystem is actually just about to invoke the callout
522 function, the callout function will return without action.
523 .El
524 .Pp
525 There is one final race condition that must be considered when a
526 callout is being stopped for the last time.
527 In this case it may not be safe to let the callout function itself
528 detect that the callout was stopped, since it may need to access
529 data objects that have already been destroyed or recycled.
530 To ensure that the callout is completely finished, a call to
531 .Fn callout_drain
532 should be used.
533 .Sh RETURN VALUES
534 The
535 .Fn timeout
536 function returns a
537 .Ft struct callout_handle
538 that can be passed to
539 .Fn untimeout .
540 The
541 .Fn callout_stop
542 and
543 .Fn callout_drain
544 functions return non-zero if the callout was still pending when it was
545 called or zero otherwise.
546 .Sh HISTORY
547 The current timeout and untimeout routines are based on the work of
548 .An Adam M. Costello
549 and
550 .An George Varghese ,
551 published in a technical report entitled
552 .%T "Redesigning the BSD Callout and Timer Facilities"
553 and modified slightly for inclusion in
554 .Fx
555 by
556 .An Justin T. Gibbs .
557 The original work on the data structures used in this implementation
558 was published by
559 .An G. Varghese
560 and
561 .An A. Lauck
562 in the paper
563 .%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility"
564 in the
565 .%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" .
566 The current implementation replaces the long standing
567 .Bx
568 linked list
569 callout mechanism which offered O(n) insertion and removal running time
570 but did not generate or require handles for untimeout operations.