Struct ClockHandle 

pub struct ClockHandle { /* private fields */ }

A handle to a clock for getting time and performing time-based operations.

This is the main interface for time operations. It’s cheap to clone and can be shared across tasks and threads. All clones share the same underlying clock, so they see consistent time.

Creating a Clock

use es_entity::clock::{ClockHandle, ArtificialClockConfig};

// Real-time clock for production
let clock = ClockHandle::realtime();

// Artificial clock for testing - returns (handle, controller)
let (clock, ctrl) = ClockHandle::artificial(ArtificialClockConfig::manual());

Basic Operations

use es_entity::clock::ClockHandle;
use std::time::Duration;

let clock = ClockHandle::realtime();

// Get current time
let now = clock.now();

// Sleep for a duration
clock.sleep(Duration::from_secs(1)).await;

// Timeout a future
match clock.timeout(Duration::from_secs(5), some_async_operation()).await {
    Ok(result) => println!("Completed: {:?}", result),
    Err(_) => println!("Timed out"),
}

Implementations

impl ClockHandle

pub fn realtime() -> Self

Create a real-time clock that uses the system clock and tokio timers.

pub fn artificial(config: ArtificialClockConfig) -> (Self, ClockController)

Create an artificial clock with the given configuration.

Returns a tuple of (ClockHandle, ClockController). The handle provides the common time interface, while the controller provides operations for advancing time.

Example

use es_entity::clock::{ClockHandle, ArtificialClockConfig, ArtificialMode};
use chrono::Utc;

// Manual mode - time only advances via controller.advance()
let (clock, ctrl) = ClockHandle::artificial(ArtificialClockConfig::manual());

// Auto mode - time advances 1000x faster than real time
let (clock, ctrl) = ClockHandle::artificial(ArtificialClockConfig::auto(1000.0));

// Start at a specific time
let (clock, ctrl) = ClockHandle::artificial(ArtificialClockConfig {
    start_at: Utc::now() - chrono::Duration::days(30),
    mode: ArtificialMode::Manual,
});

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

Get the current time.

This is a fast, synchronous operation regardless of clock type.

For real-time clocks, this returns Utc::now(). For artificial clocks, this returns the current artificial time.

pub fn sleep(&self, duration: Duration) -> ClockSleep

Sleep for the given duration.

For real-time clocks, this delegates to tokio::time::sleep. For artificial clocks in manual mode, this waits until time is advanced. For artificial clocks in auto mode, this sleeps for a scaled real duration.

pub fn timeout<F>(&self, duration: Duration, future: F) -> ClockTimeout<F>

where F: Future,

Apply a timeout to a future.

Returns Ok(output) if the future completes before the timeout, or Err(Elapsed) if the timeout expires first.

pub fn is_artificial(&self) -> bool

Check if this clock is artificial (as opposed to realtime).

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

Get the current artificial time, if this is an artificial clock that hasn’t transitioned to realtime.

Returns:

• None for realtime clocks
• None for artificial clocks that have transitioned to realtime
• Some(time) for artificial clocks (manual or auto) that are still artificial

This is useful for code that needs to cache time when running under artificial clocks but use fresh time for realtime clocks.

Trait Implementations

impl Clone for ClockHandle

fn clone(&self) -> ClockHandle

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ClockHandle

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

Formats the value using the given formatter.