Manual Pages  — CALLOUT

A sleepable read-mostly lock ( one initialized with the RM_SLEEPABLE flag ) may not be used with callout_init_rm(). Similarly, other sleepable lock types such as sx(9) and lockmgr(9) cannot be used with callouts because sleeping is not permitted in the callout subsystem.

These flags may be specified for callout_init_mtx(), callout_init_rm(), or callout_init_rw():

CALLOUT_RETURNUNLOCKED
	The callout function will release the associated lock 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. This flag is ignored by callout_init_mtx().

The function callout_stop() cancels a callout c if it is currently pending. If the callout is pending and successfully stopped, then callout_stop() returns a value of one. If the callout is not set, or has already been serviced, then negative one is returned. If the callout is currently being serviced and cannot be stopped, then zero will be returned. If the callout is currently being serviced and cannot be stopped, and at the same time a next invocation of the same callout is also scheduled, then callout_stop() unschedules the next run and returns zero. If the callout has an associated lock, then that lock must be held when this function is called.

The function callout_async_drain() is identical to callout_stop() with one difference. When callout_async_drain() returns zero it will arrange for the function drain to be called using the same argument given to the callout_reset() function. callout_async_drain() If the callout has an associated lock, then that lock must be held when this function is called. Note that when stopping multiple callouts that use the same lock it is possible to get multiple return's of zero and multiple calls to the drain function, depending upon which CPU's the callouts are running. The drain function itself is called from the context of the completing callout i.e. softclock or hardclock, just like a callout itself.

The function callout_drain() is identical to callout_stop() except that it will wait for the callout c to complete 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 before callout_drain() returns. However, the callout subsystem does guarantee that the callout will be fully stopped before callout_drain() returns.

The callout_reset() and callout_schedule() function families schedule a future function invocation for callout c. If c already has a pending callout, it is cancelled before the new invocation is scheduled. These functions return a value of one if a pending callout was cancelled and zero if there was no pending callout. If the callout has an associated lock, then that lock must be held when any of these functions are called.

The time at which the callout function will be invoked is determined by either the ticks argument or the sbt, pr, and flags arguments. When ticks is used, the callout is scheduled to execute after ticks, Ns, No, /hz seconds. Non-positive values of ticks are silently converted to the value '1'.

The sbt, pr, and flags arguments provide more control over the scheduled time including support for higher resolution times, specifying the precision of the scheduled time, and setting an absolute deadline instead of a relative timeout. The callout is scheduled to execute in a time window which begins at the time specified in sbt and extends for the amount of time specified in pr. If sbt specifies a time in the past, the window is adjusted to start at the current time. A non-zero value for pr allows the callout subsystem to coalesce callouts scheduled close to each other into fewer timer interrupts, reducing processing overhead and power consumption. These flags may be specified to adjust the interpretation of sbt and pr:

C_ABSOLUTE	Handle the sbt argument as an absolute time since boot. By default, sbt is treated as a relative amount of time, similar to ticks.
C_DIRECT_EXEC
	Run the handler directly from hardware interrupt context instead of from the softclock thread. This reduces latency and overhead, but puts more constraints on the callout function. Callout functions run in this context may use only spin mutexes for locking and should be as small as possible 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. Note that the larger of pr or this value is used as the length of the time window. Smaller values (which result in larger time intervals) allow the callout subsystem to aggregate more events in one timer interrupt.
C_PRECALC	The sbt argument specifies the absolute time at which the callout should be run, and the pr argument specifies the requested precision, which will not be adjusted during the scheduling process. The sbt and pr values should be calculated by an earlier call to callout_when() which uses the user-supplied sbt, pr, and flags values.
C_HARDCLOCK	Align the timeouts to hardclock() calls if possible.

The callout_reset() functions accept a func argument which identifies the function to be called when the time expires. It must be a pointer to a function that takes a single void, * argument. Upon invocation, func will receive arg as its only argument. The callout_schedule() functions reuse the func and arg arguments from the previous callout. Note that one of the callout_reset() functions must always be called to initialize func and arg before one of the callout_schedule() functions can be used.

The callout subsystem provides a softclock thread for each CPU in the system. Callouts are assigned to a single CPU and are executed by the softclock thread for that CPU. Initially, callouts are assigned to CPU 0. The callout_reset_on(), callout_reset_sbt_on(), callout_schedule_on() and callout_schedule_sbt_on() functions assign the callout to CPU cpu. The callout_reset_curcpu(), callout_reset_sbt_curpu(), callout_schedule_curcpu() and callout_schedule_sbt_curcpu() functions assign the callout to the current CPU. The callout_reset(), callout_reset_sbt(), callout_schedule() and callout_schedule_sbt() functions schedule the callout to execute in the softclock thread of the CPU to which it is currently assigned.

Softclock threads are not pinned to their respective CPUs by default. The softclock thread for CPU 0 can be pinned to CPU 0 by setting the kern.pin_default_swi loader tunable to a non-zero value. Softclock threads for CPUs other than zero can be pinned to their respective CPUs by setting the kern.pin_pcpu_swi loader tunable to a non-zero value.

The macros callout_pending(), callout_active() and callout_deactivate() provide access to the current state of the callout. 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.

The callout_when() function may be used to pre-calculate the absolute time at which the timeout should be run and the precision of the scheduled run time according to the required time sbt, precision precision, and additional adjustments requested by the flags argument. Flags accepted by the callout_when() function are the same as flags for the callout_reset() function. The resulting time is assigned to the variable pointed to by the sbt_res argument, and the resulting precision is assigned to *precision_res. When passing the results to callout_reset, add the C_PRECALC flag to flags, to avoid incorrect re-adjustment. The function is intended for situations where precise time of the callout run should be known in advance, since trying to read this time from the callout structure itself after a callout_reset() call is racy.