Struct HostClock 

pub struct HostClock { /* private fields */ }

Available on crate feature std only.

Maps a host’s monotonic clock, as std::time::Instant, onto the nanosecond timeline the cores take, and back. Both ways are exact for every instant the timeline holds, so a timer set at the host instant of a core’s deadline never wakes before that deadline is due.

The clock fixes one host instant, its origin, to one point of the timeline:

• HostClock::new puts the origin at Instant::ZERO: the usual choice, with the origin taken as the host starts its cores. A host instant before the origin maps to Instant::ZERO.
• HostClock::centred puts it at 2^63 ns, the middle of the timeline, so instants up to about 292 years either side of it map exactly. A host that also hands the cores times from before it started (a restored or backdated record, say) takes this one.

now reads the host clock through a function the host chooses, std::time::Instant::now unless reading names another. An async runtime whose time can be paused in tests (Tokio’s tokio::time::Instant::now().into_std(), say) passes its own, so the cores’ deadlines follow the runtime’s time.

use bacnet_time::{Duration, HostClock, Instant};

let origin = std::time::Instant::now();
let clock = HostClock::new(origin);
let later = origin + std::time::Duration::from_millis(250);
assert_eq!(clock.instant(later), Instant::from_millis(250));
assert_eq!(clock.to_std(Instant::from_millis(250)), Some(later));

// Centred: an instant before the origin keeps its distance from it.
let clock = HostClock::centred(later);
assert_eq!(clock.instant(later) - clock.instant(origin), Duration::from_millis(250));
assert_eq!(clock.to_std(clock.instant(origin)), Some(origin));

Implementations

impl HostClock

pub fn new(origin: StdInstant) -> Self

A clock that maps origin to Instant::ZERO and reads std::time::Instant::now. Host instants before origin map to Instant::ZERO, and those more than about 584 years after it to Instant::MAX.

pub fn centred(origin: StdInstant) -> Self

A clock that maps origin to the middle of the timeline, 2^63 ns, and reads std::time::Instant::now: host instants up to about 292 years either side of origin map exactly, and those further away saturate at Instant::ZERO or Instant::MAX.

pub fn reading(self, now: fn() -> StdInstant) -> Self

This clock, with now reading now instead. now must give instants on the same monotonic clock as the origin.

pub fn origin(&self) -> StdInstant

The host instant this clock is built on.

pub fn now(&self) -> Instant

The timeline’s time now, from the clock’s source.

pub fn instant(&self, at: StdInstant) -> Instant

at on the timeline, saturating as the constructor says.

The difference is taken from the later of at and the origin. On Windows, std reports an earlier instant less than one counter tick (100 ns) away as no time at all, which would put an instant just before the origin on the origin itself.

pub fn to_std(&self, at: Instant) -> Option<StdInstant>

The host instant that at on the timeline stands for, or None when the host’s clock can’t represent it. A host sleeping until a core’s deadline takes None as no deadline: that far out, it never comes.

Trait Implementations

impl Clone for HostClock

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for HostClock

impl Debug for HostClock

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

Formats the value using the given formatter.