CALLOUT(9)

🎀 CALLOUT(9) 🎀

okay bestie, this is the CALLOUT(9) page from the Kernel Developer's Manual, and it is literally the blueprint for making the kernel run a function later. Think “set a timer, but make it kernel-core.” 💅

✨ NAME ✨

okay so the whole squad on this page is: callout_active, callout_deactivate, callout_async_drain, callout_drain, callout_init, callout_init_mtx, callout_init_rm, callout_init_rw, callout_pending, callout_reset, callout_reset_curcpu, callout_reset_on, callout_reset_sbt, callout_reset_sbt_curcpu, callout_reset_sbt_on, callout_schedule, callout_schedule_curcpu, callout_schedule_on, callout_schedule_sbt, callout_schedule_sbt_curcpu, callout_schedule_sbt_on, callout_stop, and callout_when — and their whole thing is to execute a function after a specified length of time. periodt. ⏰

🛠️ SYNOPSIS 🛠️

copy-paste energy, but make it exact — these signatures are the actual API:

#include <sys/types.h>
#include <sys/callout.h>

typedef void callout_func_t (void *);

int
callout_active(struct callout *c);

void
callout_deactivate(struct callout *c);

int
callout_async_drain(struct callout *c, callout_func_t *drain);

int
callout_drain(struct callout *c);

void
callout_init(struct callout *c, int mpsafe);

void
callout_init_mtx(struct callout *c, struct mtx *mtx, int flags);

void
callout_init_rm(struct callout *c, struct rmlock *rm, int flags);

void
callout_init_rw(struct callout *c, struct rwlock *rw, int flags);

int
callout_pending(struct callout *c);

int
callout_reset(struct callout *c, int ticks, callout_func_t *func,
    void *arg);

int
callout_reset_curcpu(struct callout *c, int ticks, callout_func_t *func,
    void *arg);

int
callout_reset_on(struct callout *c, int ticks, callout_func_t *func,
    void *arg, int cpu);

int
callout_reset_sbt(struct callout *c, sbintime_t sbt, sbintime_t pr,
    callout_func_t *func, void *arg, int flags);

int
callout_reset_sbt_curcpu(struct callout *c, sbintime_t sbt,
    sbintime_t pr, callout_func_t *func, void *arg, int flags);

int
callout_reset_sbt_on(struct callout *c, sbintime_t sbt, sbintime_t pr,
    callout_func_t *func, void *arg, int cpu, int flags);

int
callout_schedule(struct callout *c, int ticks);

int
callout_schedule_curcpu(struct callout *c, int ticks);

int
callout_schedule_on(struct callout *c, int ticks, int cpu);

int
callout_schedule_sbt(struct callout *c, sbintime_t sbt, sbintime_t pr,
    int flags);

int
callout_schedule_sbt_curcpu(struct callout *c, sbintime_t sbt,
    sbintime_t pr, int flags);

int
callout_schedule_sbt_on(struct callout *c, sbintime_t sbt,
    sbintime_t pr, int cpu, int flags);

int
callout_stop(struct callout *c);

sbintime_t
callout_when(sbintime_t sbt, sbintime_t precision, int flags,
    sbintime_t *sbt_res, sbintime_t *precision_res);

💖 DESCRIPTION 💖

🌸 what even is a callout, bestie

The callout API is used to schedule a call to an arbitrary function at a specific time in the future. Consumers of this API are required to allocate a callout structure (struct callout) for each pending function invocation. This structure stores state about the pending function invocation including the function to be called and the time at which the function should be invoked. Pending function calls can be cancelled or rescheduled to a different time. In addition, a callout structure may be reused to schedule a new function call after a scheduled call is completed.

Callouts only provide a single-shot mode. If a consumer requires a periodic timer, it must explicitly reschedule each function call. This is normally done by rescheduling the subsequent call within the called function. 🔁

Callout functions must not sleep. They may not acquire sleepable locks, wait on condition variables, perform blocking allocation requests, or invoke any other action that might sleep. like, do not do it. 😭

🧵 init era + lock lore

