TIMEOUT_SET(9)

👑 TIMEOUT_SET(9) 👑

okay so this is TIMEOUT_SET(9) from the Kernel Developer's Manual, and it's literally the kernel's "run this function later" manual. bestie, it's giving future-scheduler energy 🕰️✨

---

💖 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. periodt. 🕰️💅

---

✨ 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 🦋

okay so the timeout subsystem is the part of the kernel that schedules functions to run asynchronously in the future. it's lowkey iconic 🕰️✨

All the state lives inside a struct timeout that you, the caller, allocate. You gotta initialize a timeout before you feed it to any other function in this API. Once it's initialized, you don't need to reinitialize it unless its function or argument must change. 🫶

The timeout_set() function initializes to. When the timeout is executed, the function fn gets 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. cute and simple 💖

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 these:
  • 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 these 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. she's fancy like that 💅

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. yes bestie, the clock choice matters 🎀

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. math girlie behavior 🔥

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. no drama, just quiet superseding 💀

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. patient queen behavior ⏳

The timeout_barrier() function blocks until any current execution of the given timeout has completed. yes, it waits. respectfully. 🧚

⚠️ deadlock alert: 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. no cap, that's the scary part 😭

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().

⚠️ bestie, this macro must not be used unless the memory pointed to by to has been zeroed, or its return value is meaningless. don't skip the zeroing step 🙈

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. the guest list is long and inclusive 💖

timeout_barrier() and timeout_del_barrier() may only be called from process context. sorry, interrupt girlies, not these two 💅

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. say it louder for the back row 📣

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. 📚✨

---

and that's the whole page, bestie — source/version: Debian, date: May 23, 2025, and the manual page is TIMEOUT_SET(9). slay 🎀💖