clock-lib 1.0.0

Features

Two Kinds of Time, Clearly Separated

• Monotonic readings — for measuring elapsed time; never goes backwards
• Wall-clock readings — for timestamps and calendar time
• Type-level separation — the API makes it impossible to subtract a wall-clock time from a monotonic one

Mockable Clock (the killer feature)

• SystemClock — reads the OS in production
• ManualClock — advance time instantly in tests, fully deterministic
• Clock trait — inject time into any system for testability

Simple Tier-1 API

• now() — monotonic reading
• elapsed(earlier) — duration since a monotonic reading
• wall() — wall-clock reading
• unix() / unix_ms() / unix_ns() — unix time conveniences

Lean & Correct

• Zero runtime dependencies — wraps std::time
• #![forbid(unsafe_code)] — enforced by the compiler
• no_std-compatible — the crate builds against bare-metal targets with default-features = false
• Cross-platform — Linux, macOS, Windows

This crate deliberately does not do calendar math, date formatting, or timezones. For that, use chrono or time. clock-lib is the lean primitive layer beneath them.

Installation

[dependencies]
clock-lib = "1.0"

For no_std builds, opt out of the default std feature:

[dependencies]
clock-lib = { version = "1.0", default-features = false }

In no_std mode, only the VERSION constant is exposed — the reading APIs all require an OS clock and are gated behind the std feature. This is the honest cost of a portable clock library: the readings themselves are platform-specific.

Quick Start

use clock_lib as clock;

// Measure elapsed time (monotonic — safe)
let start = clock::now();
// ... do work ...
let took = clock::elapsed(start);

// Get a timestamp (wall-clock)
let unix_seconds = clock::unix();

Reach for the typed surface when you need it — Monotonic for elapsed-time math, Wall for timestamps. The compiler refuses to mix the two, so you cannot accidentally measure an interval with a clock that can step backwards.

Deterministic Time in Tests

use clock_lib::{Clock, ManualClock, Monotonic};
use std::time::Duration;

fn expired<C: Clock>(clock: &C, stamp: Monotonic, ttl: Duration) -> bool {
    clock.now().duration_since(stamp) >= ttl
}

let clock = ManualClock::new();
let stamp = clock.now();
assert!(!expired(&clock, stamp, Duration::from_secs(60)));

clock.advance(Duration::from_secs(60));   // instant, no sleep
assert!(expired(&clock, stamp, Duration::from_secs(60)));

Inject Clock into anything time-driven (rate limiters, TTL caches, timeouts) and your test suite drops every thread::sleep it had.

Documentation

• API reference — every public type, trait, and function with examples.
• Performance — benchmark methodology and the zero-overhead claim, verified.
• Developer guidelines — the engineering bar this project is built to.
• Release notes — what shipped, when, and why.

Contributing

Contributions are welcome under the project's dual license. Before opening a pull request, please make sure:

1. cargo fmt --all -- --check passes.
2. cargo clippy --all-targets --all-features -- -D warnings is clean.
3. cargo test --all-features passes.
4. New public items include documentation and at least one example.
5. The API reference and CHANGELOG are updated alongside code changes.