Struct MockClock 

pub struct MockClock { /* private fields */ }

A controllable clock implementation for testing.

MockClock allows you to adjust logical time, making it useful for testing time-dependent code. Readings are frozen after construction by default. set_time() reanchors the logical time without changing the current progression mode or auto-advance settings. Use this type when the code under test reads the current time through Clock. Use MockNanoClock for code that needs NanoClock. For code that actually sleeps or waits for retry/backoff intervals, inject crate::sleep::MockSleeper separately; advancing a MockClock does not complete mock sleeps.

Features

• Align the logical current time to a specific time
• Advance the clock by a duration
• Automatically advance time on each call
• Switch between frozen and monotonic progression
• Reset to the initial creation state

Testing guidance

MockClock controls what “now” means to the code under test. It does not model blocking or asynchronous sleeping. If a component needs both a clock and a sleeper, tests should inject both MockClock and crate::sleep::MockSleeper and advance them independently.

Thread Safety

This type is thread-safe, using Arc<Mutex<>> internally to protect its mutable state.

Examples

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 by 1 hour
clock.add_duration(Duration::hours(1));
assert_eq!(clock.time(), fixed_time + Duration::hours(1));

// Reset to initial state
clock.reset();

Implementations

impl MockClock

pub fn new() -> Self

Creates a new MockClock.

The clock is initialized with the current system time and remains frozen at that instant until adjusted by the control methods or switched to monotonic progression.

Returns

A new MockClock instance.

Examples

use qubit_clock::MockClock;

let clock = MockClock::new();

pub fn with_progression(progression: MockClockProgression) -> Self

Creates a new MockClock with the specified progression mode.

The clock starts at the current system time. In Frozen mode, readings stay fixed until explicitly advanced. In Monotonic mode, readings progress naturally from the initial system time.

Arguments

• progression - The initial progression mode.

Examples

use qubit_clock::{MockClock, MockClockProgression};

let clock = MockClock::with_progression(MockClockProgression::Monotonic);
assert_eq!(clock.progression(), MockClockProgression::Monotonic);

pub fn progression(&self) -> MockClockProgression

Returns the current progression mode.

Examples

use qubit_clock::{MockClock, MockClockProgression};

let clock = MockClock::new();
assert_eq!(clock.progression(), MockClockProgression::Frozen);

pub fn set_progression(&self, progression: MockClockProgression)

Switches the clock progression mode without changing the current reading.

The current logical reading is first folded into the clock’s base state, so changing between frozen and monotonic modes does not cause an immediate time jump.

Arguments

• progression - The new progression mode.

Examples

use qubit_clock::{MockClock, MockClockProgression};

let clock = MockClock::new();
clock.set_progression(MockClockProgression::Monotonic);
assert_eq!(clock.progression(), MockClockProgression::Monotonic);

pub fn monotonic_progression_enabled(&self) -> bool

Returns whether monotonic progression is enabled.

Examples

use qubit_clock::MockClock;

let clock = MockClock::new();
assert!(!clock.monotonic_progression_enabled());

pub fn set_monotonic_progression_enabled(&self, enabled: bool)

Enables or disables monotonic progression.

This is a boolean convenience wrapper around set_progression().

Arguments

• enabled - true to use monotonic progression, false to freeze.

Examples

use qubit_clock::MockClock;

let clock = MockClock::new();
clock.set_monotonic_progression_enabled(true);
assert!(clock.monotonic_progression_enabled());

pub fn add_millis(&self, millis: i64, add_every_time: bool)

Adds a fixed amount of milliseconds to the clock.

Arguments

• millis - The number of milliseconds to add.
• add_every_time - If true, the specified milliseconds will be added on every call to millis(). If false, the milliseconds are added only once.

Examples

use qubit_clock::{Clock, MockClock};

let clock = MockClock::new();
let before = clock.millis();

// Add 1000ms once
clock.add_millis(1000, false);
assert_eq!(clock.millis(), before + 1000);

// Add 100ms on every call
clock.add_millis(100, true);
let t1 = clock.millis();
let t2 = clock.millis();
assert_eq!(t2 - t1, 100);

pub fn advance_millis(&self, millis: i64)

Advances the clock by a fixed amount once.

This method updates the offset used by millis() and time() without enabling auto-advance. If the accumulated offset exceeds the i64 range, it saturates at the nearest boundary.

Arguments

• millis - The milliseconds to add once.

Examples

use qubit_clock::{Clock, MockClock};

let clock = MockClock::new();
let before = clock.millis();
clock.advance_millis(1000);
assert_eq!(clock.millis(), before + 1000);

pub fn set_auto_advance_millis(&self, millis: i64)

Enables auto-advance on each read operation.

After calling this method, each call to millis() or time() returns the current logical time and advances the next read by millis.

Arguments

• millis - The milliseconds to advance on each read.

Examples

use qubit_clock::{Clock, MockClock};

let clock = MockClock::new();
clock.set_auto_advance_millis(100);
let t1 = clock.millis();
let t2 = clock.millis();
assert_eq!(t2 - t1, 100);

pub fn clear_auto_advance(&self)

Disables auto-advance behavior.

This method clears the per-read advance setting. Subsequent read operations will no longer mutate the clock state.

Examples

use qubit_clock::{Clock, MockClock};

let clock = MockClock::new();
clock.set_auto_advance_millis(100);
let _ = clock.millis();
clock.clear_auto_advance();
let t1 = clock.millis();
let t2 = clock.millis();
assert_eq!(t2, t1);

Trait Implementations

impl Clock for MockClock

fn millis(&self) -> i64

Returns the current time as a Unix timestamp in milliseconds (UTC).

fn time(&self) -> DateTime<Utc>

Returns the current time as a DateTime<Utc>.

impl Clone for MockClock

fn clone(&self) -> MockClock

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl ControllableClock for MockClock

fn set_time(&self, instant: DateTime<Utc>)

Sets or aligns the clock to a specific time.

fn add_duration(&self, duration: Duration)

Advances the clock by the specified duration.

fn reset(&self)

Resets the clock to its initial state.

impl Debug for MockClock

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for MockClock

fn default() -> Self

Returns the “default value” for a type.