time.h File Reference

Absolute monotonic microsecond deadlines and wrap extension. More...

#include "nexus/core/status.h"

Go to the source code of this file.

Data Structures
struct	nx_clock_t
	An explicitly injected clock; its context outlives all borrowers. More...
struct	nx_clock32_t
	State for extending one 32-bit free-running hardware counter. More...

Macros
#define	NX_DEADLINE_NEVER   UINT64_MAX

Typedefs
typedef uint64_t	nx_time_us_t
	Microseconds in one boot/clock domain; no wall-clock semantics.

Functions
nx_time_us_t	nx_time_now_us (void)
	Read the selected provider's monotonic clock.
bool	nx_deadline_expired (nx_time_us_t deadline, nx_time_us_t now)
	Test an absolute deadline against a clock snapshot.
nx_time_us_t	nx_deadline_after (nx_time_us_t now, uint64_t duration_us)
	Add a duration without wrapping the monotonic domain.
nx_result_t	nx_clock32_initialize (nx_clock32_t *clock, uint32_t counter, uint32_t frequency_hz)
	Initialize counter extension and its clock domain.
nx_result_t	nx_clock32_observe (nx_clock32_t *clock, uint32_t counter, nx_time_us_t *time_us)
	Extend a wrapping counter and convert to microseconds.

Detailed Description

Absolute monotonic microsecond deadlines and wrap extension.

Author

Nexus Team

Definition in file time.h.

Macro Definition Documentation

NX_DEADLINE_NEVER

#define NX_DEADLINE_NEVER   UINT64_MAX

Definition at line 21 of file time.h.

Typedef Documentation

nx_time_us_t

typedef uint64_t nx_time_us_t

Microseconds in one boot/clock domain; no wall-clock semantics.

Definition at line 20 of file time.h.

Function Documentation

nx_clock32_initialize()

nx_result_t nx_clock32_initialize	(	nx_clock32_t *	clock,
		uint32_t	counter,
		uint32_t	frequency_hz )

Initialize counter extension and its clock domain.

Parameters

[out]	clock	Caller-owned extension state.
[in]	counter	First hardware snapshot.
[in]	frequency_hz	Nonzero stable counter frequency.

Returns

NX_SUCCESS, or NX_ERROR_INVALID for invalid arguments.

Note

Single execution owner. Reset creates a new clock domain; do not reuse outstanding deadlines after reset/clock change.

nx_clock32_observe()

nx_result_t nx_clock32_observe	(	nx_clock32_t *	clock,
		uint32_t	counter,
		nx_time_us_t *	time_us )

Extend a wrapping counter and convert to microseconds.

Parameters

[in,out]	clock	Initialized, single-owner extension state.
[in]	counter	Current counter snapshot.
[out]	time_us	Extended elapsed microseconds.

Returns

NX_SUCCESS, NX_ERROR_STATE or NX_ERROR_EXHAUSTED.

Note

Observe at least once per 2^32 ticks, even when idle. Multiple missed wraps cannot be detected from two snapshots. Counter must continue through waits; frequency cannot change.

nx_deadline_after()

nx_time_us_t nx_deadline_after	(	nx_time_us_t	now,
		uint64_t	duration_us )

Add a duration without wrapping the monotonic domain.

Parameters

[in]	now	Current finite time.
[in]	duration_us	Relative duration in microseconds.

Returns

Absolute deadline, saturating at NX_DEADLINE_NEVER.

nx_deadline_expired()

bool nx_deadline_expired	(	nx_time_us_t	deadline,
		nx_time_us_t	now )

Test an absolute deadline against a clock snapshot.

Parameters

[in]	deadline	Absolute time or NX_DEADLINE_NEVER.
[in]	now	Snapshot in the same clock domain.

Returns

True when a finite deadline has expired, including equality.

nx_time_now_us()

nx_time_us_t nx_time_now_us

(

void

)

Read the selected provider's monotonic clock.

Returns

Microseconds since domain initialization.

Note

Physical providers require successful platform startup and a privileged task/configurable IRQ; NMI/HardFault callers are unsupported. No OS, allocation or wait. Physical clocks return zero outside a successfully started live epoch; zero alone cannot prove readiness. Startup status is authoritative. All consumers join before clock withdrawal. Stop/restart or a clock change invalidates every old deadline, even if a new epoch has the same numerical value. UINT64_MAX is reserved; clock exhaustion requires controlled restart. An observed hardware overflow acknowledgement failure ends the live epoch and is terminal, even when finite source isolation succeeds. The provider retains ownership, masks interrupts, calls nx_fault_observe and parks if the observer returns. It never resumes deadline consumers with invalid zero time. Observation neither releases loans nor proves safe outputs; products own separately reviewed non-returning recovery. Ordinary shutdown still requires every consumer and optional low-power owner joined first.