universal-time

Cross-platform time primitives with compile-time guarantees — no runtime panics!

This library provides Instant (monotonic time) and SystemTime (wall-clock time) that work consistently across all platforms with zero runtime overhead.

Why?

This library fails at link time if you try to build without a time provider on platforms that need one. This means:

✅ Zero runtime panics from missing time sources
✅ Compile-time verification that time is available
✅ Single consistent API across all platforms
✅ No overhead – compiles away to platform calls

Quick Start

With `std`

Works automatically with std::time:

use universal_time::{Instant, SystemTime, UNIX_EPOCH};

fn main() {
    let start = Instant::now();
    let elapsed = start.elapsed();

    let now = SystemTime::now();
    let since_epoch = now.duration_since(UNIX_EPOCH).unwrap();

    println!("Elapsed: {:?}", elapsed);
    println!("Since Unix epoch: {:?}", since_epoch);
}

Without `std` (embedded, WASM unknown)

Define a custom time provider using the define_time_provider! macro:

use core::time::Duration;

use universal_time::{define_time_provider, Instant, SystemTime, WallClock, MonotonicClock, UNIX_EPOCH};

struct MyTimeProvider;

impl WallClock for MyTimeProvider {
    fn system_time(&self) -> SystemTime {
        // Your platform-specific implementation
        SystemTime::from_unix_duration(Duration::from_secs(0))
    }
}

impl MonotonicClock for MyTimeProvider {
    fn instant(&self) -> Instant {
        // Your platform-specific implementation
        Instant::from_ticks(Duration::from_secs(0))
    }
}

define_time_provider!(MyTimeProvider);

fn main() {
    let start = Instant::now();
    let elapsed = start.elapsed();

    let now = SystemTime::now();
    let since_epoch = now.duration_since(UNIX_EPOCH).unwrap();

    println!("Elapsed: {:?}", elapsed);
    println!("Since Unix epoch: {:?}", since_epoch);
}

How It Works

The library uses extern symbols to enforce time provider availability at link time:

Platform	Behavior
Linux/macOS/Windows with `std`	Uses `std::time` automatically
`no_std` and `wasm*-unknown-unknown`	Requires `define_time_provider!` macro
Other WASM targets with `std`	Uses `std::time` automatically

Without a provider, you get a clear link error.

Duplicate provider? Link error: "duplicate symbol" – catches configuration mistakes at compile time!

Features

std (enabled by default) - Uses std::time on supported platforms

Changelog

All notable changes to this library are documented in the CHANGELOG.md.

License

This project is distributed under the MIT software license – see the LICENSE file for details

universal-time 0.3.0