Trait Clock 

pub trait Clock: Debug + Any {
    // Required methods
    fn timestamp_ns(&self) -> UnixNanos;
    fn timestamp_us(&self) -> u64;
    fn timestamp_ms(&self) -> u64;
    fn timestamp(&self) -> f64;
    fn timer_names(&self) -> Vec<&str>;
    fn timer_count(&self) -> usize;
    fn timer_exists(&self, name: &Ustr) -> bool;
    fn register_default_handler(&mut self, callback: TimeEventCallback);
    fn cancel_default_handler(&mut self);
    fn cancel_callbacks(&mut self);
    fn set_time_alert_ns(
        &mut self,
        name: &str,
        alert_time_ns: UnixNanos,
        callback: Option<TimeEventCallback>,
        allow_past: Option<bool>,
    ) -> Result<()>;
    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<()>;
    fn next_time_ns(&self, name: &str) -> Option<UnixNanos>;
    fn cancel_timer(&mut self, name: &str);
    fn cancel_timers(&mut self);
    fn reset(&mut self);

    // Provided methods
    fn utc_now(&self) -> Timestamp { ... }
    fn set_time_alert(
        &mut self,
        name: &str,
        alert_time: Timestamp,
        callback: Option<TimeEventCallback>,
        allow_past: Option<bool>,
    ) -> Result<()> { ... }
    fn set_timer(
        &mut self,
        name: &str,
        interval: Duration,
        start_time: Option<Timestamp>,
        stop_time: Option<Timestamp>,
        callback: Option<TimeEventCallback>,
        allow_past: Option<bool>,
        fire_immediately: Option<bool>,
    ) -> Result<()> { ... }
}

Provides time access, timer scheduling, and callback registration.

An active timer is one that has not expired.

Required Methods

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

Returns whether an active timer named name exists.

fn register_default_handler(&mut self, callback: TimeEventCallback)

Registers the callback used when a timer has no named callback.

fn cancel_default_handler(&mut self)

Cancels the registered default event handler, if any.

Releases the held callback so any Python object owned by it can be dropped. Trader::release_component calls this at component retirement to break the cycle between a Python component and its clock: the clock holds the callback as a Py<PyAny> that Python’s cycle collector cannot reach through.

fn cancel_callbacks(&mut self)

Cancels all registered named event callbacks, preserving the default handler.

Releases callbacks registered via Clock::set_time_alert_ns or Clock::set_timer_ns with an explicit callback argument. Trader::release_component calls this at component retirement, breaking the same cycle as Clock::cancel_default_handler.

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

Sets a timer to alert at the specified time.

Any active timer registered under the same name is canceled with a warning before the new alert is scheduled. allow_past defaults to true.

Flags

allow_past	Behavior
true	A past alert is moved to the current time and fires immediately.
false	An alert earlier than the current time returns an error.

Callback

• Some(callback) registers and uses callback for the named alert.
• None uses a callback registered under name, falling back to the default callback.

Errors

Returns an error if:

• name is invalid.
• alert_time_ns is earlier than now and allow_past is Some(false).
• No explicit, named, or default callback is available.

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<()>

Sets a timer to fire time events at every interval between the start and stop times.

Any active timer registered under the same name is canceled with a warning before the new timer is scheduled. allow_past defaults to true, and fire_immediately defaults to false.

Start Time

• None or Some(0): Uses the current time as start time.
• Some(non_zero): Uses the specified timestamp as start time.

Flags

allow_past	fire_immediately	First event behavior
true	true	Fires at the start time, including a past start.
true	false	Fires one interval after the start, including past.
false	true	A past start time returns an error.
false	false	A past first event returns an error.

Callback

• Some(callback) registers and uses callback for the named timer.
• None uses a callback registered under name, falling back to the default callback.

Errors

Returns an error if:

• name is invalid.
• interval_ns is zero.
• start_time_ns + interval_ns is out of range for UnixNanos when not firing immediately.
• The first event is in the past when past times are disallowed.
• The stop time is not after the start time.
• The stop time is not after the current time when past times are disallowed.
• No explicit, named, or default callback is available.

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

Returns the next trigger timestamp for the active timer named name.

Returns None if no active timer with that name exists.

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

Cancels the timer named name, if it exists.

fn cancel_timers(&mut self)

Cancels all timers.

fn reset(&mut self)

Resets scheduling state while preserving the default callback.

The reset clears all timers and named callbacks. Static clocks also reset their stored time.

Provided Methods

fn utc_now(&self) -> Timestamp

Returns the current UTC timestamp.

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

Sets a timer to alert at the specified time.

See Clock::set_time_alert_ns for flag semantics.

Callback

• Some(callback) registers and uses callback for the named alert.
• None uses a callback registered under name, falling back to the default callback.

Errors

Returns an error if:

• name is invalid.
• alert_time is before the UNIX epoch or outside the [UnixNanos] range.
• The alert is in the past and allow_past is Some(false).
• No explicit, named, or default callback is available.

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

Sets a timer to fire time events at every interval between the start and stop times.

Any active timer registered under the same name is canceled with a warning before the new timer is scheduled.

See Clock::set_timer_ns for flag semantics.

Callback

• Some(callback) registers and uses callback for the named timer.
• None uses a callback registered under name, falling back to the default callback.

Errors

Returns an error if:

• name is invalid.
• interval is zero or exceeds u64::MAX nanoseconds.
• start_time or stop_time is before the UNIX epoch or out of range for UnixNanos.
• The first event timestamp is out of range for UnixNanos.
• The first event is in the past when past times are disallowed.
• The stop time is not after the start time.
• The stop time is not after the current time when past times are disallowed.
• No explicit, named, or default callback is available.

Implementations

impl dyn Clock

pub fn as_any(&self) -> &dyn Any

Returns a reference to this clock as Any for downcasting.

pub fn as_any_mut(&mut self) -> &mut dyn Any

Returns a mutable reference to this clock as Any for downcasting.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl Clock for LiveClock

impl Clock for TestClock