Struct LiveClock 

pub struct LiveClock { /* private fields */ }

A real-time clock which uses system time.

Timestamps are guaranteed to be unique and monotonically increasing.

Threading

The clock holds thread-local runtime state and must remain on its originating thread.

Implementations

impl LiveClock

pub fn new(sender: Option<Arc<dyn TimeEventSender>>) -> Self

Creates a new LiveClock instance.

pub const fn get_timers(&self) -> &BTreeMap<Ustr, LiveTimer>

Methods from Deref<Target = AtomicTime>

pub fn get_time_ns(&self) -> UnixNanos

Returns the current time in nanoseconds, based on the clock’s mode.

• In real-time mode, calls [AtomicTime::time_since_epoch], ensuring strictly increasing timestamps across threads, using AcqRel semantics for the underlying atomic.
• In static mode, reads the stored time using Ordering::Acquire. Updates by other threads using [AtomicTime::set_time] or [AtomicTime::increment_time] (Release/AcqRel) will be visible here.

Thread Safety

The mode check is not atomic with the subsequent read/update. If another thread switches modes between the check and the operation, one stale-mode result may be returned. This is intentional: mode switching is a setup-time operation and should not occur concurrently with time operations.

pub fn get_time_us(&self) -> u64

Returns the current time as microseconds.

pub fn get_time_ms(&self) -> u64

Returns the current time as milliseconds.

pub fn get_time(&self) -> f64

Returns the current time as seconds.

pub fn set_time(&self, time: UnixNanos)

Manually sets a new time for the clock (only possible in static mode).

This uses an atomic store with Ordering::Release, so any thread reading with Ordering::Acquire will see the updated time. This does not enforce a total ordering among all threads, but is enough to ensure that once a thread sees this update, it also sees all writes made before this call in the writing thread.

Typically used in single-threaded scenarios or coordinated concurrency in static mode, since there’s no global ordering across threads.

Panics

Panics if invoked when in real-time mode.

Thread Safety

The mode check is not atomic with the subsequent store. If another thread calls make_realtime() between the check and store, the invariant can be violated. This is intentional: mode switching is a setup-time operation and should not occur concurrently with time operations. Callers must ensure mode switches are complete before resuming time operations.

pub fn increment_time(&self, delta: u64) -> Result<UnixNanos, Error>

Increments the current (static-mode) time by delta nanoseconds and returns the updated value.

Internally this uses AtomicU64::try_update with Ordering::AcqRel to ensure the increment is atomic and visible to readers using Acquire loads.

Errors

Returns an error if the increment would overflow u64::MAX or if called while the clock is in real-time mode.

Thread Safety

The mode check is not atomic with the subsequent update. If another thread calls make_realtime() between the check and update, the invariant can be violated. This is intentional: mode switching is a setup-time operation and should not occur concurrently with time operations. Callers must ensure mode switches are complete before resuming time operations.

pub fn time_since_epoch(&self) -> UnixNanos

Retrieves and updates the current “real-time” clock, returning a strictly increasing timestamp based on system time.

Internally:

• We fetch now from SystemTime::now().
• We do an atomic compare-and-exchange (using Ordering::AcqRel) to ensure the stored timestamp is never less than the last timestamp.

This ensures:

1. Monotonic increments: The returned timestamp is strictly greater than the previous one (by at least 1 nanosecond).
2. No backward jumps: If the OS time moves backward, we ignore that shift to preserve monotonicity.
3. Visibility: In a multi-threaded environment, other threads see the updated value once this compare-and-exchange completes.

Panics

Panics if the internal counter has reached u64::MAX, which would indicate the process has been running for longer than the representable range (~584 years) or the clock was manually corrupted.

pub fn make_realtime(&self)

Switches the clock to real-time mode (realtime = true).

If transitioning from static mode, the internal counter is reset to the current wall-clock time so that [AtomicTime::time_since_epoch] does not carry forward a timestamp set during static mode (e.g. a backtest far in the future).

