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
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
|
.\" $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 September 14, 2015
.Dt TIMEOUT 9
.Os
.Sh NAME
.Nm callout_active ,
.Nm callout_deactivate ,
.Nm callout_drain ,
.Nm callout_handle_init ,
.Nm callout_init ,
.Nm callout_init_mtx ,
.Nm callout_init_rm ,
.Nm callout_init_rw ,
.Nm callout_pending ,
.Nm callout_reset ,
.Nm callout_reset_curcpu ,
.Nm callout_reset_on ,
.Nm callout_reset_sbt ,
.Nm callout_reset_sbt_curcpu ,
.Nm callout_reset_sbt_on ,
.Nm callout_schedule ,
.Nm callout_schedule_curcpu ,
.Nm callout_schedule_on ,
.Nm callout_schedule_sbt ,
.Nm callout_schedule_sbt_curcpu ,
.Nm callout_schedule_sbt_on ,
.Nm callout_stop ,
.Nm timeout ,
.Nm untimeout
.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 int
.Fn callout_active "struct callout *c"
.Ft void
.Fn callout_deactivate "struct callout *c"
.Ft int
.Fn callout_drain "struct callout *c"
.Ft void
.Fn callout_handle_init "struct callout_handle *handle"
.Bd -literal
struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle);
.Ed
.Ft void
.Fn callout_init "struct callout *c" "int mpsafe"
.Ft void
.Fn callout_init_mtx "struct callout *c" "struct mtx *mtx" "int flags"
.Ft 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_pending "struct callout *c"
.Ft int
.Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg"
.Ft int
.Fn callout_reset_curcpu "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 "struct callout *c" "sbintime_t sbt" \
"sbintime_t pr" "timeout_t *func" "void *arg" "int flags"
.Ft int
.Fn callout_reset_sbt_curcpu "struct callout *c" "sbintime_t sbt" \
"sbintime_t pr" "timeout_t *func" "void *arg" "int flags"
.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_schedule "struct callout *c" "int ticks"
.Ft int
.Fn callout_schedule_curcpu "struct callout *c" "int ticks"
.Ft int
.Fn callout_schedule_on "struct callout *c" "int ticks" "int cpu"
.Ft int
.Fn callout_schedule_sbt "struct callout *c" "sbintime_t sbt" \
"sbintime_t pr" "int flags"
.Ft int
.Fn callout_schedule_sbt_curcpu "struct callout *c" "sbintime_t sbt" \
"sbintime_t pr" "int flags"
.Ft int
.Fn callout_schedule_sbt_on "struct callout *c" "sbintime_t sbt" \
"sbintime_t pr" "int cpu" "int flags"
.Ft int
.Fn callout_stop "struct callout *c"
.Ft struct callout_handle
.Fn timeout "timeout_t *func" "void *arg" "int ticks"
.Ft void
.Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle"
.Sh DESCRIPTION
The
.Nm callout
API is used to schedule a call to an arbitrary function at a specific
time in the future.
Consumers of this API are required to allocate a callout structure
.Pq struct callout
for each pending function invocation.
This structure stores state about the pending function invocation including
the function to be called and the time at which the function should be invoked.
Pending function calls can be cancelled or rescheduled to a different time.
In addition,
a callout structure may be reused to schedule a new function call after a
scheduled call is completed.
.Pp
Callouts only provide a single-shot mode.
If a consumer requires a periodic timer,
it must explicitly reschedule each function call.
This is normally done by rescheduling the subsequent call within the called
function.
.Pp
Callout functions must not sleep.
They may not acquire sleepable locks,
wait on condition variables,
perform blocking allocation requests,
or invoke any other action that might sleep.
.Pp
Each callout structure must be initialized by
.Fn callout_init ,
.Fn callout_init_mtx ,
.Fn callout_init_rm ,
or
.Fn callout_init_rw
before it is passed to any of the other callout functions.
The
.Fn callout_init
function initializes a callout structure in
.Fa c
that is not associated with a specific lock.
If the
.Fa mpsafe
argument is zero,
the callout structure is not considered to be
.Dq multi-processor safe ;
and the Giant lock will be acquired before calling the callout function
and released when the callout function returns.
.Pp
The
.Fn callout_init_mtx ,
.Fn callout_init_rm ,
and
.Fn callout_init_rw
functions initialize a callout structure in
.Fa c
that is associated with a specific lock.
The lock is specified by the
.Fa mtx ,
.Fa rm ,
or
.Fa rw
parameter.
The associated lock must be held while stopping or rescheduling the
callout.
The callout subsystem acquires the associated lock before calling the
callout function and releases it after the function returns.
If the callout was cancelled while the callout subsystem waited for the
associated lock,
the callout function is not called,
and the associated lock is released.
This ensures that stopping or rescheduling the callout will abort any
previously scheduled invocation.
.Pp
Only regular mutexes may be used with
.Fn callout_init_mtx ;
spin mutexes are not supported.
A sleepable read-mostly lock
.Po
one initialized with the
.Dv RM_SLEEPABLE
flag
.Pc
may not be used with
.Fn callout_init_rm .
Similarly, other sleepable lock types such as
.Xr sx 9
and
.Xr lockmgr 9
cannot be used with callouts because sleeping is not permitted in
the callout subsystem.
.Pp
These
.Fa flags
may be specified for
.Fn callout_init_mtx ,
.Fn callout_init_rm ,
or
.Fn callout_init_rw :
.Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED"
.It Dv CALLOUT_RETURNUNLOCKED
The callout function will release the associated lock itself,
so the callout subsystem should not attempt to unlock it
after the callout function returns.
.It Dv CALLOUT_SHAREDLOCK
The lock is only acquired in read mode when running the callout handler.
This flag is ignored by
.Fn callout_init_mtx .
.El
.Pp
The function
.Fn callout_stop
cancels a callout
.Fa c
if it is currently pending.
If the callout is pending, then
.Fn callout_stop
returns 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 lock,
then that lock 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
.Fa c
to complete 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 before
.Fn callout_drain
returns.
However, the callout subsystem does guarantee that the callout will be
fully stopped before
.Fn callout_drain
returns.
.Pp
The
.Fn callout_reset
and
.Fn callout_schedule
function families schedule a future function invocation for callout
.Fa c .
If
.Fa c
already has a pending callout,
it is cancelled before the new invocation is scheduled.
These functions return a non-zero value if a pending callout was cancelled
and zero if there was no pending callout.
If the callout has an associated lock,
then that lock must be held when any of these functions are called.
.Pp
The time at which the callout function will be invoked is determined by
either the
.Fa ticks
argument or the
.Fa sbt ,
.Fa pr ,
and
.Fa flags
arguments.
When
.Fa ticks
is used,
the callout is scheduled to execute after
.Fa ticks Ns No /hz
seconds.
Non-positive values of
.Fa ticks
are silently converted to the value
.Sq 1 .
.Pp
The
.Fa sbt ,
.Fa pr ,
and
.Fa flags
arguments provide more control over the scheduled time including
support for higher resolution times,
specifying the precision of the scheduled time,
and setting an absolute deadline instead of a relative timeout.
The callout is scheduled to execute in a time window which begins at
the time specified in
.Fa sbt
and extends for the amount of time specified in
.Fa pr .
If
.Fa sbt
specifies a time in the past,
the window is adjusted to start at the current time.
A non-zero value for
.Fa pr
allows the callout subsystem to coalesce callouts scheduled close to each
other into fewer timer interrupts,
reducing processing overhead and power consumption.
These
.Fa flags
may be specified to adjust the interpretation of
.Fa sbt
and
.Fa pr :
.Bl -tag -width ".Dv C_DIRECT_EXEC"
.It Dv C_ABSOLUTE
Handle the
.Fa sbt
argument as an absolute time since boot.
By default,
.Fa sbt
is treated as a relative amount of time,
similar to
.Fa ticks .
.It Dv C_DIRECT_EXEC
Run the handler directly from hardware interrupt context instead of from the
softclock thread.
This reduces latency and overhead, but puts more constraints on the callout
function.
Callout functions run in this context may use only spin mutexes for locking
and should be as small as possible 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.
Note that the larger of
.Fa pr
or this value is used as the length of the time window.
Smaller values
.Pq which result in larger time intervals
allow the callout subsystem to aggregate more events in one timer interrupt.
.It Dv C_HARDCLOCK
Align the timeouts to
.Fn hardclock
calls if possible.
.El
.Pp
The
.Fn callout_reset
functions accept a
.Fa func
argument which identifies the function to be called when the time expires.
It must be a pointer to a function that takes a single
.Fa void *
argument.
Upon invocation,
.Fa func
will receive
.Fa arg
as its only argument.
The
.Fn callout_schedule
functions reuse the
.Fa func
and
.Fa arg
arguments from the previous callout.
Note that one of the
.Fn callout_reset
functions must always be called to initialize
.Fa func
and
.Fa arg
before one of the
.Fn callout_schedule
functions can be used.
.Pp
The callout subsystem provides a softclock thread for each CPU in the system.
Callouts are assigned to a single CPU and are executed by the softclock thread
for that CPU.
Initially,
callouts are assigned to CPU 0.
The
.Fn callout_reset_on ,
.Fn callout_reset_sbt_on ,
.Fn callout_schedule_on
and
.Fn callout_schedule_sbt_on
functions assign the callout to CPU
.Fa cpu .
The
.Fn callout_reset_curcpu ,
.Fn callout_reset_sbt_curpu ,
.Fn callout_schedule_curcpu
and
.Fn callout_schedule_sbt_curcpu
functions assign the callout to the current CPU.
The
.Fn callout_reset ,
.Fn callout_reset_sbt ,
.Fn callout_schedule
and
.Fn callout_schedule_sbt
functions schedule the callout to execute in the softclock thread of the CPU
to which it is currently assigned.
.Pp
Softclock threads are not pinned to their respective CPUs by default.
The softclock thread for CPU 0 can be pinned to CPU 0 by setting the
.Va kern.pin_default_swi
loader tunable to a non-zero value.
Softclock threads for CPUs other than zero can be pinned to their
respective CPUs by setting the
.Va kern.pin_pcpu_swi
loader tunable to a non-zero value.
.Pp
The macros
.Fn callout_pending ,
.Fn callout_active
and
.Fn callout_deactivate
provide access to the current state of the callout.
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
.Pq 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 thread
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 lock as
their first action, the callout function may have already been invoked,
but is blocked waiting for that lock at the time that another thread
tries to reset or stop the callout.
.Pp
There are three main techniques for addressing these
synchronization concerns.
The first approach is preferred as it is the simplest:
.Bl -enum -offset indent
.It
Callouts can be associated with a specific lock when they are initialized
by
.Fn callout_init_mtx ,
.Fn callout_init_rm ,
or
.Fn callout_init_rw .
When a callout is associated with a lock,
the callout subsystem acquires the lock before the callout function is
invoked.
This allows the callout subsystem to transparently handle races between
callout cancellation,
scheduling,
and execution.
Note that the associated lock must be acquired before calling
.Fn callout_stop
or one of the
.Fn callout_reset
or
.Fn callout_schedule
functions to provide this safety.
.Pp
A callout initialized via
.Fn callout_init
with
.Fa mpsafe
set to zero is implicitly associated with the
.Va Giant
mutex.
If
.Va Giant
is held when cancelling or rescheduling the callout,
then its use will prevent races with the callout function.
.It
The return value from
.Fn callout_stop
.Po
or the
.Fn callout_reset
and
.Fn callout_schedule
function families
.Pc
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.
In particular,
a callout should always be drained prior to destroying its associated lock
or releasing the storage for the callout structure.
.Sh LEGACY API
.Bf Sy
The functions below are a legacy API that will be removed in a future release.
New code should not use these routines.
.Ef
.Pp
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.
.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.
.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.
.Sh RETURN VALUES
The
.Fn callout_active
macro returns the state of a callout's
.Em active
flag.
.Pp
The
.Fn callout_pending
macro returns the state of a callout's
.Em pending
flag.
.Pp
The
.Fn callout_reset
and
.Fn callout_schedule
function families return non-zero if the callout was pending before the new
function invocation was scheduled.
.Pp
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.
The
.Fn timeout
function returns a
.Ft struct callout_handle
that can be passed to
.Fn untimeout .
.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.
|