Each callout structure must be initialized by callout_init(), callout_init_mtx(), callout_init_rm(), or callout_init_rw() before it is passed to any of the other callout functions. The callout_init() function initializes a callout structure in c that is not associated with a specific lock. If the mpsafe argument is zero, the callout structure is not considered to be “multi-processor safe”; and the Giant lock will be acquired before calling the callout function and released when the callout function returns.

The callout_init_mtx(), callout_init_rm(), and callout_init_rw() functions initialize a callout structure in c that is associated with a specific lock. The lock is specified by the mtx, rm, or rw parameter. The associated lock must be held while stopping or rescheduling the callout. The callout subsystem acquires the associated lock before calling the callout function and releases it after the function returns. If the callout was cancelled while the callout subsystem waited for the associated lock, the callout function is not called, and the associated lock is released. This ensures that stopping or rescheduling the callout will abort any previously scheduled invocation. 🫶

A sleepable read-mostly lock (one initialized with the RM_SLEEPABLE flag) may not be used with callout_init_rm(). Similarly, other sleepable lock types such as sx(9) and lockmgr(9) cannot be used with callouts because sleeping is not permitted in the callout subsystem. heads up, bestie — no sleepy locks in the callout zone. 💀

These flags may be specified for callout_init_mtx(), callout_init_rm(), or callout_init_rw():

• CALLOUT_RETURNUNLOCKED — The callout function will release the associated lock itself, so the callout subsystem should not attempt to unlock it after the callout function returns.
• CALLOUT_SHAREDLOCK — The lock is only acquired in read mode when running the callout handler. This flag is ignored by callout_init_mtx().

🛑 stop, async_drain & drain energy

The function callout_stop() cancels a callout c if it is currently pending. Return-value tea: if the callout is pending and successfully stopped, then callout_stop() returns a value of one. If the callout is not set, or has already been serviced, then negative one is returned. If the callout is currently being serviced and cannot be stopped, then zero will be returned. If the callout is currently being serviced and cannot be stopped, and at the same time a next invocation of the same callout is also scheduled, then callout_stop() unschedules the next run and returns zero. If the callout has an associated lock, then that lock must be held when this function is called. 🛑

The function callout_async_drain() is identical to callout_stop() with one difference. When callout_async_drain() returns zero it will arrange for the function drain to be called using the same argument given to the callout_reset() function. If the callout has an associated lock, then that lock must be held when this function is called. Note that when stopping multiple callouts that use the same lock it is possible to get multiple returns of zero and multiple calls to the drain function, depending upon which CPU's the callouts are running. The drain function itself is called from the context of the completing callout i.e. softclock or hardclock, just like a callout itself. 🌈

The function callout_drain() is identical to callout_stop() except that it will wait for the callout c to complete if it is already in progress. This function MUST NOT be called while holding any locks on which the callout might block, or deadlock will result. Note that if the callout subsystem has already begun processing this callout, then the callout function may be invoked before callout_drain() returns. However, the callout subsystem does guarantee that the callout will be fully stopped before callout_drain() returns. deadlock is not the vibe. 🙈

⏰ reset & schedule era

The callout_reset() and callout_schedule() function families schedule a future function invocation for callout c. If c already has a pending callout, it is cancelled before the new invocation is scheduled. These functions return a value of one if a pending callout was cancelled and zero if there was no pending callout. If the callout has an associated lock, then that lock must be held when any of these functions are called. 🌀

The time at which the callout function will be invoked is determined by either the ticks argument or the sbt, pr, and flags arguments. When ticks is used, the callout is scheduled to execute after ticks/hz seconds. Non-positive values of ticks are silently converted to the value 1. not me getting quietly converted to 1 😭

The sbt, pr, and flags arguments provide more control over the scheduled time including support for higher resolution times, specifying the precision of the scheduled time, and setting an absolute deadline instead of a relative timeout. The callout is scheduled to execute in a time window which begins at the time specified in sbt and extends for the amount of time specified in pr. If sbt specifies a time in the past, the window is adjusted to start at the current time. A non-zero value for pr allows the callout subsystem to coalesce callouts scheduled close to each other into fewer timer interrupts, reducing processing overhead and power consumption. These flags may be specified to adjust the interpretation of sbt and pr:

