v1.0.0 — Stable API

[jamesgober]

v1.0.0 — Stable API

clock-lib reaches 1.0. The public surface, the performance, the documentation, and the supply-chain story are all settled. From this release forward, every change against this major version is non-breaking.

What clock-lib Is

A thin, well-inlined layer over std::time that gives you the two kinds of time every program needs — monotonic for measuring elapsed time, wall-clock for timestamps — as distinct types the compiler refuses to mix. A Clock trait makes time-driven code testable without thread::sleep. Zero runtime dependencies, no unsafe, no_std-compatible.

use clock_lib as clock;

// Measure how long something takes (never goes backwards).
let start = clock::now();
// ... do work ...
let took = clock::elapsed(start);

// Stamp an event (calendar time).
let secs = clock::unix();

[dependencies]
clock-lib = "1.0"

The Stable Surface

Everything below is committed for the 1.x line and will not change without a major version bump.

Tier-1 free functions

now, elapsed, wall, unix, unix_ms, unix_ns — one-line entry points for the common case.

Types

• Monotonic — now, elapsed, duration_since, checked_duration_since, saturating_duration_since.
• Wall — now, unix_seconds, unix_millis, unix_nanos. Pre-epoch system clocks saturate to 0; no panics, no silent wrapping.

Trait + implementations

• Clock — Send + Sync trait with now and wall methods. Blanket impls for Arc<C> and &C.
• SystemClock — zero-sized, Copy, const-constructible production clock.
• ManualClock — lock-free, atomic-offset test clock. new, advance, offset.

Constants

• VERSION — the only item exposed without the std feature.

Performance, Verified

The performance document records the recorded median for every public reading alongside the raw std::time call it forwards to. The wrappers sit on top of the bare std functions inside criterion's noise band on Windows 11 / Rust 1.85.

Wrapper	Δ vs raw std::time
clock_lib::now	−0.2%
Monotonic::now	−0.7%
SystemClock::now	−0.9%
clock_lib::wall	−0.7%
Wall::now	−0.6%
clock_lib::elapsed	−0.2%

ManualClock::now runs in 752 ps; ManualClock::advance(1ns) in 3.75 ns. A test that calls advance + now a million times spends about 4 ms on the clock.

Engineering Posture

• #![forbid(unsafe_code)] at the crate root.
• REPS-complete lint stack — #![deny(warnings)], clippy::unwrap_used, expect_used, todo, unimplemented, dbg_macro, print_*, unreachable, plus #![warn(clippy::pedantic)].
• Reproducible builds — rust-toolchain.toml pins 1.85.0; Cargo.lock is committed.
• Supply chain — cargo audit (RustSec) and cargo deny (license + yanked + wildcard policy) run on every push.
• Cross-platform CI — Linux, macOS, and Windows on stable and MSRV; bare-metal no_std build on thumbv7em-none-eabihf.

Compatibility

• MSRV: Rust 1.85
• Edition: 2024
• Platforms: Linux, macOS, Windows; no_std targets via default-features = false.
• Public API: unchanged from 0.5.0. Code written against any 0.x version since 0.3 compiles unchanged against 1.0.

Upgrading From 0.x

Bump the version. There is no code migration.

[dependencies]
clock-lib = "1.0"

Out of Scope

clock-lib is deliberately small. It does not handle:

• Calendar math, date formatting, or timezones — use chrono or time.
• Timers, sleeping, or scheduling — that's a separate concern that should depend on clock-lib, not be part of it.
• Async — the readings are synchronous; async code calls them like any other function.

Stability Promise

Anything documented in docs/API.md is part of the 1.x contract. Behavioral changes that would break correct downstream code will only ship with a major version bump. The crate is feature-complete for its scope; future work is bug fixes, performance refinement, and platform support, not new APIs.

Full Changelog: v0.5.0...v1.0.0

---

This discussion was created from the release v1.0.0 — Stable API.