Struct MockNanoClock 

pub struct MockNanoClock { /* private fields */ }

A nanosecond-precision controllable clock implementation for testing.

MockNanoClock is the high-precision counterpart of MockClock. It implements Clock, NanoClock, and ControllableClock. Readings are frozen after construction by default. set_time() reanchors the logical time without changing the current progression mode or auto-advance settings.

Features

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

Thread Safety

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

Examples

use chrono::{DateTime, Duration, Utc};
use qubit_clock::{ControllableClock, MockNanoClock, NanoClock};

let clock = MockNanoClock::new();
let fixed_time = DateTime::parse_from_rfc3339(
    "2024-01-01T00:00:00.000000123Z"
).unwrap().with_timezone(&Utc);

clock.set_time(fixed_time);
assert_eq!(clock.time_precise(), fixed_time);

clock.advance_nanos(1);
assert_eq!(
    clock.time_precise(),
    fixed_time + Duration::nanoseconds(1)
);

Implementations

impl MockNanoClock

pub fn new() -> Self

Creates a new MockNanoClock.

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

Returns

A new MockNanoClock instance.

Examples

use qubit_clock::MockNanoClock;

let clock = MockNanoClock::new();

pub fn with_progression(progression: MockClockProgression) -> Self

Creates a new MockNanoClock 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::{MockClockProgression, MockNanoClock};

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

pub fn progression(&self) -> MockClockProgression

Returns the current progression mode.

Examples

use qubit_clock::{MockClockProgression, MockNanoClock};

let clock = MockNanoClock::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::{MockClockProgression, MockNanoClock};

let clock = MockNanoClock::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::MockNanoClock;

let clock = MockNanoClock::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::MockNanoClock;

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

pub fn add_nanos(&self, nanos: i128, add_every_time: bool)

Adds a fixed amount of nanoseconds to the clock.

Arguments

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

Examples

use qubit_clock::{MockNanoClock, NanoClock};

let clock = MockNanoClock::new();
let before = clock.nanos();

clock.add_nanos(1_000, false);
assert_eq!(clock.nanos(), before + 1_000);

clock.add_nanos(100, true);
let t1 = clock.nanos();
let t2 = clock.nanos();
assert_eq!(t2 - t1, 100);

pub fn advance_nanos(&self, nanos: i128)

Advances the clock by a fixed nanosecond amount once.

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

Arguments

• nanos - The nanoseconds to add once.

Examples

use qubit_clock::{MockNanoClock, NanoClock};

let clock = MockNanoClock::new();
let before = clock.nanos();
clock.advance_nanos(1_000);
assert_eq!(clock.nanos(), before + 1_000);

pub fn set_auto_advance_nanos(&self, nanos: i128)

Enables auto-advance after each read operation.

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

Arguments

• nanos - The nanoseconds to advance on each read.

Examples

use qubit_clock::{MockNanoClock, NanoClock};

let clock = MockNanoClock::new();
clock.set_auto_advance_nanos(100);
let t1 = clock.nanos();
let t2 = clock.nanos();
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::{MockNanoClock, NanoClock};

let clock = MockNanoClock::new();
clock.set_auto_advance_nanos(100);
let _ = clock.nanos();
clock.clear_auto_advance();
let t1 = clock.nanos();
let t2 = clock.nanos();
assert_eq!(t2, t1);

Trait Implementations

impl Clock for MockNanoClock

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 MockNanoClock

fn clone(&self) -> MockNanoClock

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl ControllableClock for MockNanoClock

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 MockNanoClock

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

Formats the value using the given formatter.

impl Default for MockNanoClock

fn default() -> Self

Returns the “default value” for a type.

impl NanoClock for MockNanoClock

fn nanos(&self) -> i128

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

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

Returns the current time as a DateTime<Utc> with nanosecond precision.