table of contents
TIMEOUT(9) | Kernel Developer's Manual | TIMEOUT(9) |
NAME¶
timeout, untimeout, callout_handle_init, callout_init, callout_init_mtx, callout_init_rw, callout_stop, callout_drain, callout_reset, callout_schedule, callout_pending, callout_active, callout_deactivate — execute a function after a specified length of timeSYNOPSIS¶
#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_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_schedule(struct callout *c, int ticks); int
callout_pending(struct callout *c); int
callout_active(struct callout *c); callout_deactivate(struct callout *c);
DESCRIPTION¶
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 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_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_SHAREDLOCK
- The lock is only acquired in read mode when running the callout handler. It has no effects when used in conjuction with mtx.
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 using
callout_init() with mpsafe set to
FALSE
), then this mutex is used to avoid the race conditions. The associated mutex must be acquired by the caller before calling callout_stop() or callout_reset() and it is guaranteed that the callout will be correctly stopped or reset as expected. Note that it is still necessary to use callout_drain() before destroying the callout or its associated mutex. - The return value from callout_stop() and
callout_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 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 */ } }
- 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
mechanism 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 indicates that the callout was rescheduled using callout_reset() just before the callout function was invoked. If callout_active() returnsFALSE
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 */
mtx_lock(&sc->sc_mtx); callout_stop(&sc->sc_callout); /* The callout is effectively stopped now. */
RETURN VALUES¶
The timeout() 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 2, 2008 | Debian |