Crate qubit_clock 

Thread-safe clock abstractions for Rust.

This crate provides a flexible and type-safe clock abstraction system with support for:

• Basic time access: Get current UTC time
• High precision: Nanosecond-level time measurements
• Timezone support: Convert to local time in any timezone
• Monotonic time: Time that never goes backwards
• Testing support: Controllable mock clocks for tests
• Mockable sleeps: Relative sleep abstractions with real and mock implementations

Architecture

The crate is built around several orthogonal traits:

• Clock: Base trait providing UTC time
• NanoClock: Extension for nanosecond precision
• ZonedClock: Extension for timezone support
• ControllableClock: Extension for time control (testing)
• sleep::Sleeper: Relative blocking sleep abstraction
• sleep::AsyncSleeper: Tokio async relative sleep abstraction enabled by the tokio feature

Implementations

Several clock implementations are provided:

• SystemClock: Uses system wall clock time
• MonotonicClock: Monotonic time (unaffected by system time changes)
• NanoMonotonicClock: Monotonic time with nanosecond precision
• MockClock: Controllable clock for testing
• MockNanoClock: Nanosecond-precision controllable clock for testing
• MockClockProgression: Frozen or monotonic mock-clock progression mode
• Zoned<C>: Wrapper that adds timezone support to any clock
• sleep::SystemSleeper: Real relative sleeper, with async support when the tokio feature is enabled
• sleep::MockSleeper: Manually controlled relative sleeper for tests, with async support when the tokio feature is enabled

Examples

Basic Usage

use qubit_clock::{Clock, SystemClock};

let clock = SystemClock::new();
let timestamp = clock.millis();
let time = clock.time();
println!("Current time: {}", time);

With Timezone

use qubit_clock::{Clock, ZonedClock, SystemClock, Zoned};
use chrono_tz::Asia::Shanghai;

let clock = Zoned::new(SystemClock::new(), Shanghai);
let local = clock.local_time();
println!("Local time in Shanghai: {}", local);

Monotonic Time for Performance Measurement

use qubit_clock::{Clock, MonotonicClock};
use std::thread;
use std::time::Duration;

let clock = MonotonicClock::new();
let start = clock.millis();

thread::sleep(Duration::from_millis(100));

let elapsed = clock.millis() - start;
println!("Elapsed: {} ms", elapsed);

Testing with MockClock

use qubit_clock::{Clock, ControllableClock, MockClock};
use chrono::{DateTime, Duration, Utc};

let clock = MockClock::new();

// Set to a specific time
let fixed_time = DateTime::parse_from_rfc3339(
    "2024-01-01T00:00:00Z"
).unwrap().with_timezone(&Utc);
clock.set_time(fixed_time);

assert_eq!(clock.time(), fixed_time);

// Advance time
clock.add_duration(Duration::hours(1));
assert_eq!(clock.time(), fixed_time + Duration::hours(1));

High-Precision Measurements

use qubit_clock::{NanoClock, NanoMonotonicClock};

let clock = NanoMonotonicClock::new();
let start = clock.nanos();

// Perform some operation
for _ in 0..1000 {
    // Some work
}

let elapsed = clock.nanos() - start;
println!("Elapsed: {} ns", elapsed);

Time Meters for Elapsed Time Measurement

use qubit_clock::meter::TimeMeter;
use std::thread;
use std::time::Duration;

let mut meter = TimeMeter::new();
meter.start();
thread::sleep(Duration::from_millis(100));
meter.stop();
println!("Elapsed: {}", meter.readable_duration());

Design Principles

• Interface Segregation: Don’t force implementations to provide features they don’t need
• Single Responsibility: Each trait and type has one clear purpose
• Composition over Inheritance: Extend functionality through wrappers
• Zero-Cost Abstractions: Pay only for what you use

Re-exports

pub use clock::Clock;

pub use clock::ControllableClock;

pub use clock::MockClock;

pub use clock::MockClockProgression;

pub use clock::MockNanoClock;

pub use clock::MonotonicClock;

pub use clock::NanoClock;

pub use clock::NanoMonotonicClock;

pub use clock::SystemClock;

pub use clock::Zoned;

pub use clock::ZonedClock;

Modules

clock

Clock traits and implementations.

meter

Time measurement utilities.

sleep

Thread-blocking and asynchronous sleep abstractions.

Structs

DateTime

ISO 8601 combined date and time with time zone.

Utc

The UTC time zone. This is the most efficient time zone when you don’t need the local time. It is also used as an offset (which is also a dummy type).

Enums

Tz

TimeZones built at compile time from the tz database

Type Aliases

Duration

Alias of TimeDelta.