Struct ClockController 

pub struct ClockController { /* private fields */ }

Controller for artificial time operations.

This is only available for artificial clocks and provides methods to advance time, set time, and inspect pending wake events.

Created alongside a ClockHandle via ClockHandle::artificial().

Implementations

impl ClockController

pub async fn advance(&self, duration: Duration) -> usize

Advance artificial time by the given duration.

Wake events are processed in chronological order. If you advance by 1 day and there are sleeps scheduled at 1 hour and 2 hours, they will wake at their scheduled times (seeing the correct now() value), not at +1 day.

Returns the number of wake events that were processed.

Example

use es_entity::clock::{ClockHandle, ArtificialClockConfig};
use std::time::Duration;

let (clock, ctrl) = ClockHandle::artificial(ArtificialClockConfig::manual());
let t0 = clock.now();

let clock2 = clock.clone();
let handle = tokio::spawn(async move {
    clock2.sleep(Duration::from_secs(3600)).await;
    clock2.now() // Will be t0 + 1 hour
});

tokio::task::yield_now().await; // Let task register its sleep

// Advance 1 day - task wakes at exactly +1 hour
ctrl.advance(Duration::from_secs(86400)).await;

let wake_time = handle.await.unwrap();
assert_eq!(wake_time, t0 + chrono::Duration::hours(1));

pub async fn advance_to_next_wake(&self) -> Option<DateTime<Utc>>

Advance to the next pending wake event.

Returns the time that was advanced to, or None if there are no pending wake events.

This is useful for step-by-step testing where you want to process events one at a time.

Example

use es_entity::clock::{ClockHandle, ArtificialClockConfig};
use std::time::Duration;

let (clock, ctrl) = ClockHandle::artificial(ArtificialClockConfig::manual());
let t0 = clock.now();

// Spawn tasks with different sleep durations
let c = clock.clone();
tokio::spawn(async move { c.sleep(Duration::from_secs(60)).await; });
let c = clock.clone();
tokio::spawn(async move { c.sleep(Duration::from_secs(120)).await; });

tokio::task::yield_now().await;

// Step through one wake at a time
let t1 = ctrl.advance_to_next_wake().await;
assert_eq!(t1, Some(t0 + chrono::Duration::seconds(60)));

let t2 = ctrl.advance_to_next_wake().await;
assert_eq!(t2, Some(t0 + chrono::Duration::seconds(120)));

let t3 = ctrl.advance_to_next_wake().await;
assert_eq!(t3, None); // No more pending wakes

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

Set the artificial time to a specific value.

Warning: Unlike advance(), this does NOT process wake events in order. All tasks whose wake time has passed will see the new time when they wake. Use this for “jump ahead, don’t care about intermediate events” scenarios.

For deterministic testing, prefer advance() or advance_to_next_wake().

pub fn pending_wake_count(&self) -> usize

Get the number of pending wake events.

This is useful for testing to verify that tasks have registered their sleeps before advancing time.

pub fn now(&self) -> DateTime<Utc>

Get the current artificial time.

This is equivalent to calling now() on the associated ClockHandle.

pub fn transition_to_realtime(&self)

Transition to realtime mode.

After this call:

• now() returns Utc::now()
• sleep() uses real tokio timers
• advance() becomes a no-op

Pending sleeps are woken immediately and will re-register using real timers for their remaining duration (based on the original wake time).

pub fn is_realtime(&self) -> bool

Check if clock has transitioned to realtime.

pub fn clear_pending_wakes(&self)

Clear all pending wake events.

pub fn reset_to(&self, time: DateTime<Utc>)

Reset clock to a specific time and clear all pending wakes.

Useful for test isolation between test cases.

Trait Implementations

impl Clone for ClockController

fn clone(&self) -> ClockController

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ClockController

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

Formats the value using the given formatter.