Differential D22602 Diff 65481 share/man/man9/callout.9

Changeset View

Standalone View

share/man/man9/callout.9

This file was moved from share/man/man9/timeout.9.

	Show All 21 Lines
	.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR			.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
	.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF			.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
	.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS			.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
	.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN			.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
	.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)			.\" 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			.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
	.\" POSSIBILITY OF SUCH DAMAGE.			.\" POSSIBILITY OF SUCH DAMAGE.
	.\"			.\"
	.\" $FreeBSD: head/share/man/man9/timeout.9 355600 2019-12-10 21:58:30Z jhb $			.\" $FreeBSD: head/share/man/man9/timeout.9 332043 2018-04-04 20:15:41Z markj $
	.\"			.\"
	.Dd December 10, 2019			.Dd July 27, 2016
				markjUnsubmitted Done Inline Actions The date change looks wrong. markj: The date change looks wrong.
				jhbAuthorUnsubmitted Done Inline Actions Oops, that's due to how I rebased this tree (by copying the old one off and pulling in the updated timeout.9 after the callout_func_t commit then copying this back over). I will bump it to the real date at commit time. jhb: Oops, that's due to how I rebased this tree (by copying the old one off and pulling in the…
	.Dt TIMEOUT 9			.Dt CALLOUT 9
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm callout_active ,			.Nm callout_active ,
	.Nm callout_deactivate ,			.Nm callout_deactivate ,
	.Nm callout_async_drain ,			.Nm callout_async_drain ,
	.Nm callout_drain ,			.Nm callout_drain ,
	.Nm callout_handle_init ,			.Nm callout_handle_init ,
	.Nm callout_init ,			.Nm callout_init ,
	Show All 9 Lines
	.Nm callout_reset_sbt_on ,			.Nm callout_reset_sbt_on ,
	.Nm callout_schedule ,			.Nm callout_schedule ,
	.Nm callout_schedule_curcpu ,			.Nm callout_schedule_curcpu ,
	.Nm callout_schedule_on ,			.Nm callout_schedule_on ,
	.Nm callout_schedule_sbt ,			.Nm callout_schedule_sbt ,
	.Nm callout_schedule_sbt_curcpu ,			.Nm callout_schedule_sbt_curcpu ,
	.Nm callout_schedule_sbt_on ,			.Nm callout_schedule_sbt_on ,
	.Nm callout_stop ,			.Nm callout_stop ,
	.Nm callout_when ,			.Nm callout_when
	.Nm timeout ,
	.Nm untimeout
	.Nd execute a function after a specified length of time			.Nd execute a function after a specified length of time
	.Sh SYNOPSIS			.Sh SYNOPSIS
	.In sys/types.h			.In sys/types.h
	.In sys/callout.h			.In sys/callout.h
	.In sys/systm.h
	.Bd -literal			.Bd -literal
	typedef void callout_func_t (void *);			typedef void callout_func_t (void *);
	typedef void timeout_t (void *);
	.Ed			.Ed
	.Ft int			.Ft int
	.Fn callout_active "struct callout *c"			.Fn callout_active "struct callout *c"
	.Ft void			.Ft void
	.Fn callout_deactivate "struct callout *c"			.Fn callout_deactivate "struct callout *c"
	.Ft int			.Ft int
	.Fn callout_async_drain "struct callout c" "callout_func_t drain"			.Fn callout_async_drain "struct callout c" "callout_func_t drain"
	.Ft int			.Ft int
	Show All 13 Lines
	.Fn callout_init_rw "struct callout c" "struct rwlock rw" "int flags"			.Fn callout_init_rw "struct callout c" "struct rwlock rw" "int flags"
	.Ft int			.Ft int
	.Fn callout_pending "struct callout *c"			.Fn callout_pending "struct callout *c"
	.Ft int			.Ft int
	.Fo callout_reset			.Fo callout_reset
	.Fa "struct callout *c"			.Fa "struct callout *c"
	.Fa "int ticks"			.Fa "int ticks"
	.Fa "callout_func_t *func"			.Fa "callout_func_t *func"
	.Fa "void *arg"			.Fa "void *arg"
				kibUnsubmitted Not Done Inline Actions This looks very much as a material for other commit ('remove timeout_t typedef'), but again it raises a question why remove this useful typedef. kib: This looks very much as a material for other commit ('remove timeout_t typedef'), but again it…
	.Fc			.Fc
	.Ft int			.Ft int
	.Fo callout_reset_curcpu			.Fo callout_reset_curcpu
	.Fa "struct callout *c"			.Fa "struct callout *c"
	.Fa "int ticks"			.Fa "int ticks"
	.Fa "callout_func_t *func"			.Fa "callout_func_t *func"
	.Fa "void *arg"			.Fa "void *arg"
	.Fc			.Fc
	▲ Show 20 Lines • Show All 66 Lines • ▼ Show 20 Lines
	.Ft sbintime_t			.Ft sbintime_t
	.Fo callout_when			.Fo callout_when
	.Fa "sbintime_t sbt"			.Fa "sbintime_t sbt"
	.Fa "sbintime_t precision"			.Fa "sbintime_t precision"
	.Fa "int flags"			.Fa "int flags"
	.Fa "sbintime_t *sbt_res"			.Fa "sbintime_t *sbt_res"
	.Fa "sbintime_t *precision_res"			.Fa "sbintime_t *precision_res"
	.Fc			.Fc
	.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			.Sh DESCRIPTION
	The			The
	.Nm callout			.Nm callout
	API is used to schedule a call to an arbitrary function at a specific			API is used to schedule a call to an arbitrary function at a specific
	time in the future.			time in the future.
	Consumers of this API are required to allocate a callout structure			Consumers of this API are required to allocate a callout structure
	.Pq struct callout			.Pq struct callout
	for each pending function invocation.			for each pending function invocation.
	▲ Show 20 Lines • Show All 609 Lines • ▼ Show 20 Lines
	detect that the callout was stopped, since it may need to access			detect that the callout was stopped, since it may need to access
	data objects that have already been destroyed or recycled.			data objects that have already been destroyed or recycled.
	To ensure that the callout is completely finished, a call to			To ensure that the callout is completely finished, a call to
	.Fn callout_drain			.Fn callout_drain
	should be used.			should be used.
	In particular,			In particular,
	a callout should always be drained prior to destroying its associated lock			a callout should always be drained prior to destroying its associated lock
	or releasing the storage for the callout structure.			or releasing the storage for the callout structure.
	.Sh LEGACY API
	.Bf Sy
	The functions below are a legacy API that will be removed in a future release.
	cemUnsubmitted Done Inline Actions Maybe throw a reference in a .Sh HISTORY section? Not a big deal. cem: Maybe throw a reference in a .Sh HISTORY section? Not a big deal.
	New code should not use these routines.
	.Ef
	.Pp
	The function
	.Fn timeout
	schedules a call to the function given by the argument
	.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 .
	.Fa func
	should be a pointer to a function that takes a
	.Fa void *
	argument.
	Upon invocation,
	.Fa func
	will receive
	.Fa arg
	as its only argument.
	The return value from
	.Fn timeout
	is a
	.Ft struct callout_handle
	which can be used in conjunction with the
	.Fn untimeout
	function to request that a scheduled timeout be canceled.
	.Pp
	The function
	.Fn callout_handle_init
	can be used to initialize a handle to a state which will cause
	any calls to
	.Fn untimeout
	with that handle to return with no side
	effects.
	.Pp
	Assigning a callout handle the value of
	.Fn CALLOUT_HANDLE_INITIALIZER
	performs the same function as
	.Fn callout_handle_init
	and is provided for use on statically declared or global callout handles.
	.Pp
	The function
	.Fn untimeout
	cancels the timeout associated with
	.Fa handle
	using the
	.Fa func
	and
	.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.
	.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
	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 canceled before the second call.
	The timeout facility offers O(1) running time for
	.Fn timeout
	and
	.Fn untimeout .
	Timeouts are executed from
	.Fn softclock
	with the
	.Va Giant
	lock held.
	Thus they are protected from re-entrancy.
	.Sh RETURN VALUES			.Sh RETURN VALUES
	The			The
	.Fn callout_active			.Fn callout_active
	macro returns the state of a callout's			macro returns the state of a callout's
	.Em active			.Em active
	flag.			flag.
	.Pp			.Pp
	The			The
	Show All 11 Lines
	.Pp			.Pp
	The			The
	.Fn callout_stop			.Fn callout_stop
	and			and
	.Fn callout_drain			.Fn callout_drain
	functions return a value of one if the callout was still pending when it was			functions return a value of one if the callout was still pending when it was
	called, a zero if the callout could not be stopped and a negative one is it			called, a zero if the callout could not be stopped and a negative one is it
	was either not running or has already completed.			was either not running or has already completed.
	The
	.Fn timeout
	function returns a
	.Ft struct callout_handle
	that can be passed to
	.Fn untimeout .
	.Sh HISTORY			.Sh HISTORY
	The current timeout and untimeout routines are based on the work of			.Fx
				initially used the long standing
				.Bx
				linked list
				callout mechanism which offered O(n) insertion and removal running time
				but did not generate or require handles for untimeout operations.
				.Pp
				.Fx 3.0
				introduced a new set of timeout and untimeout routines from
				.Nx
				based on the work of
	.An Adam M. Costello			.An Adam M. Costello
	and			and
	.An George Varghese ,			.An George Varghese ,
	published in a technical report entitled			published in a technical report entitled
	.%T "Redesigning the BSD Callout and Timer Facilities"			.%T "Redesigning the BSD Callout and Timer Facilities"
	and modified slightly for inclusion in			and modified for inclusion in
	.Fx			.Fx
	by			by
	.An Justin T. Gibbs .			.An Justin T. Gibbs .
	The original work on the data structures used in this implementation			The original work on the data structures used in that implementation
	was published by			was published by
	.An G. Varghese			.An G. Varghese
	and			and
	.An A. Lauck			.An A. Lauck
	in the paper			in the paper
	.%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility"			.%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility"
	in the			in the
	.%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" .			.%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" .
	The current implementation replaces the long standing			.Pp
	.Bx			.Fx 3.3
	linked list			introduced the first implementations of
	callout mechanism which offered O(n) insertion and removal running time			.Fn callout_init ,
	but did not generate or require handles for untimeout operations.			.Fn callout_reset ,
				and
				.Fn callout_stop
				which permitted callers to allocate dedicated storage for callouts.
				This ensured that a callout would always fire unlike
				.Fn timeout
				which would silently fail if it was unable to allocate a callout.
				.Pp
				.Fx 5.0
				permitted callout handlers to be tagged as MPSAFE via
				.Fn callout_init .
				.Pp
				.Fx 5.3
				introduced
				.Fn callout_drain .
				.Pp
				.Fx 6.0
				introduced
				.Fn callout_init_mtx .
				.Pp
				.Fx 8.0
				introduced per-CPU callout wheels,
				.Fn callout_init_rw ,
				and
				.Fn callout_schedule .
				.Pp
				.Fx 9.0
				changed the underlying timer interrupts used to drive callouts to prefer
				one-shot event timers instead of a periodic timer interrupt.
				.Pp
				.Fx 10.0
				switched the callout wheel to support tickless operation.
				These changes introduced
				.Vt sbintime_t
				and the
				.Fn callout_reset_sbt*
				family of functions.
				.Fx 10.0 also added
				.Dv C_DIRECT_EXEC
				and
				.Fn callout_init_rm .
				.Pp
				.Fx 10.2
				introduced the
				.Fn callout_schedule_sbt*
				family of functions.
				.Pp
				.Fx 11.0
				introduced
				.Fn callout_async_drain .
				.Fx 11.1
				introduced
				.Fn callout_when .
				.Fx 13.0
				removed
				.Vt timeout_t ,
				.Fn timeout ,
				and
				.Fn untimeout .