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§
Sourcefn timestamp_ns(&self) -> UnixNanos
fn timestamp_ns(&self) -> UnixNanos
Returns the current UNIX timestamp in nanoseconds (ns).
Sourcefn timestamp_us(&self) -> u64
fn timestamp_us(&self) -> u64
Returns the current UNIX timestamp in microseconds (μs).
Sourcefn timestamp_ms(&self) -> u64
fn timestamp_ms(&self) -> u64
Returns the current UNIX timestamp in milliseconds (ms).
Sourcefn timer_names(&self) -> Vec<&str>
fn timer_names(&self) -> Vec<&str>
Returns the names of active timers in the clock.
Sourcefn timer_count(&self) -> usize
fn timer_count(&self) -> usize
Returns the count of active timers in the clock.
Sourcefn timer_exists(&self, name: &Ustr) -> bool
fn timer_exists(&self, name: &Ustr) -> bool
Returns whether an active timer named name exists.
Sourcefn register_default_handler(&mut self, callback: TimeEventCallback)
fn register_default_handler(&mut self, callback: TimeEventCallback)
Registers the callback used when a timer has no named callback.
Sourcefn cancel_default_handler(&mut self)
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.
Sourcefn cancel_callbacks(&mut self)
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.
Sourcefn set_time_alert_ns(
&mut self,
name: &str,
alert_time_ns: UnixNanos,
callback: Option<TimeEventCallback>,
allow_past: Option<bool>,
) -> Result<()>
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 usescallbackfor the named alert.Noneuses a callback registered undername, falling back to the default callback.
§Errors
Returns an error if:
nameis invalid.alert_time_nsis earlier than now andallow_pastisSome(false).- No explicit, named, or default callback is available.
Sourcefn 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 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
NoneorSome(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 usescallbackfor the named timer.Noneuses a callback registered undername, falling back to the default callback.
§Errors
Returns an error if:
nameis invalid.interval_nsis zero.start_time_ns + interval_nsis out of range forUnixNanoswhen 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.
Sourcefn next_time_ns(&self, name: &str) -> Option<UnixNanos>
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.
Sourcefn cancel_timer(&mut self, name: &str)
fn cancel_timer(&mut self, name: &str)
Cancels the timer named name, if it exists.
Sourcefn cancel_timers(&mut self)
fn cancel_timers(&mut self)
Cancels all timers.
Provided Methods§
Sourcefn set_time_alert(
&mut self,
name: &str,
alert_time: Timestamp,
callback: Option<TimeEventCallback>,
allow_past: Option<bool>,
) -> Result<()>
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 usescallbackfor the named alert.Noneuses a callback registered undername, falling back to the default callback.
§Errors
Returns an error if:
nameis invalid.alert_timeis before the UNIX epoch or outside the [UnixNanos] range.- The alert is in the past and
allow_pastisSome(false). - No explicit, named, or default callback is available.
Sourcefn 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( &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 usescallbackfor the named timer.Noneuses a callback registered undername, falling back to the default callback.
§Errors
Returns an error if:
nameis invalid.intervalis zero or exceedsu64::MAXnanoseconds.start_timeorstop_timeis before the UNIX epoch or out of range forUnixNanos.- 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.
Sourcefn 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<()>
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.
nameis 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§
Dyn Compatibility§
This trait is dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".