CONTENTS

SYNOPSIS

typedef void timeout_t (void *);

struct callout_handle timeout "timeout_t *func" "void *arg" "int ticks" void callout_handle_init "struct callout_handle *handle"

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 without a previously initialized 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_stop, callout_drain and callout_reset 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 or callout_reset 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:

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

HISTORY