• C_ABSOLUTE — Handle the sbt argument as an absolute time since boot. By default, sbt is treated as a relative amount of time, similar to ticks.
• C_DIRECT_EXEC — Run the handler directly from hardware interrupt context instead of from the softclock thread. This reduces latency and overhead, but puts more constraints on the callout function. Callout functions run in this context may use only spin mutexes for locking and should be as small as possible because they run with absolute priority.
• C_PREL() — Specifies relative event time precision as binary logarithm of time interval divided by acceptable time deviation: 1 -- 1/2, 2 -- 1/4, etc. Note that the larger of pr or this value is used as the length of the time window. Smaller values (which result in larger time intervals) allow the callout subsystem to aggregate more events in one timer interrupt.
• C_PRECALC — The sbt argument specifies the absolute time at which the callout should be run, and the pr argument specifies the requested precision, which will not be adjusted during the scheduling process. The sbt and pr values should be calculated by an earlier call to callout_when() which uses the user-supplied sbt, pr, and flags values.
• C_HARDCLOCK — Align the timeouts to hardclock() calls if possible.

Okay so back to the func tea ☕ — the callout_reset() functions take a func argument, and that's literally the function that gets called when the time expires. It must be a pointer to a function that takes a single void * argument, and when it's invoked, func gets arg as its only argument. Cute, right? The callout_schedule() functions are the low-effort girlies — they just reuse the func and arg from the previous callout. But ⚠️ note that one of the callout_reset() functions must always be called to initialize func and arg before any of the callout_schedule() functions can be used. No skipping the setup step, bestie 💅

---

The callout subsystem gives you a softclock thread for each CPU in the system 🌈 Callouts get assigned to a single CPU and are executed by the softclock thread for that CPU. Initially, callouts are assigned to CPU 0. Here's the lineup:

• callout_reset_on(), callout_reset_sbt_on(), callout_schedule_on(), callout_schedule_sbt_on() — assign the callout to CPU cpu.
• callout_reset_curcpu(), callout_reset_sbt_curpu(), callout_schedule_curcpu(), callout_schedule_sbt_curcpu() — assign the callout to the current CPU.
• callout_reset(), callout_reset_sbt(), callout_schedule(), callout_schedule_sbt() — schedule the callout to execute in the softclock thread of the CPU to which it's currently assigned.

Softclock threads are not pinned to their respective CPUs by default, jsyk. But you can pin them:

• The softclock thread for CPU 0 can be pinned to CPU 0 by setting the kern.pin_default_swi loader tunable to a non-zero value.
• Softclock threads for CPUs other than zero can be pinned to their respective CPUs by setting the kern.pin_pcpu_swi loader tunable to a non-zero value.

---

🦋 The state-checking macros

The macros callout_pending(), callout_active() and callout_deactivate() give you access to the current state of the callout, no cap:

• callout_pending() — checks whether a callout is pending. A callout is considered pending when a timeout has been set but the time hasn't arrived yet. 👀 Note: once the timeout time arrives and the callout subsystem starts to process this callout, callout_pending() will return FALSE even though the callout function may not have finished (or even begun) executing. So don't let that trip you up.
• callout_active() — checks whether a callout is marked as active.
• callout_deactivate() — clears the callout's active flag.

The callout subsystem marks a callout as active when a timeout is set, and it clears the active flag in callout_stop() and callout_drain() — but it does not clear it when a callout expires normally via the execution of the callout function. Rude, but okay 💀

---

🌸 callout_when()

The callout_when() function may be used to pre-calculate the absolute time at which the timeout should be run, plus the precision of the scheduled run time — according to the required time sbt, precision precision, and any additional adjustments requested by the flags argument. Flags accepted by callout_when() are the same as flags for callout_reset(). ✨

The resulting time gets assigned to the variable pointed to by the sbt_res argument, and the resulting precision gets assigned to *precision_res.

