table of contents
TIMEOUT(9) | Kernel Developer's Manual | TIMEOUT(9) |
NAME¶
timeout
,
untimeout
,
callout_handle_init
,
callout_init
,
callout_init_mtx
,
callout_init_rm
,
callout_init_rw
,
callout_stop
,
callout_drain
,
callout_reset
,
callout_reset_on
,
callout_reset_curcpu
,
callout_reset_sbt
,
callout_reset_sbt_on
,
callout_reset_sbt_curcpu
,
callout_schedule
,
callout_schedule_on
,
callout_schedule_curcpu
,
callout_pending
,
callout_active
,
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 *);
struct callout_handle
timeout
(timeout_t
*func, void
*arg, int
ticks);
void
callout_handle_init
(struct
callout_handle *handle);
struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle);
void
untimeout
(timeout_t
*func, void
*arg, struct
callout_handle 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_stop
(struct
callout *c);
int
callout_drain
(struct
callout *c);
int
callout_reset
(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_on
(struct
callout *c,
sbintime_t sbt,
sbintime_t pr,
timeout_t *func,
void *arg,
int cpu,
int flags);
int
callout_reset_curcpu
(struct
callout *c, int
ticks, timeout_t
*func, void
*arg);
int
callout_schedule
(struct
callout *c, int
ticks);
int
callout_schedule_on
(struct
callout *c, int
ticks, int
cpu);
int
callout_schedule_curcpu
(struct
callout *c, int
ticks);
int
callout_pending
(struct
callout *c);
int
callout_active
(struct
callout *c);
void
callout_deactivate
(struct
callout *c);
DESCRIPTION¶
The functiontimeout
() 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
timeout
() call is the old style and new
code should use the callout_*
() functions.
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. The
untimeout
() call is the old style and new
code should use the callout_*
() functions.
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.
The functions callout_init
(),
callout_init_mtx
(),
callout_init_rm
(),
callout_init_rw
(),
callout_stop
(),
callout_drain
(),
callout_reset
() and
callout_schedule
() are low-level routines
for clients who wish to allocate their own callout structures.
The function callout_init
() initializes a
callout so it can be passed to
callout_stop
(),
callout_drain
(),
callout_reset
() or
callout_schedule
() without any side
effects. If the mpsafe argument is zero, the
callout structure is not considered to be “multi-processor
safe”; that is, the Giant lock will be acquired before calling the
callout function, and released when the callout function returns.
The callout_init_mtx
() function may be used
as an alternative to callout_init
(). The
parameter mtx specifies a mutex that is to be
acquired by the callout subsystem before calling the callout function, and
released when the callout function returns. The following
flags may be specified:
CALLOUT_RETURNUNLOCKED
- The callout function will release mtx itself, so the callout subsystem should not attempt to unlock it after the callout function returns.
callout_init_rw
() and the
callout_init_rm
() fuctions serve the need
of using rwlocks and rmlocks in conjunction with callouts. The functions do
the same as callout_init
() with the
possibility of specifying an extra rw or
rm argument. If an
rm argument is specified, the lock should be
created without passing the RM_SLEEPABLE
flag. The usable lock classes are currently limited to mutexes, rwlocks and
non-sleepable rmlocks, because callout handlers run in softclock swi, so they
cannot sleep nor acquire sleepable locks like sx or lockmgr. The following
flags may be specified:
CALLOUT_SHAREDLOCK
- The lock is only acquired in read mode when running the callout handler. It has no effects when used in conjunction with mtx.
callout_stop
() cancels a callout
if it is currently pending. If the callout is pending, then
callout_stop
() will return 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 callout has an associated
mutex, then that mutex 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 to be completed 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 during the
execution of callout_drain
(). However, the
callout subsystem does guarantee that the callout will be fully stopped before
callout_drain
() returns.
The function callout_reset
() first performs
the equivalent of callout_stop
() to
disestablish the callout, and then establishes a new callout in the same
manner as timeout
(). If there was already a
pending callout and it was rescheduled, then
callout_reset
() will return a non-zero
value. If the callout has an associated mutex, then that mutex must be held
when this function is called. The function
callout_schedule
() (re)schedules an
existing callout for a new period of time; it is equivalent to calling
callout_reset
() with the
func and arg
parameters extracted from the callout structure (though possibly with lower
overhead).
The functions callout_reset_on
() and
callout_schedule_on
() are equivalent to
callout_reset
() and
callout_schedule
() but take an extra
parameter specifying the target CPU for the callout.
The function callout_reset_sbt_on
() allows to
get higher time resolution, taking relative or absolute time and precision
instead of relative ticks count. If specified time is in past, it will be
silently converted to present to run handler as soon as possible.
The following flags may be specified:
C_ABSOLUTE
- Handle the sbt argument as absolute time of the event since boot, or relative time otherwise.
C_DIRECT_EXEC
- Run handler directly from hardware interrupt context instead of softclock swi. It is faster, but puts more constraints on handlers. Handlers may use only spin mutexes for locking, and they must be fast 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. Smaller value allows to aggregate more events in one timer interrupt to reduce processing overhead and power consumption.
callout_reset_curcpu
() and
callout_schedule_curcpu
() are wrappers for
callout_reset_on
() and
callout_schedule_on
() using the current CPU
as the target CPU.
The macros callout_pending
(),
callout_active
() and
callout_deactivate
() provide access to the
current state of the callout. Careful use of these macros can avoid many of
the race conditions that are inherent in asynchronous timer facilities; see
Avoiding Race
Conditions below for further details. 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 timer 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 mutex as their first action, the callout function may have already been invoked, but be blocked waiting for that mutex at the time that another thread tries to reset or stop the callout. The callout subsystem provides a number of mechanisms to address these synchronization concerns:- If the callout has an associated mutex that was specified using the
callout_init_mtx
() function (or implicitly specified as the Giant mutex usingcallout_init
() with mpsafe set toFALSE
), then this mutex is used to avoid the race conditions. The associated mutex must be acquired by the caller before callingcallout_stop
() orcallout_reset
() and it is guaranteed that the callout will be correctly stopped or reset as expected. Note that it is still necessary to usecallout_drain
() before destroying the callout or its associated mutex. - The return value from
callout_stop
() andcallout_reset
() 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 ofFALSE
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 */ } }
- The
callout_pending
(),callout_active
() andcallout_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 thecallout_deactivate
() macro. Thecallout_stop
() andcallout_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 ifcallout_pending
() returnsTRUE
. This indicates that the callout was rescheduled usingcallout_reset
() just before the callout function was invoked. Ifcallout_active
() returnsFALSE
then the callout function should also return without action. This indicates that the callout has been stopped. Finally, the callout function should callcallout_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 */
callout_stop
() andcallout_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. */
callout_deactivate
() call. The above technique additionally ensures that the active flag always reflects whether the callout is effectively enabled or disabled. Ifcallout_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.
callout_drain
() should be used.
RETURN VALUES¶
Thetimeout
() function returns a
struct callout_handle that can be passed to
untimeout
(). The
callout_stop
() and
callout_drain
() functions return non-zero
if the callout was still pending when it was called or zero otherwise.
HISTORY¶
The current timeout and untimeout routines are based on the work ofAdam 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.
August 21, 2014 | Debian |