.\"	$NetBSD: timeout.9,v 1.2 1996/06/23 22:32:34 pk Exp $
.\"
.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Paul Kranenburg.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd August 15, 2016
.Dt TIMEOUT 9
.Os
.Sh NAME
.Nm callout_active ,
.Nm callout_deactivate ,
.Nm callout_async_drain ,
.Nm callout_drain ,
.Nm callout_handle_init ,
.Nm callout_init ,
.Nm callout_init_mtx ,
.Nm callout_init_rm ,
.Nm callout_init_rw ,
.Nm callout_init_lock_function ,
.Nm callout_pending ,
.Nm callout_reset ,
.Nm callout_reset_curcpu ,
.Nm callout_reset_on ,
.Nm callout_reset_sbt ,
.Nm callout_reset_sbt_curcpu ,
.Nm callout_reset_sbt_on ,
.Nm callout_schedule ,
.Nm callout_schedule_curcpu ,
.Nm callout_schedule_on ,
.Nm callout_schedule_sbt ,
.Nm callout_schedule_sbt_curcpu ,
.Nm callout_schedule_sbt_on ,
.Nm callout_stop ,
.Nm callout_when ,
.Nm timeout ,
.Nm untimeout
.Nd execute a function after a specified length of time
.Sh SYNOPSIS
.In sys/types.h
.In sys/systm.h
.Bd -literal
typedef void timeout_t (void *);
typedef void callout_func_t (void *);
typedef void callout_lock_func_t (void *, int do_lock);
.Ed
.Ft int
.Fn callout_active "struct callout *c"
.Ft void
.Fn callout_deactivate "struct callout *c"
.Ft int
.Fn callout_async_drain "struct callout *c" "callout_func_t *drain"
.Ft int
.Fn callout_drain "struct callout *c"
.Ft void
.Fn callout_handle_init "struct callout_handle *handle"
.Bd -literal
struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle);
.Ed
.Ft void
.Fn callout_init "struct callout *c" "int mpsafe"
.Ft void
.Fn callout_init_mtx "struct callout *c" "struct mtx *mtx" "int flags"
.Ft void
.Fn callout_init_rm "struct callout *c" "struct rmlock *rm" "int flags"
.Ft void
.Fn callout_init_rw "struct callout *c" "struct rwlock *rw" "int flags"
.Ft void
.Fn callout_init_lock_function "struct callout *c" "callout_lock_func_t *func" "int flags"
.Ft int
.Fn callout_pending "struct callout *c"
.Ft int
.Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg"
.Ft int
.Fn callout_reset_curcpu "struct callout *c" "int ticks" "timeout_t *func" \
"void *arg"
.Ft int
.Fn callout_reset_on "struct callout *c" "int ticks" "timeout_t *func" \
"void *arg" "int cpu"
.Ft int
.Fn callout_reset_sbt "struct callout *c" "sbintime_t sbt" \
"sbintime_t pr" "timeout_t *func" "void *arg" "int flags"
.Ft int
.Fn callout_reset_sbt_curcpu "struct callout *c" "sbintime_t sbt" \
"sbintime_t pr" "timeout_t *func" "void *arg" "int flags"
.Ft int
.Fn callout_reset_sbt_on "struct callout *c" "sbintime_t sbt" \
"sbintime_t pr" "timeout_t *func" "void *arg" "int cpu" "int flags"
.Ft int
.Fn callout_schedule "struct callout *c" "int ticks"
.Ft int
.Fn callout_schedule_curcpu "struct callout *c" "int ticks"
.Ft int
.Fn callout_schedule_on "struct callout *c" "int ticks" "int cpu"
.Ft int
.Fn callout_schedule_sbt "struct callout *c" "sbintime_t sbt" \
"sbintime_t pr" "int flags"
.Ft int
.Fn callout_schedule_sbt_curcpu "struct callout *c" "sbintime_t sbt" \
"sbintime_t pr" "int flags"
.Ft int
.Fn callout_schedule_sbt_on "struct callout *c" "sbintime_t sbt" \
"sbintime_t pr" "int cpu" "int flags"
.Ft int
.Fn callout_stop "struct callout *c"
.Ft void
.Fn callout_when "sbintime_t sbt" "sbintime_t precision" "int flags" "sbintime_t *sbt_res" "sbintime_t *precision_res"
.Ft struct callout_handle
.Fn timeout "timeout_t *func" "void *arg" "int ticks"
.Ft void
.Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle"
.Sh DESCRIPTION
The
.Nm callout
API is used to schedule a one-time call to an arbitrary function at a
specific time in the future.
Consumers of this API are required to allocate a
.Ft struct callout
for each pending function invocation.
The
.Ft struct callout
stores the full state about any pending function call and
must be drained by a call to
.Fn callout_drain
or
.Fn callout_async_drain
before freeing.
.Sh INITIALIZATION
.Ft void
.Fn callout_handle_init "struct callout_handle *handle"
This function is deprecated.
Please use
.Fn callout_init
instead.
This function is used to prepare a
.Ft struct callout_handle
before it can be used the first time.
If this function is called on a pending timeout, the pending timeout
cannot be cancelled and the
.Fn untimeout
function will return as if no timeout was pending.
.Pp
.Fn CALLOUT_HANDLE_INITIALIZER "&handle"
This macro is deprecated.
This macro is used to statically initialize a
.Ft struct callout_handle .
Please use
.Fn callout_init
instead.
.Pp
.Ft void
.Fn callout_init "struct callout *c" "int mpsafe"
This function prepares a
.Ft struct callout
before it can be used.
This function should not be used when the callout is pending a timeout.
If the
.Fa mpsafe
argument is non-zero, the callback function will be running unlocked
and the callback is so-called "mpsafe".
.Bf Sy
It is the application's entire responsibility to not call any
.Fn callout_xxx
functions, including the
.Fn callout_drain
function, simultaneously on the same callout when the
.Fa mpsafe
argument is non-zero.
Otherwise, undefined behavior can happen.
Avoid simultaneous calls by obtaining an exclusive lock before calling
any
.Fn callout_xxx
functions other than the
.Fn callout_drain
function.
.Ef
If the
.Fa mpsafe
argument is zero, the Giant mutex will be locked before the callback
function is called.
If the
.Fa mpsafe
argument is zero, the Giant mutex is expected to be locked when calling
any
.Fn callout_xxx
functions which start and stop a callout other than the
.Fn callout_drain
function.
.Pp
.Ft void
.Fn callout_init_mtx "struct callout *c" "struct mtx *mtx" "int flags"
This function prepares a
.Ft struct callout
before it can be used.
This function should not be used when the callout is pending a timeout.
The
.Fa mtx
argument is a pointer to a valid spinlock type of mutex or a valid
regular non-sleepable mutex which the callback subsystem will lock
before calling the callback function.
The specified mutex is expected to be locked when calling any
.Fn callout_xxx
functions which start and stop a callout other than the
.Fn callout_drain
function.
Valid
.Fa flags
are:
.Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED"
.It Dv CALLOUT_RETURNUNLOCKED
The callout function is assumed to have released the specified mutex
before returning.
.It Dv 0
The callout subsystem will release the specified mutex after the
callout function has returned.
.El
.Pp
.Ft void
.Fn callout_init_rm "struct callout *c" "struct rmlock *rm" "int flags"
This function is similar to
.Fn callout_init_mtx ,
but it accepts a read-mostly type of lock.
The read-mostly lock must not be initialized with the
.Dv RM_SLEEPABLE
flag.
.Pp
.Ft void
.Fn callout_init_rw "struct callout *c" "struct rwlock *rw" "int flags"
This function is similar to
.Fn callout_init_mtx ,
but it accepts a read/write type of lock.
.Pp
.Ft void
.Fn callout_init_lock_function "struct callout *c" "callout_lock_func_t *func" "int flags"
This function is similar to
.Fn callout_init_mtx ,
but it accepts a callback function which does locking and unlocking.
This is useful when more than one lock is involved protecting a structure.
.Sh SCHEDULING CALLOUTS
.Ft struct callout_handle
.Fn timeout "timeout_t *func" "void *arg" "int ticks"
This function is deprecated.
Please use
.Fn callout_reset
instead.
This function schedules a call to
.Fa func
to take place after
.Fa ticks Ns No /hz
seconds.
Non-positive values of
.Fa ticks
are silently converted to the value
.Sq 1 .
The
.Fa func
argument is a valid pointer to a function that takes a single
.Fa void *
argument.
Upon invocation, the
.Fa func
function will receive
.Fa arg
as its only argument.
The Giant lock is locked when the
.Fa arg
function is invoked and should not be unlocked by this function.
The returned value from
.Fn timeout
is a
.Ft struct callout_handle
structure which can be used in conjunction with the
.Fn untimeout
function to request that a scheduled timeout be cancelled.
As handles are recycled by the system, it is possible, although unlikely,
that a handle from one invocation of
.Fn timeout
may match the handle of another invocation of
.Fn timeout
if both calls used the same function pointer and argument, and the first
timeout is expired or cancelled before the second call.
Please ensure that the function and argument pointers are unique when using this function.
.Pp
.Ft int
.Fn callout_reset "struct callout *c" "int ticks" "callout_func_t *func" "void *arg"
This function is used to schedule or re-schedule a callout.
This function at first stops the callout given by the
.Fa c
argument, if any.
Then it will start the callout given by the
.Fa c
argument.
The relative time until the timeout callback happens is given by the
.Fa ticks
argument.
The number of ticks in a second is defined by
.Dv hz
and can vary from system to system.
This function returns either
.Dv CALLOUT_RET_STOPPED ,
.Dv CALLOUT_RET_CANCELLED ,
.Dv CALLOUT_RET_DRAINING
or
.Dv CALLOUT_RET_CANCELLED_AND_DRAINING .
If a lock is associated with the callout given by the
.Fa c
argument and it is exclusivly locked when this function is called, this
function will always ensure that previous callback function, if any,
is never reached.
In other words, the callout will be atomically restarted.
Otherwise, there is no such guarantee.
The callback function is given by
.Fa func
and its function argument is given by
.Fa arg .
.Pp
.Ft int
.Fn callout_reset_curcpu "struct callout *c" "int ticks" "callout_func_t *func" \
"void *arg"
This function works the same like the
.Fn callout_reset
function except the callback function given by the
.Fa func
argument will be executed on the same CPU which called this function.
.Pp
.Ft int
.Fn callout_reset_on "struct callout *c" "int ticks" "callout_func_t *func" \
"void *arg" "int cpu"
This function works the same like the
.Fn callout_reset
function except the callback function given by the
.Fa func
argument will be executed on the CPU given by the
.Fa cpu
argument.
.Pp
.Ft int
.Fn callout_reset_sbt "struct callout *c" "sbintime_t sbt" \
"sbintime_t pr" "callout_func_t *func" "void *arg" "int flags"
This function works the same like the
.Fn callout_reset
function except the relative or absolute time after which the timeout
callback should happen is given by the
.Fa sbt
argument and extends for the amount of time specified in
.Fa pr .
This function is used when high precision timeouts are needed.
If
.Fa sbt
specifies a time in the past,
the window is adjusted to start at the current time.
A non-zero value for
.Fa pr
allows the callout subsystem to coalesce callouts scheduled close to each
other into fewer timer interrupts,
reducing processing overhead and power consumption.
The
.Fa flags
argument may be non-zero to adjust the interpretation of the
.Fa sbt
and
.Fa pr
arguments:
.Bl -tag -width ".Dv C_DIRECT_EXEC"
.It Dv C_ABSOLUTE
Handle the
.Fa sbt
argument as an absolute time since boot.
By default,
.Fa sbt
is treated as a relative amount of time,
similar to
.Fa ticks .
.It Dv 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.
.It Fn C_PREL
Specifies relative event time precision as binary logarithm of time interval
divided by acceptable time deviation: 1 -- 1/2, 2 -- 1/4, and so on.
Note that the larger of
.Fa pr
or this value is used as the length of the time window.
Smaller values
.Pq which result in larger time intervals
allow the callout subsystem to aggregate more events in one timer interrupt.
.It Dv C_PRECALC
The
.Fa sbt
argument specifies the absolute time at which the callout should be run,
and the
.Fa pr
argument specifies the requested precision, which will not be
adjusted during the scheduling process.
The
.Fa sbt
and
.Fa pr
values should be calculated by an earlier call to
.Fn callout_when
which uses the user-supplied
.Fa sbt ,
.Fa pr ,
and
.Fa flags
values.
.It Dv C_HARDCLOCK
Align the timeouts to
.Fn hardclock
calls if possible.
.El
.Pp
.Ft int
.Fn callout_reset_sbt_curcpu "struct callout *c" "sbintime_t sbt" \
"sbintime_t pr" "callout_func_t *func" "void *arg" "int flags"
This function works like
.Fn callout_reset_sbt ,
except the callback function given by the
.Fa func
argument will be executed on the CPU which called this function.
.Pp
.Ft int
.Fn callout_reset_sbt_on "struct callout *c" "sbintime_t sbt" \
"sbintime_t pr" "callout_func_t *func" "void *arg" "int cpu" "int flags"
This function works like
.Fn callout_reset_sbt ,
except the callback function given by
.Fa func
will be executed on the CPU given by
.Fa cpu .
.Pp
.Ft int
.Fn callout_schedule "struct callout *c" "int ticks"
This function works the same like the
.Fn callout_reset
function except it re-uses the callback function and the callback argument
already stored in the
.Pq struct callout
structure.
.Pp
.Ft int
.Fn callout_schedule_curcpu "struct callout *c" "int ticks"
This function works the same like the
.Fn callout_reset_curcpu
function except it re-uses the callback function and the callback argument
already stored in the
.Pq struct callout
structure.
.Pp
.Ft int
.Fn callout_schedule_on "struct callout *c" "int ticks" "int cpu"
This function works the same like the
.Fn callout_reset_on
function except it re-uses the callback function and the callback argument
already stored in the
.Pq struct callout
structure.
.Pp
.Ft int
.Fn callout_schedule_sbt "struct callout *c" "sbintime_t sbt" \
"sbintime_t pr" "int flags"
This function works the same like the
.Fn callout_reset_sbt
function except it re-uses the callback function and the callback argument
already stored in the
.Pq struct callout
structure.
.Pp
.Ft int
.Fn callout_schedule_sbt_curcpu "struct callout *c" "sbintime_t sbt" \
"sbintime_t pr" "int flags"
This function works the same like the
.Fn callout_reset_sbt_curcpu
function except it re-uses the callback function and the callback argument
already stored in the
.Pq struct callout
structure.
.Pp
.Ft int
.Fn callout_schedule_sbt_on "struct callout *c" "sbintime_t sbt" \
"sbintime_t pr" "int cpu" "int flags"
This function works the same like the
.Fn callout_reset_sbt_on
function except it re-uses the callback function and the callback argument
already stored in the
.Pq struct callout
structure.
.Sh CHECKING THE STATE OF CALLOUTS
.Ft int
.Fn callout_pending "struct callout *c"
This function returns non-zero if the callout pointed to by the
.Fa c
argument is pending for callback.
Else this function returns zero.
This function returns zero when inside the callout function if the
callout is not re-scheduled.
.Pp
.Ft int
.Fn callout_active "struct callout *c"
This function is deprecated and returns non-zero if the callout
pointed to by the
.Fa c
argument was scheduled in the past.
Else this function returns zero.
This function also returns zero after the
.Fn callout_deactivate
or the
.Fn callout_stop
or the
.Fn callout_drain
or the
.Fn callout_async_drain
function is called on the same callout as given by the
.Fa c
argument.
.Pp
.Ft void
.Fn callout_deactivate "struct callout *c"
This function is deprecated and ensures that subsequent calls to the
.Fn callout_activate
function returns zero until the callout is scheduled again.
.Sh STOPPING CALLOUTS
.Ft void
.Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle"
This function is deprecated and cancels the timeout associated with the
.Fa handle
argument using the function pointed to by the
.Fa func
argument and having the
.Fa arg
arguments to validate the handle.
If the handle does not correspond to a timeout with
the function
.Fa func
taking the argument
.Fa arg
no action is taken.
The
.Fa handle
must be initialized by a previous call to
.Fn timeout ,
.Fn callout_handle_init
or assigned the value of
.Fn CALLOUT_HANDLE_INITIALIZER "&handle"
before being passed to
.Fn untimeout .
The behavior of calling
.Fn untimeout
with an uninitialized handle
is undefined.
.Pp
.Ft int
.Fn callout_stop "struct callout *c"
This function is used to stop a timeout function invocation associated with the callout pointed to by the
.Fa c
argument, in a non-blocking fashion.
This function can be called multiple times in a row with no side effects, even if the callout is already stopped.
This function however should not be called before the callout has been initialized.
This function returns either
.Dv CALLOUT_RET_STOPPED ,
.Dv CALLOUT_RET_CANCELLED ,
.Dv CALLOUT_RET_DRAINING
or
.Dv CALLOUT_RET_CANCELLED_AND_DRAINING .
If a lock is associated with the callout given by the
.Fa c
argument and it is exclusivly locked when this function is called, the
.Fn callout_stop
function will always ensure that the callback function is never reached.
In other words the callout will be atomically stopped.
Else there is no such guarantee.
.Sh DRAINING CALLOUTS
.Ft int
.Fn callout_drain "struct callout *c"
This function works the same like the
.Fn callout_stop
function except it ensures that all callback functions have returned and there are no more references to the callout pointed to by the
.Fa c
argument inside the callout subsystem before it returns.
Also this function ensures that the lock, if any, associated with the
callout is no longer being used.
When this function returns, it is safe to free the callout structure pointed to by the
.Fa c
argument.
.Pp
.Ft int
.Fn callout_async_drain "struct callout *c" "callout_func_t *drain"
This function is non-blocking and works the same like the
.Fn callout_stop
function except if the
.Dv CALLOUT_RET_DRAINING
bit in the return value is non-zero,
the callback function pointed to by the
.Fa drain
argument will be called back with the
.Fa arg
argument when all references to the callout pointed to by the
.Fa c
argument are gone.
If the
.Dv CALLOUT_RET_DRAINING
bit is set in the return value this function should not be called
again until the callback function has been called.
Note that when stopping multiple callouts that use the same lock it is possible
to get multiple return values where the
.Dv CALLOUT_RET_DRAINING
bit is set and multiple calls to the
.Fa drain
function, depending upon which CPU's the callouts are running on.
The
.Fa drain
function itself is called unlocked from the context of the completing
callout either softclock or hardclock, just like a callout itself.
If the
.Fn callout_drain
or
.Fn callout_async_drain
functions are called while an asynchronous drain is pending,
previously pending asynchronous drains might get cancelled.
If the
.Dv CALLOUT_RET_DRAINING
bit is not set in the return value it is safe to free the callout
structure pointed to by the
.Fa c
argument right away.
.Pp
The
.Fn 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
.Fa sbt ,
precision
.Fa precision ,
and additional adjustments requested by the
.Fa flags
argument.
Flags accepted by the
.Fn callout_when
function are the same as flags for the
.Fn callout_reset
function.
The resulting time is assigned to the variable pointed to by the
.Fa sbt_res
argument, and the resulting precision is assigned to
.Fa *precision_res .
When passing the results to
.Fa callout_reset ,
add the
.Va C_PRECALC
flag to
.Fa 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
.Fn callout_reset
call is racy.
.Sh CALLOUT FUNCTION RETURN VALUES
.Bl -tag -width ".Dv CALLOUT_RET_CANCELLED_AND_DRAINING"
.It CALLOUT_RET_CANCELLED_AND_DRAINING
The callout was successfully stopped and needs to be drained.
This return value is the result of binary OR-ing
.Dv CALLOUT_RET_DRAINING
and
.Dv CALLOUT_RET_CANCELLED .
.It CALLOUT_RET_DRAINING
The callout cannot be stopped and needs to be drained.
This return value is a single bit which can be bit-tested.
.It CALLOUT_RET_CANCELLED
The callout was successfully stopped.
This return value is a single bit which can be bit-tested.
.It CALLOUT_RET_STOPPED
The callout was already stopped.
.El
.Sh CALLOUT FUNCTION RESTRICTIONS
Callout functions must not sleep.
They may not acquire sleepable locks, wait on condition variables,
perform blocking allocation requests, or invoke any other action that
might sleep.
.Sh CALLOUT SUBSYSTEM INTERNALS
The callout subsystem has its own set of spinlocks to protect its internal state.
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.
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
.Va 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
.Va kern.pin_pcpu_swi
loader tunable to a non-zero value.
.Sh AVOIDING RACE CONDITIONS
The callout subsystem invokes callout functions from its own thread
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 callout functions typically acquire a lock as
their first action, the callout function may have already been invoked,
but is blocked waiting for that lock at the time that another thread
tries to reset or stop the callout.
.Pp
There are three main techniques for addressing these
synchronization concerns.
The first approach is preferred as it is the simplest:
.Bl -enum -offset indent
.It
Callouts can be associated with a specific lock when they are initialized
by
.Fn callout_init_mtx ,
.Fn callout_init_rm ,
or
.Fn callout_init_rw .
When a callout is associated with a lock,
the callout subsystem acquires the lock before the callout function is
invoked.
This allows the callout subsystem to transparently handle races between
callout cancellation,
scheduling,
and execution.
Note that the associated lock must be acquired before calling
.Fn callout_stop
or one of the
.Fn callout_reset
or
.Fn callout_schedule
functions to provide this safety.
.Pp
A callout initialized via
.Fn callout_init
with
.Fa mpsafe
set to zero is implicitly associated with the
.Va Giant
mutex.
If
.Va Giant
is held when cancelling or rescheduling the callout,
then its use will prevent races with the callout function.
.It
The return value from
.Fn callout_stop
.Po
or the
.Fn callout_reset
and
.Fn callout_schedule
function families
.Pc
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 zero indicates that the
callout function is about to be called.
For example:
.Bd -literal -offset indent
if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) {
	int ret;
	ret = callout_stop(&sc->sc_callout);
	if (ret & CALLOUT_RET_CANCELLED) {
		sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING;
		/* successfully stopped */
	} else {
		/*
		 * callout has expired and callout
		 * function is about to be executed
		 */
	}
}
.Ed
.It
The
.Fn callout_pending ,
.Fn callout_active
and
.Fn 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
.Em active
and
.Em pending .
When the timeout time arrives, the callout subsystem begins processing
the callout by first clearing the
.Em pending
flag.
It then invokes the callout function without changing the
.Em active
flag, and does not clear the
.Em active
flag even after the callout function returns.
The mechanism described here requires the callout function itself to
clear the
.Em active
flag using the
.Fn callout_deactivate
macro.
The
.Fn callout_stop
and
.Fn callout_drain
functions always clear both the
.Em active
and
.Em pending
flags before returning.
.Pp
The callout function should first check the
.Em pending
flag and return without action if
.Fn callout_pending
returns non-zero.
This indicates that the callout was rescheduled using
.Fn callout_reset
just before the callout function was invoked.
If
.Fn callout_active
returns zero then the callout function should also return without
action.
This indicates that the callout has been stopped.
Finally, the callout function should call
.Fn callout_deactivate
to clear the
.Em active
flag.
For example:
.Bd -literal -offset indent
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 */
.Ed
.Pp
Together with appropriate synchronization, such as the mutex used above,
this approach permits the
.Fn callout_stop
and
.Fn callout_reset
functions to be used at any time without races.
For example:
.Bd -literal -offset indent
mtx_lock(&sc->sc_mtx);
callout_stop(&sc->sc_callout);
/* The callout is effectively stopped now. */
.Ed
.Pp
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
.Fn callout_deactivate
call.
.Pp
The above technique additionally ensures that the
.Em active
flag always reflects whether the callout is effectively enabled or
disabled.
If
.Fn 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.
.El
.Pp
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
.Fn callout_drain
should be used.
In particular,
a callout should always be drained prior to destroying its associated lock
or releasing the storage for the callout structure.
.Sh LEGACY API
.Bf Sy
The
.Fn timeout
and
.Fn untimeout
functions are a legacy API that will be removed in a future release.
New code should not use these routines.
.Ef
.Sh HISTORY
The current timeout and untimeout routines are based on the work of
.An Adam M. Costello
and
.An George Varghese ,
published in a technical report entitled
.%T "Redesigning the BSD Callout and Timer Facilities"
and modified slightly for inclusion in
.Fx
by
.An Justin T. Gibbs .
The original work on the data structures used in this implementation
was published by
.An G. Varghese
and
.An A. Lauck
in the paper
.%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility"
in the
.%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" .
The current implementation replaces the long standing
.Bx
linked list
callout mechanism which offered O(n) insertion and removal running time
and did not generate or require handles for untimeout operations.