Uses Ordering::SeqCst for the mode flag to ensure global ordering.

Thread Safety

The mode swap and the counter reset are two separate atomic operations. A thread reading between them can observe real-time mode with the stale static-mode counter and return a timestamp derived from it (potentially far in the future), after which the reset moves the clock backwards. Mode switching is a setup-time operation and must not run concurrently with time reads.

pub fn make_static(&self)

Switches the clock to static mode (realtime = false).

If transitioning from real-time mode, the internal counter is snapshotted to the current wall-clock time so that subsequent static reads return a reasonable value rather than a stale or zero placeholder.

Uses Ordering::SeqCst for the mode flag to ensure global ordering.

Thread Safety

The mode swap and the counter snapshot are two separate atomic operations; see [AtomicTime::make_realtime] for the race this implies. Mode switching is a setup-time operation and must not run concurrently with time reads.

Trait Implementations

impl Clock for LiveClock

fn get_handler(&self, event: TimeEvent) -> TimeEventHandler

Panics

This function panics if:

• The event does not have an associated handler (see trait documentation).

fn timestamp_ns(&self) -> UnixNanos

Returns the current UNIX timestamp in nanoseconds (ns).

fn timestamp_us(&self) -> u64

Returns the current UNIX timestamp in microseconds (μs).

fn timestamp_ms(&self) -> u64

Returns the current UNIX timestamp in milliseconds (ms).

fn timestamp(&self) -> f64

Returns the current UNIX timestamp in seconds.

fn timer_names(&self) -> Vec<&str>

Returns the names of active timers in the clock.

fn timer_count(&self) -> usize

Returns the count of active timers in the clock.

fn timer_exists(&self, name: &Ustr) -> bool

If a timer with the name exists.

fn register_default_handler(&mut self, handler: TimeEventCallback)

Register a default event handler for the clock. If a timer does not have an event handler, then this handler is used.

fn cancel_default_handler(&mut self)

Cancel the registered default event handler (if any).

fn cancel_callbacks(&mut self)

Cancel all registered named event callbacks.

fn set_time_alert_ns( &mut self, name: &str, alert_time_ns: UnixNanos, callback: Option<TimeEventCallback>, allow_past: Option<bool>, ) -> Result<()>

Set a timer to alert at the specified time.

fn set_timer_ns( &mut self, name: &str, interval_ns: u64, start_time_ns: Option<UnixNanos>, stop_time_ns: Option<UnixNanos>, callback: Option<TimeEventCallback>, allow_past: Option<bool>, fire_immediately: Option<bool>, ) -> Result<()>

Set a timer to fire time events at every interval between start and stop time.

fn next_time_ns(&self, name: &str) -> Option<UnixNanos>

Returns the time interval in which the timer name is triggered.

fn cancel_timer(&mut self, name: &str)

Cancels the timer with name.

fn cancel_timers(&mut self)

Cancels all timers.

fn reset(&mut self)

Resets the clock by clearing it’s internal state.

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

Returns the current date and time as a timezone-aware DateTime<UTC>.

fn set_time_alert( &mut self, name: &str, alert_time: DateTime<Utc>, callback: Option<TimeEventCallback>, allow_past: Option<bool>, ) -> Result<()>

Set a timer to alert at the specified time.

fn set_timer( &mut self, name: &str, interval: Duration, start_time: Option<DateTime<Utc>>, stop_time: Option<DateTime<Utc>>, callback: Option<TimeEventCallback>, allow_past: Option<bool>, fire_immediately: Option<bool>, ) -> Result<()>

Set a timer to fire time events at every interval between start and stop time.

impl Debug for LiveClock

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

Formats the value using the given formatter.

impl Default for LiveClock

fn default() -> Self

Creates a new default LiveClock instance.

Uses try_get_time_event_sender() to allow creation before channels are initialized.

impl Deref for LiveClock

type Target = AtomicTime

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.