TIMEOUT_SET(9) | Kernel Developer's Manual | TIMEOUT_SET(9)

# NAME

`timeout_set`, `timeout_set_flags`, `timeout_set_proc`, `timeout_add`, `timeout_add_sec`, `timeout_add_msec`, `timeout_add_usec`, `timeout_add_nsec`, `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_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`(), or `timeout_add_nsec`(). 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_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`(), 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.

May 23, 2025 | Debian