When you pass the results to callout_reset, add the C_PRECALC flag to flags, to avoid incorrect re-adjustment. Fr fr, don't forget this one.

This function is intended for situations where the precise time of the callout run should be known in advance, since trying to read this time from the callout structure itself after a callout_reset() call is racy. 🙈

---

💜 Avoiding Race Conditions

The callout subsystem invokes callout functions from its own thread context. Without some kind of synchronization, it's possible that a callout function will be invoked concurrently with an attempt to stop or reset the callout by another thread. In particular — since callout functions typically acquire a lock as their first action — the callout function may have already been invoked but is blocked waiting for that lock at the time another thread tries to reset or stop the callout. Messy 😭

There are three main techniques for addressing these synchronization concerns. The first approach is preferred since it's the simplest:

1. Callouts can be associated with a specific lock when they're initialized by callout_init_mtx(), callout_init_rm(), or callout_init_rw(). When a callout is associated with a lock, the callout subsystem acquires the lock before the callout function is invoked. This allows the callout subsystem to transparently handle races between callout cancellation, scheduling, and execution. 🫶

Note that the associated lock must be acquired before calling callout_stop() or one of the callout_reset() or callout_schedule() functions, to provide this safety.

A callout initialized via callout_init() with mpsafe set to zero is implicitly associated with the Giant mutex. If Giant is held when cancelling or rescheduling the callout, then its use will prevent races with the callout function.

2. The return value from callout_stop() (or the callout_reset() and callout_schedule() function families) indicates whether or not the callout was removed. If it's known that the callout was set and the callout function has not yet executed, then a return value of FALSE indicates that the callout function is about to be called. Example time 🎀

if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) {
        if (callout_stop(&sc->sc_callout)) {
                sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING;
                /* successfully stopped */
        } else {
                /*
                 * callout has expired and callout
                 * function is about to be executed
                 */
        }
}

3. The callout_pending(), callout_active() and callout_deactivate() macros can be used together to work around the race conditions. When a callout's timeout is set, the callout subsystem marks the callout as both active and pending. When the timeout time arrives, the callout subsystem begins processing the callout by first clearing the pending flag. It then invokes the callout function without changing the active flag, and does not clear the active flag even after the callout function returns. The mechanism described here requires the callout function itself to clear the active flag using the callout_deactivate() macro. The callout_stop() and callout_drain() functions always clear both the active and pending flags before returning. 👑

The callout function should first check the pending flag and return without action if callout_pending() returns TRUE. This indicates that the callout was rescheduled using callout_reset() just before the callout function was invoked. If callout_active() returns FALSE then the callout function should also return without action — this indicates that the callout has been stopped. Finally, the callout function should call callout_deactivate() to clear the active flag. Like so:

mtx_lock(&sc->sc_mtx);
if (callout_pending(&sc->sc_callout)) {
        /* callout was reset */
        mtx_unlock(&sc->sc_mtx);
        return;
}
if (!callout_active(&sc->sc_callout)) {
        /* callout was stopped */
        mtx_unlock(&sc->sc_mtx);
        return;
}
callout_deactivate(&sc->sc_callout);
/* rest of callout function */

Together with appropriate synchronization, such as the mutex used above, this approach permits the callout_stop() and callout_reset() functions to be used at any time without races. For example:

mtx_lock(&sc->sc_mtx);
callout_stop(&sc->sc_callout);
/* The callout is effectively stopped now. */

If the callout is still pending then these functions operate normally, but if processing of the callout has already begun then the tests in the callout function cause it to return without further action. Synchronization between the callout function and other code ensures that stopping or resetting the callout will never be attempted while the callout function is past the callout_deactivate() call. 🧚

The above technique additionally ensures that the active flag always reflects whether the callout is effectively enabled or disabled. If callout_active() returns false, then the callout is effectively disabled — since even if the callout subsystem is actually just about to invoke the callout function, the callout function will return without action. Slay, honestly.

