OpenBSD manual page server

Manual Page Search Parameters
TIMEOUT_SET(9) Kernel Developer's Manual TIMEOUT_SET(9)

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

#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);

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 () 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 () 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:
Low resolution tick-based clock. The granularity of this clock is limited by the hardclock(9), which executes roughly hz(9) times per second.
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:
Execute the timeout in a process context instead of the default IPL_SOFTCLOCK interrupt context.
Execute the timeout without the kernel lock. Requires the TIMEOUT_PROC flag.

The () 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 () macro is equivalent to the timeout_set() function and the () 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 (), 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 (), (), (), (), or (). 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 (), 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_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 () cancels any pending execution of the given timeout.

The () function is similar to timeout_del(), except that it also blocks until any current execution of the given timeout has completed.

The () function blocks until any current execution of the given timeout has completed.

Callers of () and timeout_del_barrier() must not hold locks that can block processing in the timeout's context. Otherwise, the system will deadlock.

The () macro indicates whether the given timeout is scheduled for execution. A timeout's pending status is cleared when it executes or is cancelled.

The () 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 () macro indicates whether the given timeout is executing or has finished executing. Rescheduling or cancelling a timeout clears its triggered status.

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.

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.

sys/kern/kern_timeout.c

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.

August 11, 2024 OpenBSD-7.6