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