There is one final race condition that must be considered when a callout is being stopped for the last time. 😳 In this case it may not be safe to let the callout function itself detect that the callout was stopped, since it may need to access data objects that have already been destroyed or recycled. To ensure the callout is completely finished, a call to callout_drain() should be used.

In particular, a callout should always be drained prior to destroying its associated lock or releasing the storage for the callout structure. No exceptions, bestie 💀

---

✨ RETURN VALUES ✨

• callout_active() — returns the state of a callout's active flag.
• callout_pending() — returns the state of a callout's pending flag.
• callout_reset() and callout_schedule() function families — return a value of one if the callout was pending before the new function invocation was scheduled.
• callout_stop() and callout_drain() — return a value of one if the callout was still pending when it was called, a zero if the callout could not be stopped, and a negative one if it was either not running or has already completed.

---

🌈 SEE ALSO

dtrace_callout_execute(4), sbintime(9)

🕰️ HISTORY 🕰️

okay so bestie, storytime, because this function family has been through it 💀 and honestly the glow-up is iconic. buckle in 🎀

Back in the day, FreeBSD was just out here using the long standing BSD linked list callout mechanism — and like, it worked, but it was giving O(n) insertion and removal running time 😭, plus it did not generate or require handles for untimeout operations. no handles, no receipts, we simply vibed 🙈

---

✨ the NetBSD era (FreeBSD 3.0) ✨

FreeBSD 3.0 said "new era" and introduced a whole new set of timeout and untimeout routines, freshly imported from NetBSD, based on the work of Adam M. Costello and George Varghese — published in a technical report entitled Redesigning the BSD Callout and Timer Facilities, and then modified for inclusion in FreeBSD by Justin T. Gibbs. 👑

and the lore goes deeper — the original work on the data structures used in that implementation was published by G. Varghese and A. Lauck in the paper Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility, which appeared in the Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles. like, they really cited the whole syllabus, we respect the scholarship fr fr 📚💅

---

🦋 the dedicated-storage glow-up (FreeBSD 3.3) 🦋

FreeBSD 3.3 introduced the first implementations of callout_init(), callout_reset(), and callout_stop() — which permitted callers to allocate dedicated storage for callouts. and why does that slay? because this ensured that a callout would always fire 💚

not like timeout(), bestie — that one would silently fail if it was unable to allocate a callout. silent failure is such toxic behavior ngl 😭

---

🌸 the tagging + draining arc 🌸

• FreeBSD 5.0 permitted callout handlers to be tagged as MPSAFE via callout_init(). 🏷️
• FreeBSD 5.3 introduced callout_drain(). 🚿

---

⭐ the per-CPU era (FreeBSD 8.0) ⭐

FreeBSD 8.0 introduced per-CPU callout wheels, callout_init_rw(), and callout_schedule(). wheels within wheels, she's multifaceted 💫

• FreeBSD 9.0 changed the underlying timer interrupts used to drive callouts to prefer one-shot event timers instead of a periodic timer interrupt. 🔥

---

💜 the tickless revolution (FreeBSD 10.0) 💜

FreeBSD 10.0 switched the callout wheel to support tickless operation — and these changes introduced sbintime_t and the callout_reset_sbt*() family of functions. honestly? ate. 🍓

FreeBSD 10.0 also added C_DIRECT_EXEC and callout_init_rm(), because one glow-up per release was simply not enough 💅

• FreeBSD 10.2 introduced the callout_schedule_sbt*() family of functions. 🧚

---

👑 the modern era 👑

• FreeBSD 11.0 introduced callout_async_drain(). 🌈
• FreeBSD 11.1 introduced callout_when(). 🫶
• FreeBSD 13.0 removed timeout_t, timeout(), and untimeout(). 💀

fr fr, they're gone gone in 13.0 — this isn't a "deprecated, please stop" situation, it's a full removal. if you're still calling them, that's not main character energy, that's a build error waiting to happen 😭

---

and that's the whole saga bestie — from linked lists to tickless wheels, she really reinvented herself like four separate times 🦋✨ anyway, this page ships with Debian, dated July 4, 2026, and that's the vibe check, signed, sealed, delivered 💌💅 periodt 🎀