On Wed, Jun 23, 2021 at 06:57:00PM -0500, Scott Cheloha wrote: > Hi, > > I want to document kclock timeouts so others can use them. >
morning. reads fine, except one issue: > > Index: share/man/man9/timeout.9 > =================================================================== > RCS file: /cvs/src/share/man/man9/timeout.9,v > retrieving revision 1.53 > diff -u -p -r1.53 timeout.9 > --- share/man/man9/timeout.9 11 May 2021 13:29:25 -0000 1.53 > +++ share/man/man9/timeout.9 23 Jun 2021 23:39:04 -0000 > @@ -44,7 +44,7 @@ > .Nm timeout_triggered , > .Nm TIMEOUT_INITIALIZER , > .Nm TIMEOUT_INITIALIZER_FLAGS > -.Nd execute a function after a specified period of time > +.Nd execute a function in the future > .Sh SYNOPSIS > .In sys/types.h > .In sys/timeout.h > @@ -55,12 +55,13 @@ > .Fa "struct timeout *to" > .Fa "void (*fn)(void *)" > .Fa "void *arg" > +.Fa "int kclock" > .Fa "int flags" > .Fc > .Ft void > .Fn timeout_set_proc "struct timeout *to" "void (*fn)(void *)" "void *arg" > .Ft int > -.Fn timeout_add "struct timeout *to" "int ticks" > +.Fn timeout_add "struct timeout *to" "int nticks" > .Ft int > .Fn timeout_del "struct timeout *to" > .Ft int > @@ -83,174 +84,218 @@ > .Fn timeout_add_usec "struct timeout *to" "int usec" > .Ft int > .Fn timeout_add_nsec "struct timeout *to" "int nsec" > -.Fn TIMEOUT_INITIALIZER "void (*fn)(void *)" "void *arg" > -.Fn TIMEOUT_INITIALIZER_FLAGS "void (*fn)(void *)" "void *arg" "int flags" > +.Ft int > +.Fn timeout_in_nsec "struct timeout *to" "uint64_t nsecs" > +.Ft int > +.Fn timeout_at_ts "struct timeout *to" "const struct timespec *abs" > +.Fo TIMEOUT_INITIALIZER > +.Fa "void (*fn)(void *)" > +.Fa "void *arg" > +.Fc > +.Fo TIMEOUT_INITIALIZER_FLAGS > +.Fa "void (*fn)(void *)" > +.Fa "void *arg" > +.Fa "int kclock" > +.Fa "int flags" > +.Fc > .Sh DESCRIPTION > The > .Nm timeout > -API provides a mechanism to execute a function at a given time. > -The granularity of the time is limited by the granularity of the > -.Xr hardclock 9 > -timer which executes > -.Xr hz 9 > -times a second. > +API provides a mechanism to schedule an arbitrary function for asynchronous > +execution in the future. > .Pp > -It is the responsibility of the caller to provide these functions with > -pre-allocated timeout structures. > +All state is encapsulated in a caller-allocated timeout structure > +.Pq hereafter, a Qo timeout Qc . > +A timeout must be initialized before it may be used as input to other > +functions in the API. > .Pp > The > .Fn timeout_set > -function prepares the timeout structure > -.Fa to > -to be used in future calls to > -.Fn timeout_add > -and > -.Fn timeout_del . > -The timeout will be prepared to call the function specified by the > +function initializes the timeout > +.Fa to . > +When executed, > +the timeout will call the function > .Fa fn > -argument with a > -.Fa void * > -argument given in the > +with > .Fa arg > -argument. > -Once initialized, the > -.Fa to > -structure can be used repeatedly in > -.Fn timeout_add > -and > -.Fn timeout_del > -and does not need to be reinitialized unless > -the function called and/or its argument must change. > +as its first parameter. > +The timeout is implicitly scheduled against the > +.Dv KCLOCK_NONE > +clock and is not configured with any additional flags. > .Pp > The > .Fn timeout_set_flags > function is similar to > -.Fn timeout_set > -but it additionally accepts the bitwise OR of zero or more of the > -following > +.Fn timeout_set , > +except that it takes two additional parameters: > +.Bl -tag -width kclock > +.It Fa kclock > +The timeout is scheduled against the given > +.Fa kclock, you need a space between kclock and the comma jmc > +which must be one of the following: > +.Bl -tag -width KCLOCK_UPTIME > +.It Dv KCLOCK_NONE > +Low resolution tick-based clock. > +The granularity of this clock is limited by the > +.Xr hardclock 9 , > +which executes roughly > +.Xr hz 9 > +times per second. > +.It Dv KCLOCK_UPTIME > +The uptime clock. > +Counts the time elapsed since the system booted. > +.El > +.It Fa flags > +The timeout's behavior may be configured with the bitwise OR of > +zero or more of the following > .Fa flags : > -.Bl -tag -width TIMEOUT_PROC -offset indent > +.Bl -tag -width TIMEOUT_PROC > .It Dv TIMEOUT_PROC > -Runs the timeout in a process context instead of the default > +Execute the timeout in a process context instead of the default > .Dv IPL_SOFTCLOCK > interrupt context. > .El > +.El > .Pp > The > .Fn timeout_set_proc > -function is similar to > +function is equivalent to > +.Fn timeout_set , > +except that the given timeout is configured with the > +.Dv TIMEOUT_PROC > +flag. > +.Pp > +A timeout may also be initialized statically. > +The > +.Fn TIMEOUT_INITIALIZER > +macro is equivalent to the > .Fn timeout_set > -but it runs the timeout in a process context instead of the default > -.Dv IPL_SOFTCLOCK > -interrupt context. > +function, > +and the > +.Fn TIMEOUT_INITIALIZER_FLAGS > +macro is equivalent to the > +.Fn timeout_set_flags > +function. > .Pp > -The function > -.Fn timeout_add > -schedules the execution of the > +The interfaces available for scheduling a timeout vary with the timeout's > +.Fa kclock . > +.Pp > +.Dv KCLOCK_NONE > +timeouts may be scheduled with the function > +.Fn timeout_add , > +which arms > .Fa to > -timeout in at least > -.Fa ticks Ns /hz > +for execution after > +.Fa nticks > +.Xr hardclock 9 > +ticks have elapsed > +.Pq see Xr hz 9 for details . > +In practice, > +.Fa nticks > +ticks will usually elapse in slightly less than > +.Fa nticks Ns /hz > seconds. > Negative values of > -.Fa ticks > +.Fa nticks > are illegal. > -If the value is > -.Sq 0 > -it will, in the current implementation, be treated as > -.Sq 1 , > -but in the future it might cause an immediate timeout. > -The timeout in the > +If > +.Fa nticks > +is zero it will be silently rounded up to one. > +.Pp > +For convenience, > +.Dv KCLOCK_NONE > +timeouts may also be scheduled with > +.Fn timeout_add_sec , > +.Fn timeout_add_msec , > +.Fn timeout_add_usec , > +.Fn timeout_add_nsec , > +or > +.Fn timeout_add_tv . > +These wrapper functions convert their inputs to a count of ticks before > +calling > +.Fn timeout_add > +to schedule the given timeout. > +.Pp > +.Dv KCLOCK_UPTIME > +timeouts may be scheduled with > +.Fn timeout_in_nsec , > +which arms > .Fa to > -argument must be already initialized by > -.Fn timeout_set , > -.Fn timeout_set_flags , > +to execute after at least > +.Fa nsecs > +nanoseconds have elapsed, > +or with > +.Fn timeout_at_ts , > +which arms > +.Fa to > +to execute at or after the absolute time > +.Fa abs > +has elapsed on the system uptime clock. > +.Pp > +Once scheduled, > +a timeout may not be reinitialized with > +.Fn timeout_set > or > -.Fn timeout_set_proc > -and may not be used in calls to > -.Fn timeout_set , > -.Fn timeout_set_flags , > +.Fn timeout_set_flags > +until it has executed or been cancelled with > +.Fn timeout_del > or > -.Fn timeout_set_proc > -until it has timed out or been removed with > -.Fn timeout_del . > -If the timeout in the > -.Fa to > -argument is already scheduled, the old execution time will be > -replaced by the new one. > +.Fn timeout_del_barrier . > +.Pp > +A pending timeout may be rescheduled without first cancelling it with > +.Fn timeout_del > +or > +.Fn timeout_del_barrier . > +The new expiration time will quietly supersede the original. > .Pp > The function > .Fn timeout_del > -will cancel the timeout in the argument > +cancels any pending execution of > .Fa to . > -If the timeout has already executed or has never been added > +If the timeout has already executed or was never scheduled > the call will have no effect. > .Pp > +The > .Fn timeout_del_barrier > -is like > -.Fn timeout_del > -but it will wait until any current execution of the timeout has completed. > +function is similar to > +.Fn timeout_del , > +except that it may block until any current execution of the timeout > +.Fa to > +has completed. > .Pp > +The > .Fn timeout_barrier > -ensures that any current execution of the timeout in the argument > +function blocks until any current execution of the timeout > .Fa to > -has completed before returning. > +has completed. > .Pp > The > .Fn timeout_pending > -macro can be used to check if a timeout is scheduled to run. > +macro indicates whether the given timeout is scheduled for execution. > +A timeout's pending status is cleared when it is executed or cancelled. > .Pp > The > .Fn timeout_initialized > -macro can be used to check if a timeout has been initialized. > +macro indicates whether the given timeout has been initialized with > +.Fn timeout_set > +or > +.Fn timeout_set_flags . > +This macro must not be used unless the memory underlying > +.Fa to > +has been zeroed. > .Pp > The > .Fn timeout_triggered > -macro can be used to check if a timeout is running or has been run. > -The > -.Fn timeout_add > -and > -.Fn timeout_del > -functions clear the triggered state for that timeout. > -.Pp > -When possible, use the > -.Fn timeout_add_tv , > -.Fn timeout_add_sec , > -.Fn timeout_add_msec , > -.Fn timeout_add_usec , > -and > -.Fn timeout_add_nsec > -functions instead of > -.Fn timeout_add . > -Those functions add a timeout whilst converting the time specified > -by the respective types. > -They also defer the timeout handler for at least one tick if called > -with a positive value. > -.Pp > -A timeout declaration can be initialised with the > -.Fn TIMEOUT_INITIALIZER > -macro. > -The timeout will be prepared to call the function specified by the > -.Fa fn > -argument with the > -.Fa void * > -argument given in > -.Fa arg . > -.Pp > -The > -.Fn TIMEOUT_INITIALIZER_FLAGS > -macro is similar to > -.Fn TIMEOUT_INITIALIZER , > -but it accepts additional flags. > -See the > -.Fn timeout_set_flags > -function for details. > +macro indicates whether the given timeout is executing or has finished > +executing. > +Rescheduling or cancelling a timeout clears its triggered status. > .Sh CONTEXT > .Fn timeout_set , > .Fn timeout_set_flags , > -and > -.Fn timeout_set_proc > -can be called during autoconf, from process context, or from interrupt > -context. > +and timeout_set_proc > +can be called during autoconf, > +from process context, > +or from interrupt context. > .Pp > .Fn timeout_add , > .Fn timeout_add_sec , > @@ -258,54 +303,52 @@ context. > .Fn timeout_add_nsec , > .Fn timeout_add_usec , > .Fn timeout_add_tv , > +.Fn timeout_in_nsec , > +.Fn timeout_at_ts , > .Fn timeout_del , > .Fn timeout_pending , > .Fn timeout_initialized , > +and > .Fn timeout_triggered > -can be called during autoconf, from process context, or from any > -interrupt context at or below > +can be called during autoconf, > +from process context, > +or from any interrupt context at or below > .Dv IPL_CLOCK . > .Pp > +The > .Fn timeout_barrier > and > .Fn timeout_del_barrier > -can be called from process context. > +functions may only be called from a process context. > .Pp > -When the timeout runs, the > +When a timeout is executed, > +the function > .Fa fn > -argument to > -.Fn timeout_set > -or > -.Fn timeout_set_flags > -will be called in an interrupt context at > +given at initialization will be called in an interrupt context at > .Dv IPL_SOFTCLOCK > or a process context if the > .Dv TIMEOUT_PROC > -flag was given at initialization. > -The > -.Fa fn > -argument to > -.Fn timeout_set_proc > -will be called in a process context. > +flag was set. > .Sh RETURN VALUES > .Fn timeout_add , > .Fn timeout_add_sec , > .Fn timeout_add_msec , > .Fn timeout_add_nsec , > .Fn timeout_add_usec , > -and > .Fn timeout_add_tv > +.Fn timeout_in_nsec , > +and > +.Fn timeout_at_ts > will return 1 if the timeout > .Fa to > -was added to the timeout schedule or 0 if it was already queued. > +was newly scheduled or 0 if the timeout was already pending. > .Pp > .Fn timeout_del > and > .Fn timeout_del_barrier > will return 1 if the timeout > .Fa to > -was removed from the pending timeout schedule or 0 if it was not > -currently queued. > +was pending or 0 otherwise. > .Sh CODE REFERENCES > These functions are implemented in the file > .Pa sys/kern/kern_timeout.c .
