clocks-and-time
Installation
SKILL.md
Clocks and time
Rule 1: never measure duration with the wall clock
Two different clocks exist, and mixing them is the most common time bug.
| Clock | Property | Use for |
|---|---|---|
Wall clock (time(), Date.now(), System.currentTimeMillis) |
Can jump forward or backward: NTP correction, DST, manual set, VM migration | Timestamps meant for humans or storage |
Monotonic (time.monotonic(), performance.now(), System.nanoTime, CLOCK_MONOTONIC) |
Never goes backward. Meaningless as an absolute value. Usually excludes suspend time | Durations, timeouts, rate limits, retries, benchmarks |
start = time.monotonic()
do_work()
elapsed = time.monotonic() - start # correct
start = time.time() # WRONG: an NTP step makes elapsed negative