Struct tai_time::TaiClock

source ·

pub struct TaiClock<const EPOCH_REF: i64> { /* private fields */ }

Available on crate feature std only.

Expand description

A monotonic clock that generates TaiTime timestamps.

This clock internally relies on Instant::now and can therefore be used on systems that do not support TaiTime::now, or when the time reference needs to differ from the wall clock time (clock with offset).

A TaiClock instance can be simultaneously accessed from several threads.

§Examples

use std::thread;
use std::sync::Arc;
use tai_time::TaiClock;

type MyCustomClock = TaiClock<123>;

// Initialize the TAI clock assuming that the current difference
// between TAI and UTC time is 37s.
let clock = Arc::new(MyCustomClock::init_from_utc(37));

// Time the execution of 2 different threads.
let th1 = thread::spawn({
    let clock = clock.clone();
    move || clock.now()
});
let th2 = thread::spawn(
    move || clock.now()
);
let t1 = th1.join().unwrap();
let t2 = th2.join().unwrap();

println!("thread 1 has completed at {} TAI", t1);
println!("thread 2 has completed at {} TAI", t2);

Implementations§

source §

impl<const EPOCH_REF: i64> TaiClock<EPOCH_REF>

source

pub fn init_at(now: TaiTime<EPOCH_REF>) -> Self

Initializes the clock by associating a TAI timestamp to the current wall clock time.

Future calls to now will return timestamps that are relative to the provided timestamp, with a constant offset with respect to the monotonic wall clock time.

source

pub fn init_from_utc(leap_secs: i64) -> Self

Initializes the clock from the UTC system clock.

The argument is the difference between TAI and UTC time in seconds (a.k.a. leap seconds) applicable at the date represented by the timestamp. For reference, this offset has been +37s since 2017-01-01, a value which is to remain valid until at least 2024-12-28. See the official IERS bulletin C for leap second announcements or the IERS table for current and historical values.

Beware that the behavior of the system clock near a leap second shouldn’t be relied upon, where near might actually stand for the whole 24h period preceding a leap second due to the possible use of the so-called leap second smearing strategy.

Note that TaiClock is based on the monotonic system clock while UTC time can only be obtained from the non-monotonic system clock. This constructor attempts to find a well-correlated pair of monotonic and UTC system clock timestamps by collecting several candidate samples from interleaved calls to SystemTime::now and Instant::now.

source

pub fn init_from_instant( timestamp_ref: TaiTime<EPOCH_REF>, wall_clock_ref: Instant ) -> Self

Initializes the clock by associating the provided TAI timestamp to the provided Instant.

The wall_clock_ref argument may lie in the past or in the future of the current wall clock time.

Future calls to now will return timestamps with a constant offset with respect to the monotonic wall clock time. The offset is defined by the requirement that now should return timestamp_ref when the wall clock time matches wall_clock_ref.

source

pub fn init_from_system_time( timestamp_ref: TaiTime<EPOCH_REF>, wall_clock_ref: SystemTime ) -> Self

Initializes the clock by associating a TAI timestamp to a SystemTime.

The wall_clock_ref argument may lie in the past or in the future of the current wall clock time.

Future calls to now will return timestamps with a constant offset with respect to the monotonic wall clock time. The offset is defined by the requirement that now should return timestamp_ref when the wall clock time matches wall_clock_ref.

Note that TaiClock is based on the monotonic system clock while UTC time can only be obtained from the non-monotonic system clock. This constructor attempts to find a well-correlated pair of monotonic and UTC system clock timestamps by collecting several candidate samples from interleaved calls to SystemTime::now and Instant::now.

source