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