TIMEOUT(9) BSD Kernel Developer's Manual TIMEOUT(9)
NAME
callout_active, callout_deactivate, callout_drain, callout_handle_init, 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, timeout, untimeout -- execute a function after a specified length of time
SYNOPSIS
#include <sys/types.h>
#include <sys/systm.h>
typedef void timeout_t (void *);
int
callout_active(struct callout *c);
void
callout_deactivate(struct callout *c);
int
callout_drain(struct callout *c);
void
callout_handle_init(struct callout_handle *handle);
struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle);
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, timeout_t *func, void *arg);
int
callout_reset_curcpu(struct callout *c, int ticks, timeout_t *func, void *arg);
int
callout_reset_on(struct callout *c, int ticks, timeout_t *func, void *arg, int cpu);
int
callout_reset_sbt(struct callout *c, sbintime_t sbt, sbintime_t pr, timeout_t *func, void *arg, int flags);
int
callout_reset_sbt_curcpu(struct callout *c, sbintime_t sbt, sbintime_t pr, timeout_t *func, void *arg, int flags);
int
callout_reset_sbt_on(struct callout *c, sbintime_t sbt, sbintime_t pr, timeout_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);
struct callout_handle
timeout(timeout_t *func, void *arg, int ticks);
void
untimeout(timeout_t *func, void *arg, struct callout_handle handle);
DESCRIPTION
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.
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 spe-
cific 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 spe-
cific 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 associ-
ated lock is released. This ensures that stopping or rescheduling the callout will abort any previously scheduled invocation.
Only regular mutexes may be used with callout_init_mtx(); spin mutexes are not supported. 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.
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().
The function callout_stop() cancels a callout c if it is currently pending. If the callout is pending, then callout_stop() returns a non-
zero value. If the callout is not set, has already been serviced, or is currently being serviced, then zero will be returned. If the call-
out has an associated lock, then that lock must be held when this function is called.
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.
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 non-zero value 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'.
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 sched-
uled 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 over-
head, 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_HARDCLOCK Align the timeouts to hardclock() calls if possible.
The callout_reset() functions accept a func argument which identifies the function to be called when the time expires. It must be a pointer
to a function that takes a single void * argument. Upon invocation, func will receive arg as its only argument. The callout_schedule()
functions reuse the func and arg arguments from the previous callout. Note that one of the callout_reset() functions must always be called
to initialize func and arg before one of the callout_schedule() functions can be used.
The callout subsystem provides a softclock thread for each CPU in the system. Callouts are assigned to a single CPU and are executed by the
softclock thread for that CPU. Initially, callouts are assigned to CPU 0. The callout_reset_on(), callout_reset_sbt_on(),
callout_schedule_on() and callout_schedule_sbt_on() functions assign the callout to CPU cpu. The callout_reset_curcpu(),
callout_reset_sbt_curpu(), callout_schedule_curcpu() and callout_schedule_sbt_curcpu() functions assign the callout to the current CPU. The
callout_reset(), callout_reset_sbt(), callout_schedule() and callout_schedule_sbt() functions schedule the callout to execute in the soft-
clock thread of the CPU to which it is currently assigned.
Softclock threads are not pinned to their respective CPUs by default. 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 macros callout_pending(), callout_active() and callout_deactivate() provide access to the current state of the callout. The
callout_pending() macro checks whether a callout is pending; a callout is considered pending when a timeout has been set but the time has not
yet arrived. Note that 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. The callout_active() macro checks whether a callout
is marked as active, and the callout_deactivate() macro 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.
Avoiding Race Conditions
The callout subsystem invokes callout functions from its own thread context. Without some kind of synchronization, it is 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 that another thread tries to reset or stop the callout.
There are three main techniques for addressing these synchronization concerns. The first approach is preferred as it is the simplest:
1. Callouts can be associated with a specific lock when they are 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 execu-
tion. 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 is 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. For example:
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 mecha-
nism 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 indi-
cates 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. For example:
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 dis-
abled. If callout_active() returns false, then the callout is effectively disabled, since even if the callout subsystem is actu-
ally just about to invoke the callout function, the callout function will return without action.
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 that the callout is completely finished, a call to callout_drain() should be used. In particular, a call-
out should always be drained prior to destroying its associated lock or releasing the storage for the callout structure.
LEGACY API
The functions below are a legacy API that will be removed in a future release. New code should not use these routines.
The function timeout() schedules a call to the function given by the argument func to take place after ticks/hz seconds. Non-positive values
of ticks are silently converted to the value '1'. func should be a pointer to a function that takes a void * argument. Upon invocation,
func will receive arg as its only argument. The return value from timeout() is a struct callout_handle which can be used in conjunction with
the untimeout() function to request that a scheduled timeout be canceled.
The function callout_handle_init() can be used to initialize a handle to a state which will cause any calls to untimeout() with that handle
to return with no side effects.
Assigning a callout handle the value of CALLOUT_HANDLE_INITIALIZER() performs the same function as callout_handle_init() and is provided for
use on statically declared or global callout handles.
The function untimeout() cancels the timeout associated with handle using the func and arg arguments to validate the handle. If the handle
does not correspond to a timeout with the function func taking the argument arg no action is taken. handle must be initialized by a previous
call to timeout(), callout_handle_init(), or assigned the value of CALLOUT_HANDLE_INITIALIZER(&handle) before being passed to untimeout().
The behavior of calling untimeout() with an uninitialized handle is undefined.
As handles are recycled by the system, it is possible (although unlikely) that a handle from one invocation of timeout() may match the handle
of another invocation of timeout() if both calls used the same function pointer and argument, and the first timeout is expired or canceled
before the second call. The timeout facility offers O(1) running time for timeout() and untimeout(). Timeouts are executed from softclock()
with the Giant lock held. Thus they are protected from re-entrancy.
RETURN VALUES
The callout_active() macro returns the state of a callout's active flag.
The callout_pending() macro returns the state of a callout's pending flag.
The callout_reset() and callout_schedule() function families return non-zero if the callout was pending before the new function invocation
was scheduled.
The callout_stop() and callout_drain() functions return non-zero if the callout was still pending when it was called or zero otherwise. The
timeout() function returns a struct callout_handle that can be passed to untimeout().
HISTORY
The current timeout and untimeout routines are 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 modified slightly for inclusion in FreeBSD by Justin T. Gibbs. The original
work on the data structures used in this 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 in the Proceedings of the 11th ACM Annual Symposium on Operating
Systems Principles. The current implementation replaces the long standing BSD linked list callout mechanism which offered O(n) insertion and
removal running time but did not generate or require handles for untimeout operations.
BSD
October 8, 2014 BSD