ztime.h

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.

Features

• 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_us offers 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>).

Usage

#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;
}

API Reference

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".

Configuration

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.