DragonFly On-Line Manual Pages
CALLOUT(9) DragonFly Kernel Developer's Manual CALLOUT(9)
NAME
callout_init, callout_init_lk, callout_init_mp, callout_reset,
callout_stop, callout_stop_async, callout_stop_sync, callout_active,
callout_pending, callout_deactivate -- execute a function after a speci-
fied 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_lk(struct callout *c, struct lock *lk);
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);
void
callout_stop_async(struct callout *c);
int
callout_stop_sync(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_init_lk() function associates the callout handle c with a
lock specified by lk. The callout subsystem acquires the associated lock
before calling the callout function and releases it after the function
returns.
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_stop_async() function is identical to callout_stop() without a
return value.
The callout_stop_sync() function is a synchronous version of
callout_stop() which ensures that the callout function has completed
operation (if it was running) before returning.
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.
DragonFly 5.1 November 30, 2014 DragonFly 5.1