NAME
clockintr_bind
,
clockintr_schedule
,
clockintr_advance
,
clockintr_cancel
,
clockintr_unbind
,
clockintr_stagger
,
clockrequest_advance
—
execute a function in a clock interrupt
context
SYNOPSIS
#include
<sys/clockintr.h>
void
clockintr_bind
(struct clockintr
*cl, struct cpu_info *cpu, void
(*callback)(struct clockrequest *cr, void *cf, void *arg),
void *arg);
void
clockintr_schedule
(struct clockintr
*cl, uint64_t abs);
uint64_t
clockintr_advance
(struct clockintr
*cl, uint64_t interval);
void
clockintr_cancel
(struct clockintr
*cl);
void
clockintr_unbind
(struct clockintr
*cl, uint32_t flags);
void
clockintr_stagger
(struct clockintr
*cl, uint64_t interval, uint32_t
numer, uint32_t denom);
uint64_t
clockrequest_advance
(struct
clockrequest *cr, uint64_t interval);
DESCRIPTION
The clock interrupt subsystem schedules functions for asynchronous execution from the clock interrupt context on a particular CPU.
Clock interrupts are well-suited for timekeeping, scheduling, and statistical profiling. Applications with more relaxed latency requirements should use timeouts to schedule asynchronous execution; see timeout_add(9) for details.
The
clockintr_bind
()
function initializes the clock interrupt object cl.
When cl expires, its callback
function is executed from the IPL_CLOCK
context on
its host cpu without any locks or mutexes. The
callback function must not block. Its parameters are as follows:
- cr
- A private clockrequest object. May be used to
request rescheduling; see
clockrequest_advance
() below. - cf
- The cpu's current machine-dependent clockframe.
- arg
- The arg given to
clockintr_bind
().
The memory pointed to by
cl must be zeroed before it is first bound. It is an
error to use cl as argument to any other function in
the clockintr API before it is bound. It is an error
to rebind cl without first unbinding it; see
clockintr_unbind
()
below.
The
clockintr_schedule
()
function schedules cl to expire at the absolute time
abs on the system uptime clock. The subsystem will
never execute cl's callback function before this
expiration time, though its execution may be delayed by other activity on
the system.
The
clockintr_advance
()
function schedules cl to expire at the next terminus
of the given interval, a non-zero count of
nanoseconds, relative to cl's current expiration time.
Periodic clock interrupts should be scheduled with
clockintr_advance
() to keep the execution period
from drifting.
The
clockintr_cancel
()
function cancels any pending expiration of cl.
The
clockintr_unbind
()
function cancels any pending expiration of cl and
severs the binding between cl and its host
cpu. Upon return, cl may be
rebound with clockintr_bind
(). The call may be
configured with zero or more of the following
flags:
CL_BARRIER
- If cl's callback function is executing, block until it returns. By default, the caller does not block. Useful when arg is a shared reference.
The
clockintr_stagger
()
function resets cl's expiration time to a fraction of
the given interval, a count of nanoseconds.
Specifically, cl's expiration time is reset to
(interval /
denom *
numer). Periodic clock interrupts bound to multiple
CPUs may be staggered to reduce the likelihood that their callback functions
will execute simultaneously and compete for a shared resource. It is an
error if numer is greater than or equal to
denom. It is an error if cl is
already scheduled to expire.
The
clockrequest_advance
()
function is similar to clockintr_advance
(), except
that (a) it may only be called during the execution of a
callback function, (b) it accepts a
clockrequest pointer as argument, and (c) scheduling
requests submitted with the interface are not fulfilled until the callback
function returns. When the callback function returns, scheduling requests
are only committed to the underlying clock interrupt object if that object
was not manipulated during the execution of the callback function.
Otherwise, outstanding requests are discarded.
CONTEXT
The clockintr_bind
() function may only be
called from process context.
The clockintr_advance
(),
clockintr_cancel
(),
clockintr_schedule
(), and
clockintr_stagger
() functions may be called from
process context or from interrupt context.
The clockintr_unbind
() function may
normally be called from process context or from interrupt context. However,
if the CL_BARRIER
flag is set in
flags, the function may only be called from process
context.
The clockrequest_advance
() function may
only be called during execution of a callback
function.
RETURN VALUES
The clockintr_advance
() and
clockrequest_advance
() functions return the number
of intervals that have elapsed since
cl was scheduled to expire, or zero if
cl has not yet expired.
CODE REFERENCES
sys/kern/kern_clockintr.c
SEE ALSO
microtime(9), spl(9), timeout(9)
Richard McDougall and Jim Mauro, Solaris Internals: Solaris 10 and OpenSolaris Kernel Architecture, Prentice Hall, Sun Microsystems Press, pp. 912–925, 2nd Edition, 2007.
HISTORY
The clockintr and clockrequest APIs first appeared in OpenBSD 7.5.