ztime.h is a simple, cross-platform time and clock library for C and C++. It provides high-resolution monotonic clocks for profiling and benchmarking, wall clocks for date/time functionality, and utilities for precise sleep, timeouts, and fixed-timestep loops.
It is part of the Zen Development Kit.
- Monotonic Time: High-resolution nanosecond timers (
ztime_now_ns) guaranteed not to go backwards, ideal for measuring duration. - Wall Time: Epoch and millisecond-precision wall clocks (
ztime_wall_ms) for timestamps. - High-Precision Sleep:
ztime_sleep_usoffers microsecond-level sleep precision (using hybrid spin-waits on Windows where necessary). - Ticker: A robust fixed-timestep loop stabilizer (
zticker_t) for games, simulations, or render loops. - Stopwatch: Simple helpers for starting, stopping, and reading elapsed time.
- Timeouts: Easy "deadline" API to handle blocking operations with timeouts.
- Zero Dependencies: Uses standard OS headers (
<time.h>,<windows.h>,<unistd.h>).
#define ZTIME_IMPLEMENTATION
#include "ztime.h"
#include <stdio.h>
int main(void)
{
uint64_t start = ztime_now_ns();
ztime_sleep_ms(50);
uint64_t elapsed = ztime_diff_ns(start, ztime_now_ns());
printf("Slept for %.2f ms\n", elapsed / 1e6);
zticker_t ticker;
ztime_ticker_init(&ticker, 60);
while (ticker.frame_count < 60)
{
// block until next tick.
double dt = ztime_ticker_tick(&ticker);
printf("Frame %llu: dt=%.4f\n", ticker.frame_count, dt);
}
return 0;
}Core Time
| Function | Description |
|---|---|
ztime_now_ns() |
Returns monotonic time in nanoseconds (for measuring intervals). |
ztime_now_us() |
Returns monotonic time in microseconds. |
ztime_now_ms() |
Returns monotonic time in milliseconds. |
ztime_epoch() |
Returns Unix timestamp (seconds since 1970). |
ztime_wall_ms() |
Returns milliseconds since the Unix epoch (wall clock). |
ztime_diff_ns(start, end) |
Returns end - start, or 0 if start > end (underflow protection). |
Sleep
| Function | Description |
|---|---|
ztime_sleep_ms(ms) |
Standard thread sleep for ms milliseconds. |
ztime_sleep_us(us) |
High-precision sleep. Uses spin-wait on Windows for small intervals. |
Stopwatch
| Function | Description |
|---|---|
ztime_sw_start(sw) |
Starts or restarts the stopwatch. |
ztime_sw_elapsed_ns(sw) |
Returns nanoseconds elapsed since start. |
ztime_sw_elapsed_ms(sw) |
Returns milliseconds (double) elapsed since start. |
Ticker (Loop Stabilizer)
| Function | Description |
|---|---|
ztime_ticker_init(t, hz) |
Initializes ticker for a target frequency (for example, 60 Hz). |
ztime_ticker_tick(t) |
Sleeps until next tick. Returns delta time (seconds) since last frame. |
Timeouts
| Function | Description |
|---|---|
ztime_timeout_start(ms) |
Creates a timeout check set to expire ms milliseconds from now. |
ztime_timeout_expired(t) |
Returns true if the deadline has passed. |
ztime_timeout_rem_ms(t) |
Returns milliseconds remaining (0 if expired). |
Formatting
| Function | Description |
|---|---|
ztime_fmt_log(buf, len, t) |
Formats standard time t as "YYYY-MM-DD HH:MM:SS". |
ztime_fmt_now(buf, len) |
Formats current wall time with ms: "YYYY-MM-DD HH:MM:SS.mmm". |
Define these macros before including ztime.h to modify behavior:
| Macro | Description |
|---|---|
ZTIME_IMPLEMENTATION |
Define in exactly one .c or .cpp file to generate implementation. |