NAME
timeout_set
,
timeout_set_flags
,
timeout_set_proc
,
timeout_add
,
timeout_add_sec
,
timeout_add_msec
,
timeout_add_usec
,
timeout_add_nsec
,
timeout_add_tv
,
timeout_abs_ts
, timeout_del
,
timeout_del_barrier
,
timeout_barrier
,
timeout_pending
,
timeout_initialized
,
timeout_triggered
,
TIMEOUT_INITIALIZER
,
TIMEOUT_INITIALIZER_FLAGS
—
execute a function in the
future
SYNOPSIS
#include
<sys/types.h>
#include <sys/timeout.h>
void
timeout_set
(struct timeout *to,
void (*fn)(void *), void
*arg);
void
timeout_set_flags
(struct timeout
*to, void (*fn)(void *), void
*arg, int kclock, int
flags);
void
timeout_set_proc
(struct timeout
*to, void (*fn)(void *), void
*arg);
int
timeout_add
(struct timeout *to,
int nticks);
int
timeout_add_sec
(struct timeout
*to, int secs);
int
timeout_add_msec
(struct timeout
*to, int msecs);
int
timeout_add_usec
(struct timeout
*to, int usecs);
int
timeout_add_nsec
(struct timeout
*to, int nsecs);
int
timeout_add_tv
(struct timeout
*to, struct timeval *tv);
int
timeout_abs_ts
(struct timeout
*to, const struct timespec *abs);
int
timeout_del
(struct timeout
*to);
int
timeout_del_barrier
(struct timeout
*to);
void
timeout_barrier
(struct timeout
*to);
int
timeout_pending
(struct timeout
*to);
int
timeout_initialized
(struct timeout
*to);
int
timeout_triggered
(struct timeout
*to);
TIMEOUT_INITIALIZER
(void
(*fn)(void *), void *arg);
TIMEOUT_INITIALIZER_FLAGS
(void
(*fn)(void *), void *arg, int
kclock, int flags);
DESCRIPTION
The timeout
subsystem schedules functions
for asynchronous execution in the future.
All state is encapsulated in a struct timeout allocated by the caller. A timeout must be initialized before it may be used as input to other functions in the API. Once initialized, a timeout does not need to be reinitialized unless its function or argument must change.
The
timeout_set
()
function initializes the timeout to. When the timeout
is executed, the function fn will be called with
arg as its sole parameter. The timeout is implicitly
scheduled against the KCLOCK_NONE
clock and is not
configured with any additional flags.
The
timeout_set_flags
()
function is similar to timeout_set
(), except that it
takes two additional parameters:
- kclock
- The timeout is scheduled against the given kclock,
which must be one of the following:
KCLOCK_NONE
- Low resolution tick-based clock. The granularity of this clock is limited by the hardclock(9), which executes roughly hz(9) times per second.
KCLOCK_UPTIME
- The uptime clock. Counts the time elapsed since the system booted.
- flags
- The timeout's behavior may be configured with the bitwise OR of zero or
more of the following flags:
TIMEOUT_PROC
- Execute the timeout in a process context instead of the default
IPL_SOFTCLOCK
interrupt context.
The
timeout_set_proc
()
function is similar to timeout_set
(), except that
the given timeout is configured with the
TIMEOUT_PROC
flag.
A timeout may also be initialized
statically. The
TIMEOUT_INITIALIZER
()
macro is equivalent to the timeout_set
() function
and the
TIMEOUT_INITIALIZER_FLAGS
()
macro is equivalent to the timeout_set_flags
()
function.
The interfaces available for scheduling a timeout vary with the kclock set during initialization.
KCLOCK_NONE
timeouts may
be scheduled with the function
timeout_add
(),
which schedules the given timeout to execute after at least
nticks
hardclock(9) ticks have elapsed. In practice,
nticks ticks will usually elapse in slightly less than
(nticks /
hz
) seconds. Negative values of
nticks are illegal. If nticks is
zero it will be silently rounded up to one.
For convenience,
KCLOCK_NONE
timeouts may also be scheduled with
timeout_add_sec
(),
timeout_add_msec
(),
timeout_add_usec
(),
timeout_add_nsec
(),
or
timeout_add_tv
().
These wrapper functions convert their input durations to a count of
hardclock(9) ticks before calling
timeout_add
() to schedule the given timeout.
Timeouts for any other
kclock may be scheduled with
timeout_abs_ts
(),
which schedules the given timeout to execute at or after the absolute time
abs has elapsed on the timeout's
kclock.
Once scheduled, a timeout is said to be
"pending". A pending timeout may not be reinitialized with
timeout_set
(),
timeout_set_flags
(), or
timeout_set_proc
() until it has been executed or it
has been cancelled with timeout_del
() or
timeout_del_barrier
(). A pending timeout may be
rescheduled without first cancelling it with
timeout_del
() or
timeout_del_barrier
(): the new expiration time will
quietly supersede the original.
The function
timeout_del
()
cancels any pending execution of the given timeout.
The
timeout_del_barrier
()
function is similar to timeout_del
(), except that it
also blocks until any current execution of the given timeout has
completed.
The
timeout_barrier
()
function blocks until any current execution of the given timeout has
completed.
Callers of
timeout_barrier
()
and timeout_del_barrier
() must not hold locks that
can block processing in the timeout's context. Otherwise, the system will
deadlock.
The
timeout_pending
()
macro indicates whether the given timeout is scheduled for execution. A
timeout's pending status is cleared when it executes or is cancelled.
The
timeout_initialized
()
macro indicates whether the given timeout has been initialized with
timeout_set
() or
timeout_set_flags
(). This macro must not be used
unless the memory pointed to by to has been zeroed, or
its return value is meaningless.
The
timeout_triggered
()
macro indicates whether the given timeout is executing or has finished
executing. Rescheduling or cancelling a timeout clears its triggered
status.
CONTEXT
timeout_set
(),
timeout_set_flags
(),
timeout_set_proc
(),
timeout_add
(),
timeout_add_sec
(),
timeout_add_msec
(),
timeout_add_usec
(),
timeout_add_nsec
(),
timeout_add_tv
(),
timeout_abs_ts
(),
timeout_del
(),
timeout_pending
(),
timeout_initialized
(), and
timeout_triggered
() may be called during autoconf,
from process context, or from any interrupt context.
timeout_barrier
() and
timeout_del_barrier
() may only be called from
process context.
When a timeout is executed, the function fn
set during initialization is called from the
IPL_SOFTCLOCK
interrupt context, or a process
context if the timeout was configured with the
TIMEOUT_PROC
flag. The function
fn must not block and must be safe to execute on any
CPU in the system.
Currently, all timeouts are executed under the kernel lock.
RETURN VALUES
timeout_add
(),
timeout_add_sec
(),
timeout_add_msec
(),
timeout_add_usec
(),
timeout_add_nsec
(),
timeout_add_tv
(), and
timeout_abs_ts
() return 1 if the timeout
to is newly scheduled, or zero if the timeout was
already pending.
timeout_del
() and
timeout_del_barrier
() return 1 if the timeout
to was pending, or zero otherwise.
timeout_pending
(),
timeout_initialized
(), and
timeout_triggered
() return non-zero if the
corresponding condition is true, or zero otherwise.
CODE REFERENCES
sys/kern/kern_timeout.c
SEE ALSO
hardclock(9), hz(9), microtime(9), splclock(9), task_add(9), tsleep(9), tvtohz(9)
George Varghese and Anthony Lauck, Hashed and hierarchical timing wheels: efficient data structures for implementing a timer facility, IEEE/ACM, Transactions on Networking, no. 6, vol. 5, pp. 824–834, December 1997, especially Schemes 6 and 7.