Skip to main content

Module clock

Module clock 

Source
Expand description

The one clock the standard library reads, with an override for nitr test (nitr.test.clock).

Every wall-clock or elapsed-time read whose answer a script can observe goes through here: nitr.time.now/monotonic, session and JWT expiry, the after/before validation rules, cache TTLs, and the rate limiter’s window. A test can then age a session or expire a cache entry by saying so, instead of sleeping.

What deliberately does not read this clock: the runtime’s execution deadline, every tokio::time timeout, and the body-stall timers. They measure real time by design — routed through the override, t.clock.advance(3600) would trip the budget of the very test that called it.

The override is process-global, because several readers (the rate limiter, the cache) have no Lua state to find a per-state value in. That is sound only because nothing sets it but the nitr test runner, which runs files and tests strictly one after another and resets the override after every test and every file. A production process never calls set or advance, and then every read costs one relaxed atomic load on top of the real clock. The standard library’s own unit tests exercise a private Clock instance, never the global one.

Functions§

advance
Moves wall and monotonic time forward together by secs — what a TTL or a rate-limit window needs to see. For nitr test only.
now_instant
The monotonic clock, moved forward by advance.
now_system
The wall clock.
now_unix
The wall clock as whole unix seconds (0 before the epoch).
now_unix_f64
The wall clock as fractional unix seconds (0.0 before the epoch).
reset
Removes any override: every reader sees the real clock again.
set
Freezes the wall clock at ts unix seconds. Monotonic time keeps flowing: an Instant cannot be moved backwards. For nitr test only.
take_touched
Whether the clock was set or advanced since the last call — even if it has been reset since. Anything that stored an instant meanwhile (a cache entry’s expiry) carries the overridden time: the runner clears such state when this says so.