Skip to main content

Clock

Trait Clock 

Source
pub trait Clock: Debug + Any {
Show 20 methods // 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: DurationNanos, 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<()> { ... } fn set_timer_schedule( &mut self, name: &str, schedule: Arc<dyn TimerSchedule>, stop_time_ns: Option<UnixNanos>, callback: Option<TimeEventCallback>, allow_past: Option<bool>, fire_immediately: Option<bool>, ) -> Result<()> { ... }
}
Expand description

Provides time access, timer scheduling, and callback registration.

An active timer is one that has not expired.

Required Methods§

Source

fn timestamp_ns(&self) -> UnixNanos

Returns the current UNIX timestamp in nanoseconds (ns).

Source

fn timestamp_us(&self) -> u64

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

Source

fn timestamp_ms(&self) -> u64

Returns the current UNIX timestamp in milliseconds (ms).

Source

fn timestamp(&self) -> f64

Returns the current UNIX timestamp in seconds.

Source

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

Returns the names of active timers in the clock.

Source

fn timer_count(&self) -> usize

Returns the count of active timers in the clock.

Source

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

Returns whether an active timer named name exists.

Source

fn register_default_handler(&mut self, callback: TimeEventCallback)

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

Source

fn cancel_default_handler(&mut self)

Cancels the registered default event handler, if any.

Queued time event handlers no longer invoke the default callback.

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.

Source

fn cancel_callbacks(&mut self)

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

Queued time event handlers no longer invoke named callbacks.

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.

Source

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_pastBehavior
trueA past alert is moved to the current time and fires immediately.
falseAn 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.
Source

fn set_timer_ns( &mut self, name: &str, interval_ns: DurationNanos, 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_pastfire_immediatelyFirst event behavior
truetrueFires at the start time, including a past start.
truefalseFires one interval after the start, including past.
falsetrueA past start time returns an error.
falsefalseA 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.
Source

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.

Source

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

Cancels the timer named name, if it exists.

Source

fn cancel_timers(&mut self)

Cancels all timers.

Source

fn reset(&mut self)

Resets scheduling state while preserving the default callback.

The reset clears all timers and revokes named callbacks, including queued copies. Static clocks also reset their stored time.

Provided Methods§

Source

fn utc_now(&self) -> Timestamp

Returns the current UTC timestamp.

Source

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.
Source

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.
Source

fn set_timer_schedule( &mut self, name: &str, schedule: Arc<dyn TimerSchedule>, stop_time_ns: Option<UnixNanos>, callback: Option<TimeEventCallback>, allow_past: Option<bool>, fire_immediately: Option<bool>, ) -> Result<()>

Registers a recurring source of absolute UTC deadlines.

The schedule supplies its nominal start and deadlines. The clock owns event delivery, cancellation, replacement, and the inclusive stop time. See Clock::set_timer_ns for flag and callback semantics. An explicit epoch start supplied by the schedule stays at the UNIX epoch.

§Errors

Returns an error if:

  • This clock does not support deadline schedules.
  • name is invalid.
  • No valid first deadline exists 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.

Implementations§

Source§

impl dyn Clock

Source

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

Returns a reference to this clock as Any for downcasting.

Source

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§