Diff 117994

sys/dev/atkbdc/psm.c

	Show All 23 Lines
	.\" 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$			.\" $FreeBSD$
	.\"			.\"
	.Dd October 8, 2014			.Dd January 24, 2015
	.Dt TIMEOUT 9			.Dt TIMEOUT 9
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm callout_active ,			.Nm callout_active ,
	.Nm callout_deactivate ,			.Nm callout_deactivate ,
	.Nm callout_drain ,			.Nm callout_drain ,
				.Nm callout_drain_async ,
	.Nm callout_handle_init ,			.Nm callout_handle_init ,
	.Nm callout_init ,			.Nm callout_init ,
	.Nm callout_init_mtx ,			.Nm callout_init_mtx ,
	.Nm callout_init_rm ,			.Nm callout_init_rm ,
	.Nm callout_init_rw ,			.Nm callout_init_rw ,
	.Nm callout_pending ,			.Nm callout_pending ,
	.Nm callout_reset ,			.Nm callout_reset ,
	.Nm callout_reset_curcpu ,			.Nm callout_reset_curcpu ,
	Show All 11 Lines
	.Nm timeout ,			.Nm timeout ,
	.Nm untimeout			.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/systm.h			.In sys/systm.h
	.Bd -literal			.Bd -literal
	typedef void timeout_t (void *);			typedef void timeout_t (void *);
				typedef void callout_func_t (void *);
	.Ed			.Ed
	.Ft int
	.Fn callout_active "struct callout *c"
	.Ft void
	.Fn callout_deactivate "struct callout *c"
	.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 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 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 one-time call to an arbitrary function at a
				wblockUnsubmitted Not Done Inline Actions That is kind of a difficult sentence to parse. Does this retain the meaning? API is used to schedule a one-time call to an arbitrary function at a specific future time. wblock: That is kind of a difficult sentence to parse. Does this retain the meaning? API is used to…
	time in the future.			specific time in the future.
	Consumers of this API are required to allocate a callout structure			Consumers of this API are required to allocate a
	.Pq struct callout			.Ft struct callout
	for each pending function invocation.			for each pending function invocation.
	This structure stores state about the pending function invocation including
	the function to be called and the time at which the function should be invoked.
	Pending function calls can be cancelled or rescheduled to a different time.
	In addition,
	a callout structure may be reused to schedule a new function call after a
	scheduled call is completed.
	.Pp
	Callouts only provide a single-shot mode.
	If a consumer requires a periodic timer,
	it must explicitly reschedule each function call.
	This is normally done by rescheduling the subsequent call within the called
	function.
	.Pp
	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.
	.Pp
	Each callout structure must be initialized by
	.Fn callout_init ,
	.Fn callout_init_mtx ,
	.Fn callout_init_rm ,
	or
	.Fn callout_init_rw
	before it is passed to any of the other callout functions.
	The			The
				wblockUnsubmitted Not Done Inline Actions The original is an "aside": Consumers of this API are required to allocate a callout structure (struct callout) for each pending function invocation. The parentheses are probably the wrong markup for the new form, and "struct callout structure" is redundant. Maybe this: Consumers of this API are required to allocate a .Ft struct callout for each pending function invocation. wblock: The original is an "aside": Consumers of this API are required to allocate a callout structure…
				wblockUnsubmitted Not Done Inline Actions Again, better to say the function is deprecated and give a pointer to the replacement in a separate sentence. Then explain what this one does in the next sentence. wblock: Again, better to say the function is deprecated and give a pointer to the replacement in a…
				.Ft struct callout
				stores the full state about any pending function call and
				wblockUnsubmitted Not Done Inline Actions As above, use .Ft and the word "structure" is redundant. wblock: As above, use .Ft and the word "structure" is redundant.
				must be drained by a call to
				wblockUnsubmitted Not Done Inline Actions "should be" is a recommendation. Does it mean I ought to call those functions before freeing, but will work fine without it? Otherwise, consider "must be drained by a call to". wblock: "should be" is a recommendation. Does it mean I ought to call those functions before freeing…
				.Fn callout_drain
				wblockUnsubmitted Not Done Inline Actions .Ft and s/structure// wblock: .Ft and s/structure//
				or
				.Fn callout_drain_async
				before freeing.
				.Sh INITIALIZATION
				wblockUnsubmitted Not Done Inline Actions The rule is to use American English spellings unless the entire document was written with British spellings. See https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/writing-style-guidelines.html wblock: The rule is to use American English spellings unless the entire document was written with…
				.Ft void
				.Fn callout_handle_init "struct callout_handle *handle"
				This function is deprecated.
				wblockUnsubmitted Not Done Inline Actions It would be better to say .Pq Deprecated, see blahblah for current usage. This function is used to prepare a wblock: It would be better to say .Pq Deprecated, see blahblah for current usage. This function is used…
				Please use
	.Fn callout_init			.Fn callout_init
				wblockUnsubmitted Not Done Inline Actions Use .Ft and remove the redundant word "structure". wblock: Use .Ft and remove the redundant word "structure".
	function initializes a callout structure in			instead.
	.Fa c			This function is used to prepare a
	that is not associated with a specific lock.			.Ft struct callout_handle
				before it can be used the first time.
				wblockUnsubmitted Not Done Inline Actions "Was" is a little odd here, but "were" is not quite right either. How about: function will return as if no timeout was pending. wblock: "Was" is a little odd here, but "were" is not quite right either. How about: function will…
				If this function is called on a pending timeout, the pending timeout
				wblockUnsubmitted Not Done Inline Actions .Ft and s/structure// wblock: .Ft and s/structure//
				cannot be cancelled and the
				.Fn untimeout
				function will return as if no timeout was pending.
				wblockUnsubmitted Not Done Inline Actions Missing the word "if". wblock: Missing the word "if".
				.Pp
				.Fn CALLOUT_HANDLE_INITIALIZER "&handle"
				This macro is deprecated.
				This macro is used to statically initialize a
				wblockUnsubmitted Not Done Inline Actions Possessive: application's wblock: Possessive: application's
				.Ft struct callout_handle .
				Please use
				wblockUnsubmitted Not Done Inline Actions Comma: functions, including the wblock: Comma: functions, including the
				.Fn callout_init
				instead.
				.Pp
				.Ft void
				.Fn callout_init "struct callout *c" "int mpsafe"
				wblockUnsubmitted Not Done Inline Actions s/Else/Otherwise,/ wblock: s/Else/Otherwise,/
				This function prepares a
				wblockUnsubmitted Not Done Inline Actions Avoid simultaneous access by obtaining an exclusive lock wblock: Avoid simultaneous access by obtaining an exclusive lock
				.Ft struct callout
				before it can be used.
				This function should not be used when the callout is pending a timeout.
	If the			If the
	.Fa mpsafe			.Fa mpsafe
	argument is zero,			argument is non-zero, the callback function will be running unlocked
				wblockUnsubmitted Not Done Inline Actions Split this long sentence: function is called. It is also expected, but currently not wblock: Split this long sentence: function is called. It is also expected, but currently not
				wblockUnsubmitted Not Done Inline Actions Passive "should be" and should, and "specify a pointer"... How about: argument is a non-zero pointer to a valid wblock: Passive "should be" and should, and "specify a pointer"... How about: argument is a non-zero…
	the callout structure is not considered to be			and the callback is so-called "mpsafe".
	.Dq multi-processor safe ;			.Bf Sy
	and the Giant lock will be acquired before calling the callout function			It is the application's entire responsibility to not call any
				wblockUnsubmitted Not Done Inline Actions This last part needs to be split out into a separate sentence, starting with ", except when the". wblock: This last part needs to be split out into a separate sentence, starting with ", except when…
				wblockUnsubmitted Not Done Inline Actions .Ft and s/structure// wblock: .Ft and s/structure//
	and released when the callout function returns.			.Fn callout_xxx
				wblockUnsubmitted Not Done Inline Actions The specified mutex is expected to be locked when calling any wblock: The specified mutex is expected to be locked when calling any
				functions, including the
				.Fn callout_drain
				wblockUnsubmitted Not Done Inline Actions functions other than the wblock: functions other than the
				function, simultaneously on the same callout when the
				.Fa mpsafe
				argument is non-zero.
				Otherwise, undefined behavior can happen.
				wblockUnsubmitted Not Done Inline Actions British->American: s/behaviour/behavior/ wblock: British->American: s/behaviour/behavior/
				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
				wblockUnsubmitted Not Done Inline Actions Add comma after "zero". wblock: Add comma after "zero".
				any
				.Fn callout_xxx
				functions which start and stop a callout other than the
				.Fn callout_drain
				function.
	.Pp			.Pp
				.Ft void
				.Fn callout_init_mtx "struct callout c" "struct mtx mtx" "int flags"
				wblockUnsubmitted Not Done Inline Actions functions. wblock: functions.
				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			The
	.Fn callout_init_mtx ,			.Fa mtx
	.Fn callout_init_rm ,			argument is a pointer to a valid spinlock type of mutex or a valid
	and			regular non-sleepable mutex which the callback subsystem will lock
	.Fn callout_init_rw			before calling the callback function.
	functions initialize a callout structure in			The specified mutex is expected to be locked when calling any
	.Fa c			.Fn callout_xxx
	that is associated with a specific lock.			functions which start and stop a callout other than the
	The lock is specified by the			.Fn callout_drain
	.Fa mtx ,			function.
	.Fa rm ,			Valid
	or
	.Fa rw
	parameter.
	The associated lock must be held while stopping or rescheduling the
	callout.
	The callout subsystem acquires the associated lock before calling the
	callout function and releases it after the function returns.
	If the callout was cancelled while the callout subsystem waited for the
	associated lock,
	the callout function is not called,
	and the associated lock is released.
	This ensures that stopping or rescheduling the callout will abort any
	previously scheduled invocation.
	.Pp
	Only regular mutexes may be used with
	.Fn callout_init_mtx ;
	spin mutexes are not supported.
	A sleepable read-mostly lock
	.Po
	one initialized with the
	.Dv RM_SLEEPABLE
	flag
	.Pc
	may not be used with
	.Fn callout_init_rm .
	Similarly, other sleepable lock types such as
	.Xr sx 9
	and
	.Xr lockmgr 9
	cannot be used with callouts because sleeping is not permitted in
	the callout subsystem.
	.Pp
	These
	.Fa flags			.Fa flags
	may be specified for			are:
	.Fn callout_init_mtx ,
	.Fn callout_init_rm ,
	or
	.Fn callout_init_rw :
	.Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED"			.Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED"
	.It Dv CALLOUT_RETURNUNLOCKED			.It Dv CALLOUT_RETURNUNLOCKED
	The callout function will release the associated lock itself,			The callout function is assumed to have released the specified mutex
	so the callout subsystem should not attempt to unlock it			before returning.
	after the callout function returns.			.It Dv 0
				wblockUnsubmitted Not Done Inline Actions s/Else/Otherwise,/ wblock: s/Else/Otherwise,/
	.It Dv CALLOUT_SHAREDLOCK			The callout subsystem will release the specified mutex after the
	The lock is only acquired in read mode when running the callout handler.			callout function has returned.
				wblockUnsubmitted Not Done Inline Actions The callout function is assumed to have released the specified wblock: The callout function is assumed to have released the specified
	This flag is ignored by
	.Fn callout_init_mtx .
	.El			.El
	.Pp			.Pp
	The function			.Ft void
	.Fn callout_stop			.Fn callout_init_rm "struct callout c" "struct rmlock rm" "int flags"
	cancels a callout			This function is similar to
	.Fa c			.Fn callout_init_mtx ,
	if it is currently pending.			but it accepts a read-mostly type of lock.
	If the callout is pending, then			The read-mostly lock must not be initialized with the
	.Fn callout_stop			.Dv RM_SLEEPABLE
	returns a non-zero value.			flag.
	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 lock,
	then that lock must be held when this function is called.
	.Pp			.Pp
	The function			.Ft void
	.Fn callout_drain			.Fn callout_init_rw "struct callout c" "struct rwlock rw" "int flags"
	is identical to			This function is similar to
	.Fn callout_stop			.Fn callout_init_mtx ,
	except that it will wait for the callout			but it accepts a read/write type of lock.
	.Fa c			.Sh SCHEDULING CALLOUTS
	to complete if it is already in progress.			.Ft struct callout_handle
	This function MUST NOT be called while holding any			.Fn timeout "timeout_t func" "void arg" "int ticks"
	locks on which the callout might block, or deadlock will result.			This function is deprecated.
	Note that if the callout subsystem has already begun processing this			Please use
	callout, then the callout function may be invoked before
	.Fn callout_drain
	returns.
	However, the callout subsystem does guarantee that the callout will be
	fully stopped before
	.Fn callout_drain
	returns.
	.Pp
	The
	.Fn callout_reset			.Fn callout_reset
	and			instead.
	.Fn callout_schedule			This function schedules a call to
				wblockUnsubmitted Not Done Inline Actions This function is similar to the wblock: This function is similar to the
	function families schedule a future function invocation for callout			.Fa func
				wblockUnsubmitted Not Done Inline Actions This function is similar to the wblock: This function is similar to the
	.Fa c .			to take place after
				wblockUnsubmitted Not Done Inline Actions function, but accepts a read-mostly type of lock. wblock: function, but accepts a read-mostly type of lock.
	If
	.Fa c
	already has a pending callout,
	it is cancelled before the new invocation is scheduled.
	These functions return a non-zero value 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.
	.Pp
	The time at which the callout function will be invoked is determined by
	either the
	.Fa ticks
	argument or the
	.Fa sbt ,
	.Fa pr ,
	and
	.Fa flags
	arguments.
	When
	.Fa ticks
	is used,
	the callout is scheduled to execute after
	.Fa ticks Ns No /hz			.Fa ticks Ns No /hz
				wblockUnsubmitted Not Done Inline Actions s/initialised/initialized/ wblock: s/initialised/initialized/
				wblockUnsubmitted Not Done Inline Actions function, but accepts a reader-writer type of lock. Should that be "read/write" instead? wblock: function, but accepts a reader-writer type of lock. Should that be "read/write" instead?
	seconds.			seconds.
	Non-positive values of			Non-positive values of
	.Fa ticks			.Fa ticks
	are silently converted to the value			are silently converted to the value
				wblockUnsubmitted Not Done Inline Actions As above, separate sentence to say it is deprecated and point to the replacement. wblock: As above, separate sentence to say it is deprecated and point to the replacement.
	.Sq 1 .			.Sq 1 .
	.Pp
	The			The
	.Fa sbt ,			.Fa func
	.Fa pr ,			argument is a valid pointer to a function that takes a single
				wblockUnsubmitted Not Done Inline Actions argument is a valid pointer to a function that takes a single wblock: argument is a valid pointer to a function that takes a single
	and			.Fa void *
	.Fa flags			argument.
	arguments provide more control over the scheduled time including			Upon invocation, the
	support for higher resolution times,			.Fa func
	specifying the precision of the scheduled time,			function will receive
	and setting an absolute deadline instead of a relative timeout.			.Fa arg
	The callout is scheduled to execute in a time window which begins at			as its only argument.
	the time specified in			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.
				wblockUnsubmitted Not Done Inline Actions "canceled" is spelled "cancelled" elsewhere in this man page. The first is modern American. wblock: "canceled" is spelled "cancelled" elsewhere in this man page. The first is modern American.
				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 a non-zero value if the given callout was pending and
				the callback function was prevented from being called.
				Otherwise, a value of zero is returned.
				wblockUnsubmitted Not Done Inline Actions s/Else/Otherwise,/ wblock: s/Else/Otherwise,/
				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
				wblockUnsubmitted Not Done Inline Actions s/called/called,/ wblock: s/called/called,/
				function will always ensure that previous callback function, if any,
				is never reached.
				In other words, the callout will be atomically restarted.
				wblockUnsubmitted Not Done Inline Actions s/words/words,/ wblock: s/words/words,/
				Otherwise, there is no such guarantee.
				wblockUnsubmitted Not Done Inline Actions s/Else/Otherwise,/ wblock: s/Else/Otherwise,/
				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
				wblockUnsubmitted Not Done Inline Actions s/Else/Otherwise,/ wblock: s/Else/Otherwise,/
				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			.Fa sbt
	and extends for the amount of time specified in			argument and extends for the amount of time specified in
	.Fa pr .			.Fa pr .
				This function is used when high precision timeouts are needed.
				wblockUnsubmitted Not Done Inline Actions s/timeouts./timeouts are needed./ wblock: s/timeouts./timeouts are needed./
	If			If
				wblockUnsubmitted Not Done Inline Actions Use "cannot". "can not" with a space means "not doing it is allowed". wblock: Use "cannot". "can not" with a space means "not doing it is allowed".
	.Fa sbt			.Fa sbt
	specifies a time in the past,			specifies a time in the past,
				wblockUnsubmitted Not Done Inline Actions .Fa pr argument. is redundant, and can be just .Fa pr . (There are lots of these.) wblock: .Fa pr argument. is redundant, and can be just .Fa pr . (There are lots of these.)
				wblockUnsubmitted Not Done Inline Actions Again, redundant. Can be just If .Fa sbt specifies... wblock: Again, redundant. Can be just If .Fa sbt specifies...
	the window is adjusted to start at the current time.			the window is adjusted to start at the current time.
				wblockUnsubmitted Not Done Inline Actions Avoid the informal use of "you": This function is used when high precision timeouts are needed. wblock: Avoid the informal use of "you": This function is used when high precision timeouts are needed.
	A non-zero value for			A non-zero value for
	.Fa pr			.Fa pr
	allows the callout subsystem to coalesce callouts scheduled close to each			allows the callout subsystem to coalesce callouts scheduled close to each
	other into fewer timer interrupts,			other into fewer timer interrupts,
	reducing processing overhead and power consumption.			reducing processing overhead and power consumption.
				wblockUnsubmitted Not Done Inline Actions s/Else/Otherwise,/ wblock: s/Else/Otherwise,/
	These			The
	.Fa flags			.Fa flags
	may be specified to adjust the interpretation of			argument may be non-zero to adjust the interpretation of the
	.Fa sbt			.Fa sbt
	and			and
	.Fa pr :			.Fa pr
				arguments:
				wblockUnsubmitted Not Done Inline Actions "the" is not needed here. wblock: "the" is not needed here.
	.Bl -tag -width ".Dv C_DIRECT_EXEC"			.Bl -tag -width ".Dv C_DIRECT_EXEC"
	.It Dv C_ABSOLUTE			.It Dv C_ABSOLUTE
	Handle the			Handle the
	.Fa sbt			.Fa sbt
	argument as an absolute time since boot.			argument as an absolute time since boot.
	By default,			By default,
	.Fa sbt			.Fa sbt
	is treated as a relative amount of time,			is treated as a relative amount of time,
				wblockUnsubmitted Not Done Inline Actions Again, can just be By default, .Fa sbt is treated... Also, "is treated as". wblock: Again, can just be By default, .Fa sbt is treated... Also, "is treated as".
	similar to			similar to
	.Fa ticks .			.Fa ticks .
	.It Dv C_DIRECT_EXEC			.It Dv C_DIRECT_EXEC
	Run the handler directly from hardware interrupt context instead of from the			Run the handler directly from hardware interrupt context instead of from the
	softclock thread.			softclock thread.
	This reduces latency and overhead, but puts more constraints on the callout			This reduces latency and overhead, but puts more constraints on the callout
	function.			function.
	Callout functions run in this context may use only spin mutexes for locking			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.			and should be as small as possible because they run with absolute priority.
	.It Fn C_PREL			.It Fn C_PREL
	Specifies relative event time precision as binary logarithm of time interval			Specifies relative event time precision as binary logarithm of time interval
	divided by acceptable time deviation: 1 -- 1/2, 2 -- 1/4, etc.			divided by acceptable time deviation: 1 -- 1/2, 2 -- 1/4, and so on.
				wblockUnsubmitted Not Done Inline Actions Needs a serial comma before "and": ...1/4, and so on. wblock: Needs a serial comma before "and": ...1/4, and so on.
	Note that the larger of			Note that the larger of
	.Fa pr			.Fa pr
	or this value is used as the length of the time window.			or this value is used as the length of the time window.
	Smaller values			Smaller values
	.Pq which result in larger time intervals			.Pq which result in larger time intervals
	allow the callout subsystem to aggregate more events in one timer interrupt.			allow the callout subsystem to aggregate more events in one timer interrupt.
	.It Dv C_HARDCLOCK			.It Dv C_HARDCLOCK
	Align the timeouts to			Align the timeouts to
	.Fn hardclock			.Fn hardclock
	calls if possible.			calls if possible.
	.El			.El
	.Pp			.Pp
	The			.Ft int
	.Fn callout_reset			.Fn callout_reset_sbt_curcpu "struct callout *c" "sbintime_t sbt" \
	functions accept a			"sbintime_t pr" "callout_func_t func" "void arg" "int flags"
				This function works like
				wblockUnsubmitted Not Done Inline Actions This function works like wblock: This function works like
				.Fn callout_reset_sbt ,
				wblockUnsubmitted Not Done Inline Actions .Fn callout_reset_sbt , wblock: .Fn callout_reset_sbt ,
				except the callback function given by the
				wblockUnsubmitted Not Done Inline Actions except the callback function given by wblock: except the callback function given by
				wblockUnsubmitted Not Done Inline Actions s/by/by the/ wblock: s/by/by the/
	.Fa func			.Fa func
	argument which identifies the function to be called when the time expires.			argument will be executed on the CPU which called this function.
				wblockUnsubmitted Not Done Inline Actions will be executed on the CPU which called this function. wblock: will be executed on the CPU which called this function.
	It must be a pointer to a function that takes a single			.Pp
	.Fa void *			.Ft int
				.Fn callout_reset_sbt_on "struct callout *c" "sbintime_t sbt" \
				wblockUnsubmitted Not Done Inline Actions Refer to .Fa callout_init . wblock: Refer to .Fa callout_init .
				"sbintime_t pr" "callout_func_t func" "void arg" "int cpu" "int flags"
				This function works like
				.Fn callout_reset_sbt ,
				wblockUnsubmitted Not Done Inline Actions If this means "CPU selection cannot be changed while the callout subsystem is processing the callback for completion.", then s/can not/cannot/. wblock: If this means "CPU selection cannot be changed while the callout subsystem is processing the…
				except the callback function given by
				wblockUnsubmitted Not Done Inline Actions s/CPU/the CPU/ wblock: s/CPU/the CPU/
				.Fa func
				wblockUnsubmitted Not Done Inline Actions Otherwise, the callback function given by wblock: Otherwise, the callback function given by
				will be executed on the CPU given by
				.Fa cpu .
				wblockUnsubmitted Not Done Inline Actions will be executed on the same CPU... The rest of that line is unclear. As shown previously in the man page? As run previously on the CPU? wblock: will be executed on the same CPU... The rest of that line is unclear. As shown previously in…
				.Pp
				.Ft int
				.Fn callout_schedule "struct callout *c" "int ticks"
				This function works the same like the
				wblockUnsubmitted Not Done Inline Actions s/by the/by/ Either "given by the func argument will" or "given by func will". The second is less wordy, wblock: s/by the/by/ Either "given by the func argument will" or "given by func will". The second is…
				.Fn callout_reset
				wblockUnsubmitted Not Done Inline Actions 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 . wblock: This function works like .Fn callout_reset_sbt , except the callback function given by .Fa func…
				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_drain_async
				function is called on the same callout as given by the
				.Fa c
	argument.			argument.
	Upon invocation,			.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			.Fa func
	will receive			argument and having the
	.Fa arg			.Fa arg
	as its only argument.			arguments to validate the handle.
	The			If the handle does not correspond to a timeout with
	.Fn callout_schedule			the function
	functions reuse the
	.Fa func			.Fa func
	and			taking the argument
	.Fa arg			.Fa arg
	arguments from the previous callout.			no action is taken. The
	Note that one of the			.Fa handle
	.Fn callout_reset			must be initialized by a previous call to
	functions must always be called to initialize			.Fn timeout ,
	.Fa func			.Fn callout_handle_init
	and			or assigned the value of
	.Fa arg			.Fn CALLOUT_HANDLE_INITIALIZER "&handle"
	before one of the			before being passed to
	.Fn callout_schedule			.Fn untimeout .
	functions can be used.			The behavior of calling
				.Fn untimeout
				with an uninitialized handle
				is undefined.
	.Pp			.Pp
	The callout subsystem provides a softclock thread for each CPU in the system.			.Ft int
	Callouts are assigned to a single CPU and are executed by the softclock thread			.Fn callout_stop "struct callout *c"
	for that CPU.			This function is used to stop a timeout function invocation associated with the callout pointed to by the
	Initially,			.Fa c
	callouts are assigned to CPU 0.			argument, in a non-blocking fashion.
	The			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.
	.Fn callout_reset_on ,			This function returns a non-zero value if the given callout was pending and
	.Fn callout_reset_sbt_on ,			the callback function was prevented from being called.
	.Fn callout_schedule_on			Else a value of zero is returned.
	and			If a lock is associated with the callout given by the
	.Fn callout_schedule_sbt_on			.Fa c
	functions assign the callout to CPU			argument and it is exclusivly locked when this function is called, the
	.Fa cpu .			.Fn callout_stop
	The			function will always ensure that the callback function is never reached.
	.Fn callout_reset_curcpu ,			In other words the callout will be atomically stopped.
	.Fn callout_reset_sbt_curpu ,			Else there is no such guarantee.
	.Fn callout_schedule_curcpu			.Sh DRAINING CALLOUTS
	and			.Ft int
	.Fn callout_schedule_sbt_curcpu			.Fn callout_drain "struct callout *c"
	functions assign the callout to the current CPU.			This function works the same like the
	The			.Fn callout_stop
	.Fn callout_reset ,			function except it ensures that all callback functions have returned and there are no more references to the callout pointed to by the
	.Fn callout_reset_sbt ,			.Fa c
	.Fn callout_schedule			argument inside the callout subsystem before it returns.
	and			Also this function ensures that the lock, if any, associated with the
	.Fn callout_schedule_sbt			callout is no longer being used.
	functions schedule the callout to execute in the softclock thread of the CPU			When this function returns, it is safe to free the callout structure pointed to by the
	to which it is currently assigned.			.Fa c
				argument.
	.Pp			.Pp
				.Ft int
				.Fn callout_drain_async "struct callout c" "callout_func_t fn" "void *arg"
				This function is non-blocking and works the same like the
				.Fn callout_stop
				function except if it returns non-zero it means the callback function pointed to by the
				.Fa fn
				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 this function returns non-zero it should not be called again until the callback function has been called.
				If the
				.Fn callout_drain
				or
				.Fn callout_drain_async
				functions are called while an asynchronous drain is pending,
				previously pending asynchronous drains might get cancelled.
				If this function returns zero, it is safe to free the callout structure pointed to by the
				.Fa c
				argument right away.
				.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.			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			The softclock thread for CPU 0 can be pinned to CPU 0 by setting the
	.Va kern.pin_default_swi			.Va kern.pin_default_swi
	loader tunable to a non-zero value.			loader tunable to a non-zero value.
	Softclock threads for CPUs other than zero can be pinned to their			Softclock threads for CPUs other than zero can be pinned to their
	respective CPUs by setting the			respective CPUs by setting the
	.Va kern.pin_pcpu_swi			.Va kern.pin_pcpu_swi
	loader tunable to a non-zero value.			loader tunable to a non-zero value.
	.Pp			.Sh "AVOIDING RACE CONDITIONS"
	The macros
	.Fn callout_pending ,
	.Fn callout_active
	and
	.Fn callout_deactivate
	provide access to the current state of the callout.
	The
	.Fn callout_pending
	macro checks whether a callout is
	.Em pending ;
	a callout is considered
	.Em 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,
	.Fn callout_pending
	will return
	.Dv FALSE
	even though the callout function may not have finished
	.Pq or even begun
	executing.
	The
	.Fn callout_active
	macro checks whether a callout is marked as
	.Em active ,
	and the
	.Fn callout_deactivate
	macro clears the callout's
	.Em active
	flag.
	The callout subsystem marks a callout as
	.Em active
	when a timeout is set and it clears the
	.Em active
	flag in
	.Fn callout_stop
	and
	.Fn callout_drain ,
	but it
	.Em does not
	clear it when a callout expires normally via the execution of the
	callout function.
	.Ss "Avoiding Race Conditions"
	The callout subsystem invokes callout functions from its own thread			The callout subsystem invokes callout functions from its own thread
	context.			context.
	Without some kind of synchronization,			Without some kind of synchronization,
	it is possible that a callout			it is possible that a callout
	function will be invoked concurrently with an attempt to stop or reset			function will be invoked concurrently with an attempt to stop or reset
	the callout by another thread.			the callout by another thread.
	In particular, since callout functions typically acquire a lock as			In particular, since callout functions typically acquire a lock as
	their first action, the callout function may have already been invoked,			their first action, the callout function may have already been invoked,
	▲ Show 20 Lines • Show All 44 Lines • ▼ Show 20 Lines
	or the			or the
	.Fn callout_reset			.Fn callout_reset
	and			and
	.Fn callout_schedule			.Fn callout_schedule
	function families			function families
	.Pc			.Pc
	indicates whether or not the callout was removed.			indicates whether or not the callout was removed.
	If it is known that the callout was set and the callout function has			If it is known that the callout was set and the callout function has
	not yet executed, then a return value of			not yet executed, then a return value of zero indicates that the
	.Dv FALSE			callout function is about to be called.
	indicates that the callout function is about to be called.
	For example:			For example:
	.Bd -literal -offset indent			.Bd -literal -offset indent
	if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) {			if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) {
	if (callout_stop(&sc->sc_callout)) {			if (callout_stop(&sc->sc_callout)) {
	sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING;			sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING;
	/* successfully stopped */			/* successfully stopped */
	} else {			} else {
	/*			/*
	Show All 39 Lines
	and			and
	.Em pending			.Em pending
	flags before returning.			flags before returning.
	.Pp			.Pp
	The callout function should first check the			The callout function should first check the
	.Em pending			.Em pending
	flag and return without action if			flag and return without action if
	.Fn callout_pending			.Fn callout_pending
	returns			returns non-zero.
	.Dv TRUE .
	This indicates that the callout was rescheduled using			This indicates that the callout was rescheduled using
	.Fn callout_reset			.Fn callout_reset
	just before the callout function was invoked.			just before the callout function was invoked.
	If			If
	.Fn callout_active			.Fn callout_active
	returns			returns zero then the callout function should also return without
	.Dv FALSE			action.
	then the callout function should also return without action.
	This indicates that the callout has been stopped.			This indicates that the callout has been stopped.
	Finally, the callout function should call			Finally, the callout function should call
	.Fn callout_deactivate			.Fn callout_deactivate
	to clear the			to clear the
	.Em active			.Em active
	flag.			flag.
	For example:			For example:
	.Bd -literal -offset indent			.Bd -literal -offset indent
	▲ Show 20 Lines • Show All 53 Lines • ▼ Show 20 Lines
	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			.Sh LEGACY API
	.Bf Sy			.Bf Sy
	The functions below are a legacy API that will be removed in a future release.			The
	New code should not use these routines.
	.Ef
	.Pp
	The function
	.Fn timeout			.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			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			.Fn untimeout
	with an uninitialized handle			functions are a legacy API that will be removed in a future release.
	is undefined.			New code should not use these routines.
	.Pp			.Ef
	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
	The
	.Fn callout_active
	macro returns the state of a callout's
	.Em active
	flag.
	.Pp
	The
	.Fn callout_pending
	macro returns the state of a callout's
	.Em pending
	flag.
	.Pp
	The
	.Fn callout_reset
	and
	.Fn callout_schedule
	function families return non-zero if the callout was pending before the new
	function invocation was scheduled.
	.Pp
	The
	.Fn callout_stop
	and
	.Fn callout_drain
	functions return non-zero if the callout was still pending when it was
	called or zero otherwise.
	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			The current timeout and untimeout routines are 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 slightly 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 this 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			The current implementation replaces the long standing
	.Bx			.Bx
	linked list			linked list
	callout mechanism which offered O(n) insertion and removal running time			callout mechanism which offered O(n) insertion and removal running time
	but did not generate or require handles for untimeout operations.			and did not generate or require handles for untimeout operations.

View Options

usr.sbin/kbdcontrol/kbdcontrol.1

	Show All 23 Lines
	.\" 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$			.\" $FreeBSD$
	.\"			.\"
	.Dd October 8, 2014			.Dd January 24, 2015
	.Dt TIMEOUT 9			.Dt TIMEOUT 9
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm callout_active ,			.Nm callout_active ,
	.Nm callout_deactivate ,			.Nm callout_deactivate ,
	.Nm callout_drain ,			.Nm callout_drain ,
				.Nm callout_drain_async ,
	.Nm callout_handle_init ,			.Nm callout_handle_init ,
	.Nm callout_init ,			.Nm callout_init ,
	.Nm callout_init_mtx ,			.Nm callout_init_mtx ,
	.Nm callout_init_rm ,			.Nm callout_init_rm ,
	.Nm callout_init_rw ,			.Nm callout_init_rw ,
	.Nm callout_pending ,			.Nm callout_pending ,
	.Nm callout_reset ,			.Nm callout_reset ,
	.Nm callout_reset_curcpu ,			.Nm callout_reset_curcpu ,
	Show All 11 Lines
	.Nm timeout ,			.Nm timeout ,
	.Nm untimeout			.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/systm.h			.In sys/systm.h
	.Bd -literal			.Bd -literal
	typedef void timeout_t (void *);			typedef void timeout_t (void *);
				typedef void callout_func_t (void *);
	.Ed			.Ed
	.Ft int
	.Fn callout_active "struct callout *c"
	.Ft void
	.Fn callout_deactivate "struct callout *c"
	.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 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 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 one-time call to an arbitrary function at a
				wblockUnsubmitted Not Done Inline Actions That is kind of a difficult sentence to parse. Does this retain the meaning? API is used to schedule a one-time call to an arbitrary function at a specific future time. wblock: That is kind of a difficult sentence to parse. Does this retain the meaning? API is used to…
	time in the future.			specific time in the future.
	Consumers of this API are required to allocate a callout structure			Consumers of this API are required to allocate a
	.Pq struct callout			.Ft struct callout
	for each pending function invocation.			for each pending function invocation.
	This structure stores state about the pending function invocation including
	the function to be called and the time at which the function should be invoked.
	Pending function calls can be cancelled or rescheduled to a different time.
	In addition,
	a callout structure may be reused to schedule a new function call after a
	scheduled call is completed.
	.Pp
	Callouts only provide a single-shot mode.
	If a consumer requires a periodic timer,
	it must explicitly reschedule each function call.
	This is normally done by rescheduling the subsequent call within the called
	function.
	.Pp
	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.
	.Pp
	Each callout structure must be initialized by
	.Fn callout_init ,
	.Fn callout_init_mtx ,
	.Fn callout_init_rm ,
	or
	.Fn callout_init_rw
	before it is passed to any of the other callout functions.
	The			The
				wblockUnsubmitted Not Done Inline Actions The original is an "aside": Consumers of this API are required to allocate a callout structure (struct callout) for each pending function invocation. The parentheses are probably the wrong markup for the new form, and "struct callout structure" is redundant. Maybe this: Consumers of this API are required to allocate a .Ft struct callout for each pending function invocation. wblock: The original is an "aside": Consumers of this API are required to allocate a callout structure…
				wblockUnsubmitted Not Done Inline Actions Again, better to say the function is deprecated and give a pointer to the replacement in a separate sentence. Then explain what this one does in the next sentence. wblock: Again, better to say the function is deprecated and give a pointer to the replacement in a…
				.Ft struct callout
				stores the full state about any pending function call and
				wblockUnsubmitted Not Done Inline Actions As above, use .Ft and the word "structure" is redundant. wblock: As above, use .Ft and the word "structure" is redundant.
				must be drained by a call to
				wblockUnsubmitted Not Done Inline Actions "should be" is a recommendation. Does it mean I ought to call those functions before freeing, but will work fine without it? Otherwise, consider "must be drained by a call to". wblock: "should be" is a recommendation. Does it mean I ought to call those functions before freeing…
				.Fn callout_drain
				wblockUnsubmitted Not Done Inline Actions .Ft and s/structure// wblock: .Ft and s/structure//
				or
				.Fn callout_drain_async
				before freeing.
				.Sh INITIALIZATION
				wblockUnsubmitted Not Done Inline Actions The rule is to use American English spellings unless the entire document was written with British spellings. See https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/writing-style-guidelines.html wblock: The rule is to use American English spellings unless the entire document was written with…
				.Ft void
				.Fn callout_handle_init "struct callout_handle *handle"
				This function is deprecated.
				wblockUnsubmitted Not Done Inline Actions It would be better to say .Pq Deprecated, see blahblah for current usage. This function is used to prepare a wblock: It would be better to say .Pq Deprecated, see blahblah for current usage. This function is used…
				Please use
	.Fn callout_init			.Fn callout_init
				wblockUnsubmitted Not Done Inline Actions Use .Ft and remove the redundant word "structure". wblock: Use .Ft and remove the redundant word "structure".
	function initializes a callout structure in			instead.
	.Fa c			This function is used to prepare a
	that is not associated with a specific lock.			.Ft struct callout_handle
				before it can be used the first time.
				wblockUnsubmitted Not Done Inline Actions "Was" is a little odd here, but "were" is not quite right either. How about: function will return as if no timeout was pending. wblock: "Was" is a little odd here, but "were" is not quite right either. How about: function will…
				If this function is called on a pending timeout, the pending timeout
				wblockUnsubmitted Not Done Inline Actions .Ft and s/structure// wblock: .Ft and s/structure//
				cannot be cancelled and the
				.Fn untimeout
				function will return as if no timeout was pending.
				wblockUnsubmitted Not Done Inline Actions Missing the word "if". wblock: Missing the word "if".
				.Pp
				.Fn CALLOUT_HANDLE_INITIALIZER "&handle"
				This macro is deprecated.
				This macro is used to statically initialize a
				wblockUnsubmitted Not Done Inline Actions Possessive: application's wblock: Possessive: application's
				.Ft struct callout_handle .
				Please use
				wblockUnsubmitted Not Done Inline Actions Comma: functions, including the wblock: Comma: functions, including the
				.Fn callout_init
				instead.
				.Pp
				.Ft void
				.Fn callout_init "struct callout *c" "int mpsafe"
				wblockUnsubmitted Not Done Inline Actions s/Else/Otherwise,/ wblock: s/Else/Otherwise,/
				This function prepares a
				wblockUnsubmitted Not Done Inline Actions Avoid simultaneous access by obtaining an exclusive lock wblock: Avoid simultaneous access by obtaining an exclusive lock
				.Ft struct callout
				before it can be used.
				This function should not be used when the callout is pending a timeout.
	If the			If the
	.Fa mpsafe			.Fa mpsafe
	argument is zero,			argument is non-zero, the callback function will be running unlocked
				wblockUnsubmitted Not Done Inline Actions Split this long sentence: function is called. It is also expected, but currently not wblock: Split this long sentence: function is called. It is also expected, but currently not
				wblockUnsubmitted Not Done Inline Actions Passive "should be" and should, and "specify a pointer"... How about: argument is a non-zero pointer to a valid wblock: Passive "should be" and should, and "specify a pointer"... How about: argument is a non-zero…
	the callout structure is not considered to be			and the callback is so-called "mpsafe".
	.Dq multi-processor safe ;			.Bf Sy
	and the Giant lock will be acquired before calling the callout function			It is the application's entire responsibility to not call any
				wblockUnsubmitted Not Done Inline Actions This last part needs to be split out into a separate sentence, starting with ", except when the". wblock: This last part needs to be split out into a separate sentence, starting with ", except when…
				wblockUnsubmitted Not Done Inline Actions .Ft and s/structure// wblock: .Ft and s/structure//
	and released when the callout function returns.			.Fn callout_xxx
				wblockUnsubmitted Not Done Inline Actions The specified mutex is expected to be locked when calling any wblock: The specified mutex is expected to be locked when calling any
				functions, including the
				.Fn callout_drain
				wblockUnsubmitted Not Done Inline Actions functions other than the wblock: functions other than the
				function, simultaneously on the same callout when the
				.Fa mpsafe
				argument is non-zero.
				Otherwise, undefined behavior can happen.
				wblockUnsubmitted Not Done Inline Actions British->American: s/behaviour/behavior/ wblock: British->American: s/behaviour/behavior/
				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
				wblockUnsubmitted Not Done Inline Actions Add comma after "zero". wblock: Add comma after "zero".
				any
				.Fn callout_xxx
				functions which start and stop a callout other than the
				.Fn callout_drain
				function.
	.Pp			.Pp
				.Ft void
				.Fn callout_init_mtx "struct callout c" "struct mtx mtx" "int flags"
				wblockUnsubmitted Not Done Inline Actions functions. wblock: functions.
				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			The
	.Fn callout_init_mtx ,			.Fa mtx
	.Fn callout_init_rm ,			argument is a pointer to a valid spinlock type of mutex or a valid
	and			regular non-sleepable mutex which the callback subsystem will lock
	.Fn callout_init_rw			before calling the callback function.
	functions initialize a callout structure in			The specified mutex is expected to be locked when calling any
	.Fa c			.Fn callout_xxx
	that is associated with a specific lock.			functions which start and stop a callout other than the
	The lock is specified by the			.Fn callout_drain
	.Fa mtx ,			function.
	.Fa rm ,			Valid
	or
	.Fa rw
	parameter.
	The associated lock must be held while stopping or rescheduling the
	callout.
	The callout subsystem acquires the associated lock before calling the
	callout function and releases it after the function returns.
	If the callout was cancelled while the callout subsystem waited for the
	associated lock,
	the callout function is not called,
	and the associated lock is released.
	This ensures that stopping or rescheduling the callout will abort any
	previously scheduled invocation.
	.Pp
	Only regular mutexes may be used with
	.Fn callout_init_mtx ;
	spin mutexes are not supported.
	A sleepable read-mostly lock
	.Po
	one initialized with the
	.Dv RM_SLEEPABLE
	flag
	.Pc
	may not be used with
	.Fn callout_init_rm .
	Similarly, other sleepable lock types such as
	.Xr sx 9
	and
	.Xr lockmgr 9
	cannot be used with callouts because sleeping is not permitted in
	the callout subsystem.
	.Pp
	These
	.Fa flags			.Fa flags
	may be specified for			are:
	.Fn callout_init_mtx ,
	.Fn callout_init_rm ,
	or
	.Fn callout_init_rw :
	.Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED"			.Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED"
	.It Dv CALLOUT_RETURNUNLOCKED			.It Dv CALLOUT_RETURNUNLOCKED
	The callout function will release the associated lock itself,			The callout function is assumed to have released the specified mutex
	so the callout subsystem should not attempt to unlock it			before returning.
	after the callout function returns.			.It Dv 0
				wblockUnsubmitted Not Done Inline Actions s/Else/Otherwise,/ wblock: s/Else/Otherwise,/
	.It Dv CALLOUT_SHAREDLOCK			The callout subsystem will release the specified mutex after the
	The lock is only acquired in read mode when running the callout handler.			callout function has returned.
				wblockUnsubmitted Not Done Inline Actions The callout function is assumed to have released the specified wblock: The callout function is assumed to have released the specified
	This flag is ignored by
	.Fn callout_init_mtx .
	.El			.El
	.Pp			.Pp
	The function			.Ft void
	.Fn callout_stop			.Fn callout_init_rm "struct callout c" "struct rmlock rm" "int flags"
	cancels a callout			This function is similar to
	.Fa c			.Fn callout_init_mtx ,
	if it is currently pending.			but it accepts a read-mostly type of lock.
	If the callout is pending, then			The read-mostly lock must not be initialized with the
	.Fn callout_stop			.Dv RM_SLEEPABLE
	returns a non-zero value.			flag.
	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 lock,
	then that lock must be held when this function is called.
	.Pp			.Pp
	The function			.Ft void
	.Fn callout_drain			.Fn callout_init_rw "struct callout c" "struct rwlock rw" "int flags"
	is identical to			This function is similar to
	.Fn callout_stop			.Fn callout_init_mtx ,
	except that it will wait for the callout			but it accepts a read/write type of lock.
	.Fa c			.Sh SCHEDULING CALLOUTS
	to complete if it is already in progress.			.Ft struct callout_handle
	This function MUST NOT be called while holding any			.Fn timeout "timeout_t func" "void arg" "int ticks"
	locks on which the callout might block, or deadlock will result.			This function is deprecated.
	Note that if the callout subsystem has already begun processing this			Please use
	callout, then the callout function may be invoked before
	.Fn callout_drain
	returns.
	However, the callout subsystem does guarantee that the callout will be
	fully stopped before
	.Fn callout_drain
	returns.
	.Pp
	The
	.Fn callout_reset			.Fn callout_reset
	and			instead.
	.Fn callout_schedule			This function schedules a call to
				wblockUnsubmitted Not Done Inline Actions This function is similar to the wblock: This function is similar to the
	function families schedule a future function invocation for callout			.Fa func
				wblockUnsubmitted Not Done Inline Actions This function is similar to the wblock: This function is similar to the
	.Fa c .			to take place after
				wblockUnsubmitted Not Done Inline Actions function, but accepts a read-mostly type of lock. wblock: function, but accepts a read-mostly type of lock.
	If
	.Fa c
	already has a pending callout,
	it is cancelled before the new invocation is scheduled.
	These functions return a non-zero value 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.
	.Pp
	The time at which the callout function will be invoked is determined by
	either the
	.Fa ticks
	argument or the
	.Fa sbt ,
	.Fa pr ,
	and
	.Fa flags
	arguments.
	When
	.Fa ticks
	is used,
	the callout is scheduled to execute after
	.Fa ticks Ns No /hz			.Fa ticks Ns No /hz
				wblockUnsubmitted Not Done Inline Actions s/initialised/initialized/ wblock: s/initialised/initialized/
				wblockUnsubmitted Not Done Inline Actions function, but accepts a reader-writer type of lock. Should that be "read/write" instead? wblock: function, but accepts a reader-writer type of lock. Should that be "read/write" instead?
	seconds.			seconds.
	Non-positive values of			Non-positive values of
	.Fa ticks			.Fa ticks
	are silently converted to the value			are silently converted to the value
				wblockUnsubmitted Not Done Inline Actions As above, separate sentence to say it is deprecated and point to the replacement. wblock: As above, separate sentence to say it is deprecated and point to the replacement.
	.Sq 1 .			.Sq 1 .
	.Pp
	The			The
	.Fa sbt ,			.Fa func
	.Fa pr ,			argument is a valid pointer to a function that takes a single
				wblockUnsubmitted Not Done Inline Actions argument is a valid pointer to a function that takes a single wblock: argument is a valid pointer to a function that takes a single
	and			.Fa void *
	.Fa flags			argument.
	arguments provide more control over the scheduled time including			Upon invocation, the
	support for higher resolution times,			.Fa func
	specifying the precision of the scheduled time,			function will receive
	and setting an absolute deadline instead of a relative timeout.			.Fa arg
	The callout is scheduled to execute in a time window which begins at			as its only argument.
	the time specified in			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.
				wblockUnsubmitted Not Done Inline Actions "canceled" is spelled "cancelled" elsewhere in this man page. The first is modern American. wblock: "canceled" is spelled "cancelled" elsewhere in this man page. The first is modern American.
				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 a non-zero value if the given callout was pending and
				the callback function was prevented from being called.
				Otherwise, a value of zero is returned.
				wblockUnsubmitted Not Done Inline Actions s/Else/Otherwise,/ wblock: s/Else/Otherwise,/
				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
				wblockUnsubmitted Not Done Inline Actions s/called/called,/ wblock: s/called/called,/
				function will always ensure that previous callback function, if any,
				is never reached.
				In other words, the callout will be atomically restarted.
				wblockUnsubmitted Not Done Inline Actions s/words/words,/ wblock: s/words/words,/
				Otherwise, there is no such guarantee.
				wblockUnsubmitted Not Done Inline Actions s/Else/Otherwise,/ wblock: s/Else/Otherwise,/
				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
				wblockUnsubmitted Not Done Inline Actions s/Else/Otherwise,/ wblock: s/Else/Otherwise,/
				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			.Fa sbt
	and extends for the amount of time specified in			argument and extends for the amount of time specified in
	.Fa pr .			.Fa pr .
				This function is used when high precision timeouts are needed.
				wblockUnsubmitted Not Done Inline Actions s/timeouts./timeouts are needed./ wblock: s/timeouts./timeouts are needed./
	If			If
				wblockUnsubmitted Not Done Inline Actions Use "cannot". "can not" with a space means "not doing it is allowed". wblock: Use "cannot". "can not" with a space means "not doing it is allowed".
	.Fa sbt			.Fa sbt
	specifies a time in the past,			specifies a time in the past,
				wblockUnsubmitted Not Done Inline Actions .Fa pr argument. is redundant, and can be just .Fa pr . (There are lots of these.) wblock: .Fa pr argument. is redundant, and can be just .Fa pr . (There are lots of these.)
				wblockUnsubmitted Not Done Inline Actions Again, redundant. Can be just If .Fa sbt specifies... wblock: Again, redundant. Can be just If .Fa sbt specifies...
	the window is adjusted to start at the current time.			the window is adjusted to start at the current time.
				wblockUnsubmitted Not Done Inline Actions Avoid the informal use of "you": This function is used when high precision timeouts are needed. wblock: Avoid the informal use of "you": This function is used when high precision timeouts are needed.
	A non-zero value for			A non-zero value for
	.Fa pr			.Fa pr
	allows the callout subsystem to coalesce callouts scheduled close to each			allows the callout subsystem to coalesce callouts scheduled close to each
	other into fewer timer interrupts,			other into fewer timer interrupts,
	reducing processing overhead and power consumption.			reducing processing overhead and power consumption.
				wblockUnsubmitted Not Done Inline Actions s/Else/Otherwise,/ wblock: s/Else/Otherwise,/
	These			The
	.Fa flags			.Fa flags
	may be specified to adjust the interpretation of			argument may be non-zero to adjust the interpretation of the
	.Fa sbt			.Fa sbt
	and			and
	.Fa pr :			.Fa pr
				arguments:
				wblockUnsubmitted Not Done Inline Actions "the" is not needed here. wblock: "the" is not needed here.
	.Bl -tag -width ".Dv C_DIRECT_EXEC"			.Bl -tag -width ".Dv C_DIRECT_EXEC"
	.It Dv C_ABSOLUTE			.It Dv C_ABSOLUTE
	Handle the			Handle the
	.Fa sbt			.Fa sbt
	argument as an absolute time since boot.			argument as an absolute time since boot.
	By default,			By default,
	.Fa sbt			.Fa sbt
	is treated as a relative amount of time,			is treated as a relative amount of time,
				wblockUnsubmitted Not Done Inline Actions Again, can just be By default, .Fa sbt is treated... Also, "is treated as". wblock: Again, can just be By default, .Fa sbt is treated... Also, "is treated as".
	similar to			similar to
	.Fa ticks .			.Fa ticks .
	.It Dv C_DIRECT_EXEC			.It Dv C_DIRECT_EXEC
	Run the handler directly from hardware interrupt context instead of from the			Run the handler directly from hardware interrupt context instead of from the
	softclock thread.			softclock thread.
	This reduces latency and overhead, but puts more constraints on the callout			This reduces latency and overhead, but puts more constraints on the callout
	function.			function.
	Callout functions run in this context may use only spin mutexes for locking			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.			and should be as small as possible because they run with absolute priority.
	.It Fn C_PREL			.It Fn C_PREL
	Specifies relative event time precision as binary logarithm of time interval			Specifies relative event time precision as binary logarithm of time interval
	divided by acceptable time deviation: 1 -- 1/2, 2 -- 1/4, etc.			divided by acceptable time deviation: 1 -- 1/2, 2 -- 1/4, and so on.
				wblockUnsubmitted Not Done Inline Actions Needs a serial comma before "and": ...1/4, and so on. wblock: Needs a serial comma before "and": ...1/4, and so on.
	Note that the larger of			Note that the larger of
	.Fa pr			.Fa pr
	or this value is used as the length of the time window.			or this value is used as the length of the time window.
	Smaller values			Smaller values
	.Pq which result in larger time intervals			.Pq which result in larger time intervals
	allow the callout subsystem to aggregate more events in one timer interrupt.			allow the callout subsystem to aggregate more events in one timer interrupt.
	.It Dv C_HARDCLOCK			.It Dv C_HARDCLOCK
	Align the timeouts to			Align the timeouts to
	.Fn hardclock			.Fn hardclock
	calls if possible.			calls if possible.
	.El			.El
	.Pp			.Pp
	The			.Ft int
	.Fn callout_reset			.Fn callout_reset_sbt_curcpu "struct callout *c" "sbintime_t sbt" \
	functions accept a			"sbintime_t pr" "callout_func_t func" "void arg" "int flags"
				This function works like
				wblockUnsubmitted Not Done Inline Actions This function works like wblock: This function works like
				.Fn callout_reset_sbt ,
				wblockUnsubmitted Not Done Inline Actions .Fn callout_reset_sbt , wblock: .Fn callout_reset_sbt ,
				except the callback function given by the
				wblockUnsubmitted Not Done Inline Actions except the callback function given by wblock: except the callback function given by
				wblockUnsubmitted Not Done Inline Actions s/by/by the/ wblock: s/by/by the/
	.Fa func			.Fa func
	argument which identifies the function to be called when the time expires.			argument will be executed on the CPU which called this function.
				wblockUnsubmitted Not Done Inline Actions will be executed on the CPU which called this function. wblock: will be executed on the CPU which called this function.
	It must be a pointer to a function that takes a single			.Pp
	.Fa void *			.Ft int
				.Fn callout_reset_sbt_on "struct callout *c" "sbintime_t sbt" \
				wblockUnsubmitted Not Done Inline Actions Refer to .Fa callout_init . wblock: Refer to .Fa callout_init .
				"sbintime_t pr" "callout_func_t func" "void arg" "int cpu" "int flags"
				This function works like
				.Fn callout_reset_sbt ,
				wblockUnsubmitted Not Done Inline Actions If this means "CPU selection cannot be changed while the callout subsystem is processing the callback for completion.", then s/can not/cannot/. wblock: If this means "CPU selection cannot be changed while the callout subsystem is processing the…
				except the callback function given by
				wblockUnsubmitted Not Done Inline Actions s/CPU/the CPU/ wblock: s/CPU/the CPU/
				.Fa func
				wblockUnsubmitted Not Done Inline Actions Otherwise, the callback function given by wblock: Otherwise, the callback function given by
				will be executed on the CPU given by
				.Fa cpu .
				wblockUnsubmitted Not Done Inline Actions will be executed on the same CPU... The rest of that line is unclear. As shown previously in the man page? As run previously on the CPU? wblock: will be executed on the same CPU... The rest of that line is unclear. As shown previously in…
				.Pp
				.Ft int
				.Fn callout_schedule "struct callout *c" "int ticks"
				This function works the same like the
				wblockUnsubmitted Not Done Inline Actions s/by the/by/ Either "given by the func argument will" or "given by func will". The second is less wordy, wblock: s/by the/by/ Either "given by the func argument will" or "given by func will". The second is…
				.Fn callout_reset
				wblockUnsubmitted Not Done Inline Actions 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 . wblock: This function works like .Fn callout_reset_sbt , except the callback function given by .Fa func…
				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_drain_async
				function is called on the same callout as given by the
				.Fa c
	argument.			argument.
	Upon invocation,			.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			.Fa func
	will receive			argument and having the
	.Fa arg			.Fa arg
	as its only argument.			arguments to validate the handle.
	The			If the handle does not correspond to a timeout with
	.Fn callout_schedule			the function
	functions reuse the
	.Fa func			.Fa func
	and			taking the argument
	.Fa arg			.Fa arg
	arguments from the previous callout.			no action is taken. The
	Note that one of the			.Fa handle
	.Fn callout_reset			must be initialized by a previous call to
	functions must always be called to initialize			.Fn timeout ,
	.Fa func			.Fn callout_handle_init
	and			or assigned the value of
	.Fa arg			.Fn CALLOUT_HANDLE_INITIALIZER "&handle"
	before one of the			before being passed to
	.Fn callout_schedule			.Fn untimeout .
	functions can be used.			The behavior of calling
				.Fn untimeout
				with an uninitialized handle
				is undefined.
	.Pp			.Pp
	The callout subsystem provides a softclock thread for each CPU in the system.			.Ft int
	Callouts are assigned to a single CPU and are executed by the softclock thread			.Fn callout_stop "struct callout *c"
	for that CPU.			This function is used to stop a timeout function invocation associated with the callout pointed to by the
	Initially,			.Fa c
	callouts are assigned to CPU 0.			argument, in a non-blocking fashion.
	The			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.
	.Fn callout_reset_on ,			This function returns a non-zero value if the given callout was pending and
	.Fn callout_reset_sbt_on ,			the callback function was prevented from being called.
	.Fn callout_schedule_on			Else a value of zero is returned.
	and			If a lock is associated with the callout given by the
	.Fn callout_schedule_sbt_on			.Fa c
	functions assign the callout to CPU			argument and it is exclusivly locked when this function is called, the
	.Fa cpu .			.Fn callout_stop
	The			function will always ensure that the callback function is never reached.
	.Fn callout_reset_curcpu ,			In other words the callout will be atomically stopped.
	.Fn callout_reset_sbt_curpu ,			Else there is no such guarantee.
	.Fn callout_schedule_curcpu			.Sh DRAINING CALLOUTS
	and			.Ft int
	.Fn callout_schedule_sbt_curcpu			.Fn callout_drain "struct callout *c"
	functions assign the callout to the current CPU.			This function works the same like the
	The			.Fn callout_stop
	.Fn callout_reset ,			function except it ensures that all callback functions have returned and there are no more references to the callout pointed to by the
	.Fn callout_reset_sbt ,			.Fa c
	.Fn callout_schedule			argument inside the callout subsystem before it returns.
	and			Also this function ensures that the lock, if any, associated with the
	.Fn callout_schedule_sbt			callout is no longer being used.
	functions schedule the callout to execute in the softclock thread of the CPU			When this function returns, it is safe to free the callout structure pointed to by the
	to which it is currently assigned.			.Fa c
				argument.
	.Pp			.Pp
				.Ft int
				.Fn callout_drain_async "struct callout c" "callout_func_t fn" "void *arg"
				This function is non-blocking and works the same like the
				.Fn callout_stop
				function except if it returns non-zero it means the callback function pointed to by the
				.Fa fn
				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 this function returns non-zero it should not be called again until the callback function has been called.
				If the
				.Fn callout_drain
				or
				.Fn callout_drain_async
				functions are called while an asynchronous drain is pending,
				previously pending asynchronous drains might get cancelled.
				If this function returns zero, it is safe to free the callout structure pointed to by the
				.Fa c
				argument right away.
				.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.			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			The softclock thread for CPU 0 can be pinned to CPU 0 by setting the
	.Va kern.pin_default_swi			.Va kern.pin_default_swi
	loader tunable to a non-zero value.			loader tunable to a non-zero value.
	Softclock threads for CPUs other than zero can be pinned to their			Softclock threads for CPUs other than zero can be pinned to their
	respective CPUs by setting the			respective CPUs by setting the
	.Va kern.pin_pcpu_swi			.Va kern.pin_pcpu_swi
	loader tunable to a non-zero value.			loader tunable to a non-zero value.
	.Pp			.Sh "AVOIDING RACE CONDITIONS"
	The macros
	.Fn callout_pending ,
	.Fn callout_active
	and
	.Fn callout_deactivate
	provide access to the current state of the callout.
	The
	.Fn callout_pending
	macro checks whether a callout is
	.Em pending ;
	a callout is considered
	.Em 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,
	.Fn callout_pending
	will return
	.Dv FALSE
	even though the callout function may not have finished
	.Pq or even begun
	executing.
	The
	.Fn callout_active
	macro checks whether a callout is marked as
	.Em active ,
	and the
	.Fn callout_deactivate
	macro clears the callout's
	.Em active
	flag.
	The callout subsystem marks a callout as
	.Em active
	when a timeout is set and it clears the
	.Em active
	flag in
	.Fn callout_stop
	and
	.Fn callout_drain ,
	but it
	.Em does not
	clear it when a callout expires normally via the execution of the
	callout function.
	.Ss "Avoiding Race Conditions"
	The callout subsystem invokes callout functions from its own thread			The callout subsystem invokes callout functions from its own thread
	context.			context.
	Without some kind of synchronization,			Without some kind of synchronization,
	it is possible that a callout			it is possible that a callout
	function will be invoked concurrently with an attempt to stop or reset			function will be invoked concurrently with an attempt to stop or reset
	the callout by another thread.			the callout by another thread.
	In particular, since callout functions typically acquire a lock as			In particular, since callout functions typically acquire a lock as
	their first action, the callout function may have already been invoked,			their first action, the callout function may have already been invoked,
	▲ Show 20 Lines • Show All 44 Lines • ▼ Show 20 Lines
	or the			or the
	.Fn callout_reset			.Fn callout_reset
	and			and
	.Fn callout_schedule			.Fn callout_schedule
	function families			function families
	.Pc			.Pc
	indicates whether or not the callout was removed.			indicates whether or not the callout was removed.
	If it is known that the callout was set and the callout function has			If it is known that the callout was set and the callout function has
	not yet executed, then a return value of			not yet executed, then a return value of zero indicates that the
	.Dv FALSE			callout function is about to be called.
	indicates that the callout function is about to be called.
	For example:			For example:
	.Bd -literal -offset indent			.Bd -literal -offset indent
	if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) {			if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) {
	if (callout_stop(&sc->sc_callout)) {			if (callout_stop(&sc->sc_callout)) {
	sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING;			sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING;
	/* successfully stopped */			/* successfully stopped */
	} else {			} else {
	/*			/*
	Show All 39 Lines
	and			and
	.Em pending			.Em pending
	flags before returning.			flags before returning.
	.Pp			.Pp
	The callout function should first check the			The callout function should first check the
	.Em pending			.Em pending
	flag and return without action if			flag and return without action if
	.Fn callout_pending			.Fn callout_pending
	returns			returns non-zero.
	.Dv TRUE .
	This indicates that the callout was rescheduled using			This indicates that the callout was rescheduled using
	.Fn callout_reset			.Fn callout_reset
	just before the callout function was invoked.			just before the callout function was invoked.
	If			If
	.Fn callout_active			.Fn callout_active
	returns			returns zero then the callout function should also return without
	.Dv FALSE			action.
	then the callout function should also return without action.
	This indicates that the callout has been stopped.			This indicates that the callout has been stopped.
	Finally, the callout function should call			Finally, the callout function should call
	.Fn callout_deactivate			.Fn callout_deactivate
	to clear the			to clear the
	.Em active			.Em active
	flag.			flag.
	For example:			For example:
	.Bd -literal -offset indent			.Bd -literal -offset indent
	▲ Show 20 Lines • Show All 53 Lines • ▼ Show 20 Lines
	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			.Sh LEGACY API
	.Bf Sy			.Bf Sy
	The functions below are a legacy API that will be removed in a future release.			The
	New code should not use these routines.
	.Ef
	.Pp
	The function
	.Fn timeout			.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			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			.Fn untimeout
	with an uninitialized handle			functions are a legacy API that will be removed in a future release.
	is undefined.			New code should not use these routines.
	.Pp			.Ef
	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
	The
	.Fn callout_active
	macro returns the state of a callout's
	.Em active
	flag.
	.Pp
	The
	.Fn callout_pending
	macro returns the state of a callout's
	.Em pending
	flag.
	.Pp
	The
	.Fn callout_reset
	and
	.Fn callout_schedule
	function families return non-zero if the callout was pending before the new
	function invocation was scheduled.
	.Pp
	The
	.Fn callout_stop
	and
	.Fn callout_drain
	functions return non-zero if the callout was still pending when it was
	called or zero otherwise.
	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			The current timeout and untimeout routines are 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 slightly 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 this 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			The current implementation replaces the long standing
	.Bx			.Bx
	linked list			linked list
	callout mechanism which offered O(n) insertion and removal running time			callout mechanism which offered O(n) insertion and removal running time
	but did not generate or require handles for untimeout operations.			and did not generate or require handles for untimeout operations.

View Options

usr.sbin/kbdcontrol/kbdcontrol.c

	Show All 23 Lines
	.\" 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$			.\" $FreeBSD$
	.\"			.\"
	.Dd October 8, 2014			.Dd January 24, 2015
	.Dt TIMEOUT 9			.Dt TIMEOUT 9
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm callout_active ,			.Nm callout_active ,
	.Nm callout_deactivate ,			.Nm callout_deactivate ,
	.Nm callout_drain ,			.Nm callout_drain ,
				.Nm callout_drain_async ,
	.Nm callout_handle_init ,			.Nm callout_handle_init ,
	.Nm callout_init ,			.Nm callout_init ,
	.Nm callout_init_mtx ,			.Nm callout_init_mtx ,
	.Nm callout_init_rm ,			.Nm callout_init_rm ,
	.Nm callout_init_rw ,			.Nm callout_init_rw ,
	.Nm callout_pending ,			.Nm callout_pending ,
	.Nm callout_reset ,			.Nm callout_reset ,
	.Nm callout_reset_curcpu ,			.Nm callout_reset_curcpu ,
	Show All 11 Lines
	.Nm timeout ,			.Nm timeout ,
	.Nm untimeout			.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/systm.h			.In sys/systm.h
	.Bd -literal			.Bd -literal
	typedef void timeout_t (void *);			typedef void timeout_t (void *);
				typedef void callout_func_t (void *);
	.Ed			.Ed
	.Ft int
	.Fn callout_active "struct callout *c"
	.Ft void
	.Fn callout_deactivate "struct callout *c"
	.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 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 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 one-time call to an arbitrary function at a
				wblockUnsubmitted Not Done Inline Actions That is kind of a difficult sentence to parse. Does this retain the meaning? API is used to schedule a one-time call to an arbitrary function at a specific future time. wblock: That is kind of a difficult sentence to parse. Does this retain the meaning? API is used to…
	time in the future.			specific time in the future.
	Consumers of this API are required to allocate a callout structure			Consumers of this API are required to allocate a
	.Pq struct callout			.Ft struct callout
	for each pending function invocation.			for each pending function invocation.
	This structure stores state about the pending function invocation including
	the function to be called and the time at which the function should be invoked.
	Pending function calls can be cancelled or rescheduled to a different time.
	In addition,
	a callout structure may be reused to schedule a new function call after a
	scheduled call is completed.
	.Pp
	Callouts only provide a single-shot mode.
	If a consumer requires a periodic timer,
	it must explicitly reschedule each function call.
	This is normally done by rescheduling the subsequent call within the called
	function.
	.Pp
	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.
	.Pp
	Each callout structure must be initialized by
	.Fn callout_init ,
	.Fn callout_init_mtx ,
	.Fn callout_init_rm ,
	or
	.Fn callout_init_rw
	before it is passed to any of the other callout functions.
	The			The
				wblockUnsubmitted Not Done Inline Actions The original is an "aside": Consumers of this API are required to allocate a callout structure (struct callout) for each pending function invocation. The parentheses are probably the wrong markup for the new form, and "struct callout structure" is redundant. Maybe this: Consumers of this API are required to allocate a .Ft struct callout for each pending function invocation. wblock: The original is an "aside": Consumers of this API are required to allocate a callout structure…
				wblockUnsubmitted Not Done Inline Actions Again, better to say the function is deprecated and give a pointer to the replacement in a separate sentence. Then explain what this one does in the next sentence. wblock: Again, better to say the function is deprecated and give a pointer to the replacement in a…
				.Ft struct callout
				stores the full state about any pending function call and
				wblockUnsubmitted Not Done Inline Actions As above, use .Ft and the word "structure" is redundant. wblock: As above, use .Ft and the word "structure" is redundant.
				must be drained by a call to
				wblockUnsubmitted Not Done Inline Actions "should be" is a recommendation. Does it mean I ought to call those functions before freeing, but will work fine without it? Otherwise, consider "must be drained by a call to". wblock: "should be" is a recommendation. Does it mean I ought to call those functions before freeing…
				.Fn callout_drain
				wblockUnsubmitted Not Done Inline Actions .Ft and s/structure// wblock: .Ft and s/structure//
				or
				.Fn callout_drain_async
				before freeing.
				.Sh INITIALIZATION
				wblockUnsubmitted Not Done Inline Actions The rule is to use American English spellings unless the entire document was written with British spellings. See https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/writing-style-guidelines.html wblock: The rule is to use American English spellings unless the entire document was written with…
				.Ft void
				.Fn callout_handle_init "struct callout_handle *handle"
				This function is deprecated.
				wblockUnsubmitted Not Done Inline Actions It would be better to say .Pq Deprecated, see blahblah for current usage. This function is used to prepare a wblock: It would be better to say .Pq Deprecated, see blahblah for current usage. This function is used…
				Please use
	.Fn callout_init			.Fn callout_init
				wblockUnsubmitted Not Done Inline Actions Use .Ft and remove the redundant word "structure". wblock: Use .Ft and remove the redundant word "structure".
	function initializes a callout structure in			instead.
	.Fa c			This function is used to prepare a
	that is not associated with a specific lock.			.Ft struct callout_handle
				before it can be used the first time.
				wblockUnsubmitted Not Done Inline Actions "Was" is a little odd here, but "were" is not quite right either. How about: function will return as if no timeout was pending. wblock: "Was" is a little odd here, but "were" is not quite right either. How about: function will…
				If this function is called on a pending timeout, the pending timeout
				wblockUnsubmitted Not Done Inline Actions .Ft and s/structure// wblock: .Ft and s/structure//
				cannot be cancelled and the
				.Fn untimeout
				function will return as if no timeout was pending.
				wblockUnsubmitted Not Done Inline Actions Missing the word "if". wblock: Missing the word "if".
				.Pp
				.Fn CALLOUT_HANDLE_INITIALIZER "&handle"
				This macro is deprecated.
				This macro is used to statically initialize a
				wblockUnsubmitted Not Done Inline Actions Possessive: application's wblock: Possessive: application's
				.Ft struct callout_handle .
				Please use
				wblockUnsubmitted Not Done Inline Actions Comma: functions, including the wblock: Comma: functions, including the
				.Fn callout_init
				instead.
				.Pp
				.Ft void
				.Fn callout_init "struct callout *c" "int mpsafe"
				wblockUnsubmitted Not Done Inline Actions s/Else/Otherwise,/ wblock: s/Else/Otherwise,/
				This function prepares a
				wblockUnsubmitted Not Done Inline Actions Avoid simultaneous access by obtaining an exclusive lock wblock: Avoid simultaneous access by obtaining an exclusive lock
				.Ft struct callout
				before it can be used.
				This function should not be used when the callout is pending a timeout.
	If the			If the
	.Fa mpsafe			.Fa mpsafe
	argument is zero,			argument is non-zero, the callback function will be running unlocked
				wblockUnsubmitted Not Done Inline Actions Split this long sentence: function is called. It is also expected, but currently not wblock: Split this long sentence: function is called. It is also expected, but currently not
				wblockUnsubmitted Not Done Inline Actions Passive "should be" and should, and "specify a pointer"... How about: argument is a non-zero pointer to a valid wblock: Passive "should be" and should, and "specify a pointer"... How about: argument is a non-zero…
	the callout structure is not considered to be			and the callback is so-called "mpsafe".
	.Dq multi-processor safe ;			.Bf Sy
	and the Giant lock will be acquired before calling the callout function			It is the application's entire responsibility to not call any
				wblockUnsubmitted Not Done Inline Actions This last part needs to be split out into a separate sentence, starting with ", except when the". wblock: This last part needs to be split out into a separate sentence, starting with ", except when…
				wblockUnsubmitted Not Done Inline Actions .Ft and s/structure// wblock: .Ft and s/structure//
	and released when the callout function returns.			.Fn callout_xxx
				wblockUnsubmitted Not Done Inline Actions The specified mutex is expected to be locked when calling any wblock: The specified mutex is expected to be locked when calling any
				functions, including the
				.Fn callout_drain
				wblockUnsubmitted Not Done Inline Actions functions other than the wblock: functions other than the
				function, simultaneously on the same callout when the
				.Fa mpsafe
				argument is non-zero.
				Otherwise, undefined behavior can happen.
				wblockUnsubmitted Not Done Inline Actions British->American: s/behaviour/behavior/ wblock: British->American: s/behaviour/behavior/
				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
				wblockUnsubmitted Not Done Inline Actions Add comma after "zero". wblock: Add comma after "zero".
				any
				.Fn callout_xxx
				functions which start and stop a callout other than the
				.Fn callout_drain
				function.
	.Pp			.Pp
				.Ft void
				.Fn callout_init_mtx "struct callout c" "struct mtx mtx" "int flags"
				wblockUnsubmitted Not Done Inline Actions functions. wblock: functions.
				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			The
	.Fn callout_init_mtx ,			.Fa mtx
	.Fn callout_init_rm ,			argument is a pointer to a valid spinlock type of mutex or a valid
	and			regular non-sleepable mutex which the callback subsystem will lock
	.Fn callout_init_rw			before calling the callback function.
	functions initialize a callout structure in			The specified mutex is expected to be locked when calling any
	.Fa c			.Fn callout_xxx
	that is associated with a specific lock.			functions which start and stop a callout other than the
	The lock is specified by the			.Fn callout_drain
	.Fa mtx ,			function.
	.Fa rm ,			Valid
	or
	.Fa rw
	parameter.
	The associated lock must be held while stopping or rescheduling the
	callout.
	The callout subsystem acquires the associated lock before calling the
	callout function and releases it after the function returns.
	If the callout was cancelled while the callout subsystem waited for the
	associated lock,
	the callout function is not called,
	and the associated lock is released.
	This ensures that stopping or rescheduling the callout will abort any
	previously scheduled invocation.
	.Pp
	Only regular mutexes may be used with
	.Fn callout_init_mtx ;
	spin mutexes are not supported.
	A sleepable read-mostly lock
	.Po
	one initialized with the
	.Dv RM_SLEEPABLE
	flag
	.Pc
	may not be used with
	.Fn callout_init_rm .
	Similarly, other sleepable lock types such as
	.Xr sx 9
	and
	.Xr lockmgr 9
	cannot be used with callouts because sleeping is not permitted in
	the callout subsystem.
	.Pp
	These
	.Fa flags			.Fa flags
	may be specified for			are:
	.Fn callout_init_mtx ,
	.Fn callout_init_rm ,
	or
	.Fn callout_init_rw :
	.Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED"			.Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED"
	.It Dv CALLOUT_RETURNUNLOCKED			.It Dv CALLOUT_RETURNUNLOCKED
	The callout function will release the associated lock itself,			The callout function is assumed to have released the specified mutex
	so the callout subsystem should not attempt to unlock it			before returning.
	after the callout function returns.			.It Dv 0
				wblockUnsubmitted Not Done Inline Actions s/Else/Otherwise,/ wblock: s/Else/Otherwise,/
	.It Dv CALLOUT_SHAREDLOCK			The callout subsystem will release the specified mutex after the
	The lock is only acquired in read mode when running the callout handler.			callout function has returned.
				wblockUnsubmitted Not Done Inline Actions The callout function is assumed to have released the specified wblock: The callout function is assumed to have released the specified
	This flag is ignored by
	.Fn callout_init_mtx .
	.El			.El
	.Pp			.Pp
	The function			.Ft void
	.Fn callout_stop			.Fn callout_init_rm "struct callout c" "struct rmlock rm" "int flags"
	cancels a callout			This function is similar to
	.Fa c			.Fn callout_init_mtx ,
	if it is currently pending.			but it accepts a read-mostly type of lock.
	If the callout is pending, then			The read-mostly lock must not be initialized with the
	.Fn callout_stop			.Dv RM_SLEEPABLE
	returns a non-zero value.			flag.
	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 lock,
	then that lock must be held when this function is called.
	.Pp			.Pp
	The function			.Ft void
	.Fn callout_drain			.Fn callout_init_rw "struct callout c" "struct rwlock rw" "int flags"
	is identical to			This function is similar to
	.Fn callout_stop			.Fn callout_init_mtx ,
	except that it will wait for the callout			but it accepts a read/write type of lock.
	.Fa c			.Sh SCHEDULING CALLOUTS
	to complete if it is already in progress.			.Ft struct callout_handle
	This function MUST NOT be called while holding any			.Fn timeout "timeout_t func" "void arg" "int ticks"
	locks on which the callout might block, or deadlock will result.			This function is deprecated.
	Note that if the callout subsystem has already begun processing this			Please use
	callout, then the callout function may be invoked before
	.Fn callout_drain
	returns.
	However, the callout subsystem does guarantee that the callout will be
	fully stopped before
	.Fn callout_drain
	returns.
	.Pp
	The
	.Fn callout_reset			.Fn callout_reset
	and			instead.
	.Fn callout_schedule			This function schedules a call to
				wblockUnsubmitted Not Done Inline Actions This function is similar to the wblock: This function is similar to the
	function families schedule a future function invocation for callout			.Fa func
				wblockUnsubmitted Not Done Inline Actions This function is similar to the wblock: This function is similar to the
	.Fa c .			to take place after
				wblockUnsubmitted Not Done Inline Actions function, but accepts a read-mostly type of lock. wblock: function, but accepts a read-mostly type of lock.
	If
	.Fa c
	already has a pending callout,
	it is cancelled before the new invocation is scheduled.
	These functions return a non-zero value 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.
	.Pp
	The time at which the callout function will be invoked is determined by
	either the
	.Fa ticks
	argument or the
	.Fa sbt ,
	.Fa pr ,
	and
	.Fa flags
	arguments.
	When
	.Fa ticks
	is used,
	the callout is scheduled to execute after
	.Fa ticks Ns No /hz			.Fa ticks Ns No /hz
				wblockUnsubmitted Not Done Inline Actions s/initialised/initialized/ wblock: s/initialised/initialized/
				wblockUnsubmitted Not Done Inline Actions function, but accepts a reader-writer type of lock. Should that be "read/write" instead? wblock: function, but accepts a reader-writer type of lock. Should that be "read/write" instead?
	seconds.			seconds.
	Non-positive values of			Non-positive values of
	.Fa ticks			.Fa ticks
	are silently converted to the value			are silently converted to the value
				wblockUnsubmitted Not Done Inline Actions As above, separate sentence to say it is deprecated and point to the replacement. wblock: As above, separate sentence to say it is deprecated and point to the replacement.
	.Sq 1 .			.Sq 1 .
	.Pp
	The			The
	.Fa sbt ,			.Fa func
	.Fa pr ,			argument is a valid pointer to a function that takes a single
				wblockUnsubmitted Not Done Inline Actions argument is a valid pointer to a function that takes a single wblock: argument is a valid pointer to a function that takes a single
	and			.Fa void *
	.Fa flags			argument.
	arguments provide more control over the scheduled time including			Upon invocation, the
	support for higher resolution times,			.Fa func
	specifying the precision of the scheduled time,			function will receive
	and setting an absolute deadline instead of a relative timeout.			.Fa arg
	The callout is scheduled to execute in a time window which begins at			as its only argument.
	the time specified in			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.
				wblockUnsubmitted Not Done Inline Actions "canceled" is spelled "cancelled" elsewhere in this man page. The first is modern American. wblock: "canceled" is spelled "cancelled" elsewhere in this man page. The first is modern American.
				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 a non-zero value if the given callout was pending and
				the callback function was prevented from being called.
				Otherwise, a value of zero is returned.
				wblockUnsubmitted Not Done Inline Actions s/Else/Otherwise,/ wblock: s/Else/Otherwise,/
				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
				wblockUnsubmitted Not Done Inline Actions s/called/called,/ wblock: s/called/called,/
				function will always ensure that previous callback function, if any,
				is never reached.
				In other words, the callout will be atomically restarted.
				wblockUnsubmitted Not Done Inline Actions s/words/words,/ wblock: s/words/words,/
				Otherwise, there is no such guarantee.
				wblockUnsubmitted Not Done Inline Actions s/Else/Otherwise,/ wblock: s/Else/Otherwise,/
				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
				wblockUnsubmitted Not Done Inline Actions s/Else/Otherwise,/ wblock: s/Else/Otherwise,/
				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			.Fa sbt
	and extends for the amount of time specified in			argument and extends for the amount of time specified in
	.Fa pr .			.Fa pr .
				This function is used when high precision timeouts are needed.
				wblockUnsubmitted Not Done Inline Actions s/timeouts./timeouts are needed./ wblock: s/timeouts./timeouts are needed./
	If			If
				wblockUnsubmitted Not Done Inline Actions Use "cannot". "can not" with a space means "not doing it is allowed". wblock: Use "cannot". "can not" with a space means "not doing it is allowed".
	.Fa sbt			.Fa sbt
	specifies a time in the past,			specifies a time in the past,
				wblockUnsubmitted Not Done Inline Actions .Fa pr argument. is redundant, and can be just .Fa pr . (There are lots of these.) wblock: .Fa pr argument. is redundant, and can be just .Fa pr . (There are lots of these.)
				wblockUnsubmitted Not Done Inline Actions Again, redundant. Can be just If .Fa sbt specifies... wblock: Again, redundant. Can be just If .Fa sbt specifies...
	the window is adjusted to start at the current time.			the window is adjusted to start at the current time.
				wblockUnsubmitted Not Done Inline Actions Avoid the informal use of "you": This function is used when high precision timeouts are needed. wblock: Avoid the informal use of "you": This function is used when high precision timeouts are needed.
	A non-zero value for			A non-zero value for
	.Fa pr			.Fa pr
	allows the callout subsystem to coalesce callouts scheduled close to each			allows the callout subsystem to coalesce callouts scheduled close to each
	other into fewer timer interrupts,			other into fewer timer interrupts,
	reducing processing overhead and power consumption.			reducing processing overhead and power consumption.
				wblockUnsubmitted Not Done Inline Actions s/Else/Otherwise,/ wblock: s/Else/Otherwise,/
	These			The
	.Fa flags			.Fa flags
	may be specified to adjust the interpretation of			argument may be non-zero to adjust the interpretation of the
	.Fa sbt			.Fa sbt
	and			and
	.Fa pr :			.Fa pr
				arguments:
				wblockUnsubmitted Not Done Inline Actions "the" is not needed here. wblock: "the" is not needed here.
	.Bl -tag -width ".Dv C_DIRECT_EXEC"			.Bl -tag -width ".Dv C_DIRECT_EXEC"
	.It Dv C_ABSOLUTE			.It Dv C_ABSOLUTE
	Handle the			Handle the
	.Fa sbt			.Fa sbt
	argument as an absolute time since boot.			argument as an absolute time since boot.
	By default,			By default,
	.Fa sbt			.Fa sbt
	is treated as a relative amount of time,			is treated as a relative amount of time,
				wblockUnsubmitted Not Done Inline Actions Again, can just be By default, .Fa sbt is treated... Also, "is treated as". wblock: Again, can just be By default, .Fa sbt is treated... Also, "is treated as".
	similar to			similar to
	.Fa ticks .			.Fa ticks .
	.It Dv C_DIRECT_EXEC			.It Dv C_DIRECT_EXEC
	Run the handler directly from hardware interrupt context instead of from the			Run the handler directly from hardware interrupt context instead of from the
	softclock thread.			softclock thread.
	This reduces latency and overhead, but puts more constraints on the callout			This reduces latency and overhead, but puts more constraints on the callout
	function.			function.
	Callout functions run in this context may use only spin mutexes for locking			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.			and should be as small as possible because they run with absolute priority.
	.It Fn C_PREL			.It Fn C_PREL
	Specifies relative event time precision as binary logarithm of time interval			Specifies relative event time precision as binary logarithm of time interval
	divided by acceptable time deviation: 1 -- 1/2, 2 -- 1/4, etc.			divided by acceptable time deviation: 1 -- 1/2, 2 -- 1/4, and so on.
				wblockUnsubmitted Not Done Inline Actions Needs a serial comma before "and": ...1/4, and so on. wblock: Needs a serial comma before "and": ...1/4, and so on.
	Note that the larger of			Note that the larger of
	.Fa pr			.Fa pr
	or this value is used as the length of the time window.			or this value is used as the length of the time window.
	Smaller values			Smaller values
	.Pq which result in larger time intervals			.Pq which result in larger time intervals
	allow the callout subsystem to aggregate more events in one timer interrupt.			allow the callout subsystem to aggregate more events in one timer interrupt.
	.It Dv C_HARDCLOCK			.It Dv C_HARDCLOCK
	Align the timeouts to			Align the timeouts to
	.Fn hardclock			.Fn hardclock
	calls if possible.			calls if possible.
	.El			.El
	.Pp			.Pp
	The			.Ft int
	.Fn callout_reset			.Fn callout_reset_sbt_curcpu "struct callout *c" "sbintime_t sbt" \
	functions accept a			"sbintime_t pr" "callout_func_t func" "void arg" "int flags"
				This function works like
				wblockUnsubmitted Not Done Inline Actions This function works like wblock: This function works like
				.Fn callout_reset_sbt ,
				wblockUnsubmitted Not Done Inline Actions .Fn callout_reset_sbt , wblock: .Fn callout_reset_sbt ,
				except the callback function given by the
				wblockUnsubmitted Not Done Inline Actions except the callback function given by wblock: except the callback function given by
				wblockUnsubmitted Not Done Inline Actions s/by/by the/ wblock: s/by/by the/
	.Fa func			.Fa func
	argument which identifies the function to be called when the time expires.			argument will be executed on the CPU which called this function.
				wblockUnsubmitted Not Done Inline Actions will be executed on the CPU which called this function. wblock: will be executed on the CPU which called this function.
	It must be a pointer to a function that takes a single			.Pp
	.Fa void *			.Ft int
				.Fn callout_reset_sbt_on "struct callout *c" "sbintime_t sbt" \
				wblockUnsubmitted Not Done Inline Actions Refer to .Fa callout_init . wblock: Refer to .Fa callout_init .
				"sbintime_t pr" "callout_func_t func" "void arg" "int cpu" "int flags"
				This function works like
				.Fn callout_reset_sbt ,
				wblockUnsubmitted Not Done Inline Actions If this means "CPU selection cannot be changed while the callout subsystem is processing the callback for completion.", then s/can not/cannot/. wblock: If this means "CPU selection cannot be changed while the callout subsystem is processing the…
				except the callback function given by
				wblockUnsubmitted Not Done Inline Actions s/CPU/the CPU/ wblock: s/CPU/the CPU/
				.Fa func
				wblockUnsubmitted Not Done Inline Actions Otherwise, the callback function given by wblock: Otherwise, the callback function given by
				will be executed on the CPU given by
				.Fa cpu .
				wblockUnsubmitted Not Done Inline Actions will be executed on the same CPU... The rest of that line is unclear. As shown previously in the man page? As run previously on the CPU? wblock: will be executed on the same CPU... The rest of that line is unclear. As shown previously in…
				.Pp
				.Ft int
				.Fn callout_schedule "struct callout *c" "int ticks"
				This function works the same like the
				wblockUnsubmitted Not Done Inline Actions s/by the/by/ Either "given by the func argument will" or "given by func will". The second is less wordy, wblock: s/by the/by/ Either "given by the func argument will" or "given by func will". The second is…
				.Fn callout_reset
				wblockUnsubmitted Not Done Inline Actions 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 . wblock: This function works like .Fn callout_reset_sbt , except the callback function given by .Fa func…
				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_drain_async
				function is called on the same callout as given by the
				.Fa c
	argument.			argument.
	Upon invocation,			.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			.Fa func
	will receive			argument and having the
	.Fa arg			.Fa arg
	as its only argument.			arguments to validate the handle.
	The			If the handle does not correspond to a timeout with
	.Fn callout_schedule			the function
	functions reuse the
	.Fa func			.Fa func
	and			taking the argument
	.Fa arg			.Fa arg
	arguments from the previous callout.			no action is taken. The
	Note that one of the			.Fa handle
	.Fn callout_reset			must be initialized by a previous call to
	functions must always be called to initialize			.Fn timeout ,
	.Fa func			.Fn callout_handle_init
	and			or assigned the value of
	.Fa arg			.Fn CALLOUT_HANDLE_INITIALIZER "&handle"
	before one of the			before being passed to
	.Fn callout_schedule			.Fn untimeout .
	functions can be used.			The behavior of calling
				.Fn untimeout
				with an uninitialized handle
				is undefined.
	.Pp			.Pp
	The callout subsystem provides a softclock thread for each CPU in the system.			.Ft int
	Callouts are assigned to a single CPU and are executed by the softclock thread			.Fn callout_stop "struct callout *c"
	for that CPU.			This function is used to stop a timeout function invocation associated with the callout pointed to by the
	Initially,			.Fa c
	callouts are assigned to CPU 0.			argument, in a non-blocking fashion.
	The			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.
	.Fn callout_reset_on ,			This function returns a non-zero value if the given callout was pending and
	.Fn callout_reset_sbt_on ,			the callback function was prevented from being called.
	.Fn callout_schedule_on			Else a value of zero is returned.
	and			If a lock is associated with the callout given by the
	.Fn callout_schedule_sbt_on			.Fa c
	functions assign the callout to CPU			argument and it is exclusivly locked when this function is called, the
	.Fa cpu .			.Fn callout_stop
	The			function will always ensure that the callback function is never reached.
	.Fn callout_reset_curcpu ,			In other words the callout will be atomically stopped.
	.Fn callout_reset_sbt_curpu ,			Else there is no such guarantee.
	.Fn callout_schedule_curcpu			.Sh DRAINING CALLOUTS
	and			.Ft int
	.Fn callout_schedule_sbt_curcpu			.Fn callout_drain "struct callout *c"
	functions assign the callout to the current CPU.			This function works the same like the
	The			.Fn callout_stop
	.Fn callout_reset ,			function except it ensures that all callback functions have returned and there are no more references to the callout pointed to by the
	.Fn callout_reset_sbt ,			.Fa c
	.Fn callout_schedule			argument inside the callout subsystem before it returns.
	and			Also this function ensures that the lock, if any, associated with the
	.Fn callout_schedule_sbt			callout is no longer being used.
	functions schedule the callout to execute in the softclock thread of the CPU			When this function returns, it is safe to free the callout structure pointed to by the
	to which it is currently assigned.			.Fa c
				argument.
	.Pp			.Pp
				.Ft int
				.Fn callout_drain_async "struct callout c" "callout_func_t fn" "void *arg"
				This function is non-blocking and works the same like the
				.Fn callout_stop
				function except if it returns non-zero it means the callback function pointed to by the
				.Fa fn
				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 this function returns non-zero it should not be called again until the callback function has been called.
				If the
				.Fn callout_drain
				or
				.Fn callout_drain_async
				functions are called while an asynchronous drain is pending,
				previously pending asynchronous drains might get cancelled.
				If this function returns zero, it is safe to free the callout structure pointed to by the
				.Fa c
				argument right away.
				.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.			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			The softclock thread for CPU 0 can be pinned to CPU 0 by setting the
	.Va kern.pin_default_swi			.Va kern.pin_default_swi
	loader tunable to a non-zero value.			loader tunable to a non-zero value.
	Softclock threads for CPUs other than zero can be pinned to their			Softclock threads for CPUs other than zero can be pinned to their
	respective CPUs by setting the			respective CPUs by setting the
	.Va kern.pin_pcpu_swi			.Va kern.pin_pcpu_swi
	loader tunable to a non-zero value.			loader tunable to a non-zero value.
	.Pp			.Sh "AVOIDING RACE CONDITIONS"
	The macros
	.Fn callout_pending ,
	.Fn callout_active
	and
	.Fn callout_deactivate
	provide access to the current state of the callout.
	The
	.Fn callout_pending
	macro checks whether a callout is
	.Em pending ;
	a callout is considered
	.Em 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,
	.Fn callout_pending
	will return
	.Dv FALSE
	even though the callout function may not have finished
	.Pq or even begun
	executing.
	The
	.Fn callout_active
	macro checks whether a callout is marked as
	.Em active ,
	and the
	.Fn callout_deactivate
	macro clears the callout's
	.Em active
	flag.
	The callout subsystem marks a callout as
	.Em active
	when a timeout is set and it clears the
	.Em active
	flag in
	.Fn callout_stop
	and
	.Fn callout_drain ,
	but it
	.Em does not
	clear it when a callout expires normally via the execution of the
	callout function.
	.Ss "Avoiding Race Conditions"
	The callout subsystem invokes callout functions from its own thread			The callout subsystem invokes callout functions from its own thread
	context.			context.
	Without some kind of synchronization,			Without some kind of synchronization,
	it is possible that a callout			it is possible that a callout
	function will be invoked concurrently with an attempt to stop or reset			function will be invoked concurrently with an attempt to stop or reset
	the callout by another thread.			the callout by another thread.
	In particular, since callout functions typically acquire a lock as			In particular, since callout functions typically acquire a lock as
	their first action, the callout function may have already been invoked,			their first action, the callout function may have already been invoked,
	▲ Show 20 Lines • Show All 44 Lines • ▼ Show 20 Lines
	or the			or the
	.Fn callout_reset			.Fn callout_reset
	and			and
	.Fn callout_schedule			.Fn callout_schedule
	function families			function families
	.Pc			.Pc
	indicates whether or not the callout was removed.			indicates whether or not the callout was removed.
	If it is known that the callout was set and the callout function has			If it is known that the callout was set and the callout function has
	not yet executed, then a return value of			not yet executed, then a return value of zero indicates that the
	.Dv FALSE			callout function is about to be called.
	indicates that the callout function is about to be called.
	For example:			For example:
	.Bd -literal -offset indent			.Bd -literal -offset indent
	if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) {			if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) {
	if (callout_stop(&sc->sc_callout)) {			if (callout_stop(&sc->sc_callout)) {
	sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING;			sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING;
	/* successfully stopped */			/* successfully stopped */
	} else {			} else {
	/*			/*
	Show All 39 Lines
	and			and
	.Em pending			.Em pending
	flags before returning.			flags before returning.
	.Pp			.Pp
	The callout function should first check the			The callout function should first check the
	.Em pending			.Em pending
	flag and return without action if			flag and return without action if
	.Fn callout_pending			.Fn callout_pending
	returns			returns non-zero.
	.Dv TRUE .
	This indicates that the callout was rescheduled using			This indicates that the callout was rescheduled using
	.Fn callout_reset			.Fn callout_reset
	just before the callout function was invoked.			just before the callout function was invoked.
	If			If
	.Fn callout_active			.Fn callout_active
	returns			returns zero then the callout function should also return without
	.Dv FALSE			action.
	then the callout function should also return without action.
	This indicates that the callout has been stopped.			This indicates that the callout has been stopped.
	Finally, the callout function should call			Finally, the callout function should call
	.Fn callout_deactivate			.Fn callout_deactivate
	to clear the			to clear the
	.Em active			.Em active
	flag.			flag.
	For example:			For example:
	.Bd -literal -offset indent			.Bd -literal -offset indent
	▲ Show 20 Lines • Show All 53 Lines • ▼ Show 20 Lines
	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			.Sh LEGACY API
	.Bf Sy			.Bf Sy
	The functions below are a legacy API that will be removed in a future release.			The
	New code should not use these routines.
	.Ef
	.Pp
	The function
	.Fn timeout			.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			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			.Fn untimeout
	with an uninitialized handle			functions are a legacy API that will be removed in a future release.
	is undefined.			New code should not use these routines.
	.Pp			.Ef
	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
	The
	.Fn callout_active
	macro returns the state of a callout's
	.Em active
	flag.
	.Pp
	The
	.Fn callout_pending
	macro returns the state of a callout's
	.Em pending
	flag.
	.Pp
	The
	.Fn callout_reset
	and
	.Fn callout_schedule
	function families return non-zero if the callout was pending before the new
	function invocation was scheduled.
	.Pp
	The
	.Fn callout_stop
	and
	.Fn callout_drain
	functions return non-zero if the callout was still pending when it was
	called or zero otherwise.
	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			The current timeout and untimeout routines are 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 slightly 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 this 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			The current implementation replaces the long standing
	.Bx			.Bx
	linked list			linked list
	callout mechanism which offered O(n) insertion and removal running time			callout mechanism which offered O(n) insertion and removal running time
	but did not generate or require handles for untimeout operations.			and did not generate or require handles for untimeout operations.

fix legacy psm/atkbc build after c51978f4b2f0, unlock new settings from NOTES via userland
AbandonedPublic
Actions

Details

Diff Detail

Event Timeline

Revision Contents
Changeset List

Diff 117994

sys/dev/atkbdc/psm.c

usr.sbin/kbdcontrol/kbdcontrol.1

usr.sbin/kbdcontrol/kbdcontrol.c

fix legacy psm/atkbc build after c51978f4b2f0, unlock new settings from NOTES via userlandAbandonedPublicActions

Details

Diff Detail

Event Timeline

Revision ContentsChangeset List

Diff 117994

sys/dev/atkbdc/psm.c

usr.sbin/kbdcontrol/kbdcontrol.1

usr.sbin/kbdcontrol/kbdcontrol.c

fix legacy psm/atkbc build after c51978f4b2f0, unlock new settings from NOTES via userland
AbandonedPublic
Actions

Revision Contents
Changeset List