clock-lib 0.4.0

Monotonic and wall-clock time readings for Rust, with a mockable clock for deterministic testing. Simple Tier-1 API, zero dependencies, no unsafe.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

# v0.4.0 — Performance, Verified

The "zero-overhead" claim that has been quietly sitting in the README since day one now ships with the numbers to back it up. `clock-lib` 0.4.0 adds a real benchmark suite and a [`docs/PERFORMANCE.md`](../PERFORMANCE.md) report that proves the wrapper costs the same as `std::time` — not "approximately the same", measurably the same.

## Highlights

- **Real benchmark suite.** Seven [`criterion`](https://crates.io/crates/criterion) groups in [`benches/clock_bench.rs`](../../benches/clock_bench.rs) covering monotonic readings, wall readings, unix conversions, the unix helpers end-to-end, elapsed-time measurement, every `ManualClock` operation, and trait-object dispatch through `&dyn Clock`.
- **Zero overhead, verified.** [`docs/PERFORMANCE.md`](../PERFORMANCE.md) records the recorded median for every bench alongside the raw `std::time` call it forwards to. The wrapper functions sit on top of the bare std functions inside criterion's noise band.
- **Committed baseline.** Run `cargo bench --bench clock_bench -- --save-baseline 0.4.0` to pin the current numbers, then `cargo bench --bench clock_bench -- --baseline 0.4.0` after any change to detect regressions.
- **Hot-path methodology written down.** What was measured, how, on what hardware, and how to reproduce it locally — all in the [performance doc](../PERFORMANCE.md).

## What's New

### Added

- `benches/clock_bench.rs` — real benchmarks across seven groups:
  - `monotonic_now` — `Instant::now` vs `clock_lib::now`, `Monotonic::now`, `SystemClock::now`.
  - `wall_now` — `SystemTime::now` vs `clock_lib::wall`, `Wall::now`.
  - `unix_conversions` — cost of `Wall::unix_seconds` / `unix_millis` / `unix_nanos` on a pre-captured reading.
  - `unix_helpers` — end-to-end cost of `clock_lib::unix` / `unix_ms` / `unix_ns`.
  - `elapsed` — `Instant::elapsed` vs `Monotonic::elapsed` vs `clock_lib::elapsed`.
  - `manual_clock` — `now`, `wall`, `offset`, `advance(1ns)`.
  - `dyn_dispatch` — concrete `SystemClock` vs `&dyn Clock`.
- `docs/PERFORMANCE.md` — methodology, recorded numbers, the zero-overhead claim, and how to compare against the baseline.
- README link to the performance document.

### Changed

- Replaced the placeholder bench function with the real suite.

## Compatibility

- **MSRV:** Rust 1.85 (unchanged)
- **Edition:** 2024 (unchanged)
- **Public API:** unchanged — no migration required from 0.3.x.

## Upgrading From 0.3.x

```toml
[dependencies]
clock-lib = "0.4"
```

No code changes required.

## What's Next

- **0.5.0 — `no_std` hardening and the 1.0 release candidate.**
- **1.0.0 — stable.**