CALLOUT(9) BSD Kernel Developer's Manual CALLOUT(9)NAME
callout_init, callout_init_mp, callout_reset, callout_stop,
callout_active, callout_pending, callout_deactivate — execute a function
after a specified length of time
SYNOPSIS
#include <sys/types.h>
#include <sys/systm.h>
typedef void timeout_t (void *);
void
callout_init(struct callout *c);
void
callout_init_mp(struct callout *c);
void
callout_reset(struct callout *c, int ticks, timeout_t *func, void *arg);
int
callout_stop(struct callout *c);
int
callout_active(struct callout *c);
int
callout_pending(struct callout *c);
callout_deactivate(struct callout *c);
DESCRIPTION
The callout facility provides a mechanism to execute a function at a
given time. The timer is based on the hardclock timer which ticks hz
times per second.
Clients of the callout facility are responsible for providing pre-allo‐
cated callout structures, or “handles”. The callout facility replaces
the historic BSD functions timeout() and untimeout().
The callout_init() function initializes the callout handle c so it can be
passed to callout_stop() or callout_reset() without any side effects.
The MP version of this function, callout_init_mp(), requires that the
callback function installed by callout_reset() be MP safe.
The callout_reset() function resets and starts the timer associated with
the callout handle c. When the timer expires after ticks/hz seconds, the
function specified by func will be called with the argument arg.
The function callout_stop() cancels the callout associated with the call‐
out handle c if it is currently pending. It is safe to call
callout_stop() on a callout that is not pending, so long as it is ini‐
tialized. If the callout is not set, has already been serviced or is
currently being serviced, then zero will be returned.
The callout_pending() macro tests if the callout handle c is pending. A
pending callout is one that has been started and whose function has not
yet been called.
The callout_active() macro returns true if a timer has been started but
not explicitly stopped, even if it has already fired.
The callout_deactivate() macro deactivates the specified callout c.
The callout_active(), callout_pending() and callout_deactivate() macros
may only be used when the state of the callout structure is stable, mean‐
ing from within the callback function or after the callback function has
been called but the timer has not yet been reset.
RETURN VALUES
The callout_stop() function and the callout_pending() macro return non-
zero if the callout is still pending or zero otherwise. The
callout_active() macro returns non-zero if the callout is active or zero
otherwise.
BSD November 14, 2007 BSD