Module cached_clock 

Process-global cached wall clock.

A single background thread refreshes a cached microsecond timestamp every REFRESH_INTERVAL. Readers load one relaxed atomic (~1 ns) instead of calling clock_gettime (~20 ns), trading at most REFRESH_INTERVAL of staleness for the cheaper read.

This suits primitives whose physical-clock component tolerates coarse resolution because a logical counter orders sub-interval events - e.g. a same-host Hybrid Logical Clock, where every process reads the same hardware clock (zero inter-process skew) and the only thing the cache changes is the granularity at which the physical timestamp advances.

Compared with CLOCK_REALTIME_COARSE (~1 ms granularity, ~5 ns read) this is both finer (250 us) and faster (a plain atomic load); the cost is one background thread per process, spawned lazily on first use.

Functions

now_us

Cached wall-clock microseconds - one relaxed atomic load. Callers must have invoked start (e.g. at handle create) so the updater is running; before the first refresh this returns the seed taken in start. Monotonic to the precision of the underlying clock; a brief backward NTP step is absorbed by HLC-style max(prev, now) callers.

start

Start the background updater thread (once per process). Idempotent; call from a consumer’s create / open. The cache is seeded synchronously here so the very first now_us is valid even before the thread’s first refresh.