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, uint64_t msecs);

int
timeout_add_usec(struct timeout *to, uint64_t usecs);

int
timeout_add_nsec(struct timeout *to, uint64_t 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.

TIMEOUT_MPSAFE

Execute the timeout without the kernel lock. Requires the TIMEOUT_PROC flag.

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.

Timeouts without the TIMEOUT_MPSAFE flag 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.