Struct VenueClock 

pub struct VenueClock { /* private fields */ }

The earliest a venue’s clock can read at a given moment, from the times it stamped on events this host received.

Each observe gives a stamp and the Instant its event arrived. The event was stamped before it arrived, so at that instant the venue’s clock read the stamp or later: the delay in between only makes the stamp earlier. The clock keeps the one sample that bounds the venue’s time the tightest, allowing for drift since it was taken, and counts on from it on tokio’s clock. An old event delivered late, such as a fill a venue replays when a stream resubscribes, gives a loose bound and so never displaces a better one.

Caller obligations

• Observe only times the venue itself stamped. A time filled in from this host’s clock, for an event that arrived without one, is not the venue’s: if this host’s clock is ahead, it reads as a venue clock that is ahead too, and every bound taken from it is late. A Trade says which it is in its time_source.
• Pass the instant the event arrived, read from Instant::now. That is tokio’s clock, so a test runtime with a paused clock controls it.

Known limitations

• A stamp the venue sends from ahead of its own clock, such as one read in the wrong time zone, is kept: it bounds the venue’s time later than it is until a later sample bounds it later still. Compare the result with this host’s clock (see host_lead) to see such a stamp.
• A venue clock that steps back is followed only as fast as the drift allowance lets the old sample go, about 0.36 s an hour.
• Before the first sample there is no bound: earliest_at is None.
• The monotonic clock is not free of the host’s time keeping. On some platforms, such as Linux, it does not advance while the host is suspended, which makes the bound earlier than it could be: safe for a read’s start, but no help for its end. NTP can also slew it, up to 500 ppm or more while it corrects an offset, beyond the drift allowance. A slew that speeds it up corrects a wall clock that is behind, so a caller that also bounds a read’s start by the wall clock, taking the earlier of the two, stays covered.

Implementations

impl VenueClock

pub const fn new() -> Self

A clock with no sample yet.

pub fn observe(&mut self, stamp: DateTime<Utc>, received: Instant)

Records stamp, a time the venue stamped on an event that arrived at received.

Kept when it bounds the venue’s time at received later than the sample held, and otherwise dropped.

pub fn earliest_at(&self, at: Instant) -> Option<DateTime<Utc>>

The earliest the venue’s clock can read at at, or None before any sample.

Counts from the sample on tokio’s clock, less the drift allowance, so the venue’s clock reads this or later at at. at may be before the sample.

pub fn host_lead( &self, host_time: DateTime<Utc>, at: Instant, ) -> Option<TimeDelta>

The most this host’s clock can lead the venue’s, given it read host_time at at, or None before any sample. Negative when this host’s clock is behind the venue’s.

An upper bound: it is the true lead plus the delay of the sample held and the drift allowed for since. A large negative value says the venue’s clock is ahead, or that a stamp was (see the type’s known limitations).

pub fn span_start(&self, moment: HostMoment) -> Option<DateTime<Utc>>

Where a read of what the venue stamped from moment on starts: the earliest the venue’s clock can read at moment, or this host’s time then if that is earlier, as on a host clock behind the venue’s. None before any sample, when the caller has to allow for the difference between the clocks itself.

A host clock ahead of the venue’s does not make the start late, and one behind it costs a read that starts that much earlier. Less a caller’s own margin, for the delay between an event and its arrival, this is where a read of what was missed after moment begins.

pub fn span_end(&self, since: HostMoment, now: HostMoment) -> DateTime<Utc>

Where a read that has to reach now ends, for a span that began at since: the latest of this host’s time at now, the earliest the venue’s clock can read then, and since’s host time counted on to now on tokio’s clock. Before any sample the venue’s time is left out.

So neither a host clock behind the venue’s nor one stepped back since since ends the read early. The venue’s clock can still read later than this, as an estimate is a lower bound: add a margin for that.

Trait Implementations

impl Clone for VenueClock

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 VenueClock

impl Debug for VenueClock

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

Formats the value using the given formatter.

impl Default for VenueClock

fn default() -> Self

Returns the “default value” for a type.

impl Eq for VenueClock

impl PartialEq for VenueClock

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for VenueClock