CLOCKINTR_BIND(9) | Kernel Developer's Manual | CLOCKINTR_BIND(9)

# 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.

February 24, 2024 | Debian