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