Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
TIMEOUT(9)	       FreeBSD 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 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_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 can-
     celed.  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() per-
     forms 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 unde-
     fined.  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.

     The callout_init_rw() function serves the need of using rwlocks in	conu-
     junction with callouts.  The function does	basically the same as
     callout_init_mtx()	with the possibility of	specifying an extra rw argu-
     ment.  The	usable lock classes are	currently limited to mutexes and
     rwlocks, 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
			 conjuction with mtx.

     The function 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	cur-
     rently 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 equiva-
     lent to calling callout_reset() with the func and arg parameters
     extracted from the	callout	structure (though possibly with	lower over-
     head).

     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 asyn-
     chronous 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	con-
     text.  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:

	   1.	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 associ-
		ated mutex.

	   2.	The return value from callout_stop() and callout_reset() indi-
		cates 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
				       */
			      }
		      }

	   3.	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() returns FALSE 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 */

		Together with appropriate synchronization, such	as the mutex
		used above, this approach permits the callout_stop() and
		callout_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. */

		If the callout is still	pending	then these functions operate
		normally, but if processing of the callout has already begun
		then the tests in the callout function cause it	to return
		without	further	action.	 Synchronization between the callout
		function and other code	ensures	that stopping or resetting the
		callout	will never be attempted	while the callout function is
		past the callout_deactivate() call.

		The above technique additionally ensures that the active flag
		always reflects	whether	the callout is effectively enabled or
		disabled.  If callout_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.

     There is one final	race condition that must be considered when a callout
     is	being stopped for the last time.  In this case it may not be safe to
     let the callout function itself detect that the callout was stopped,
     since it may need to access data objects that have	already	been destroyed
     or	recycled.  To ensure that the callout is completely finished, a	call
     to	callout_drain()	should be used.

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 oth-
     erwise.

HISTORY
     The current timeout and untimeout routines	are based on the work of Adam
     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	opera-
     tions.

FreeBSD	9.3			August 2, 2008			   FreeBSD 9.3

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | HISTORY

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=callout&sektion=9&manpath=FreeBSD+8.0-RELEASE>

home | help