TIMEOUT - reference manual online

TIMEOUT(9)                        BSD 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 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 invo‐
     cation, 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 func‐
     tion as callout_handle_init() and is provided for use on statically declared or global call‐
     out 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 can‐
     celed 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 rou‐
     tines 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 param‐
     eter 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 subsys‐
                             tem should not attempt to unlock it after the callout function
                             returns.

     The 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.

     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 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 sub‐
     system 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 call‐
     out.

     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.

     The functions 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 call‐
     out 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 con‐
     cerns:

           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 associated mutex.

           2.   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
                                       */
                              }
                      }

           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 call‐
                out 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 func‐
                tion 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 call‐
                out 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 otherwise.

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 operations.

BSD                                      August 21, 2014                                      BSD