Struct UnixClock 

pub struct UnixClock<Timescale> { /* private fields */ }

A Unix OS clock

Implementations

impl UnixClock<UTC>

pub const CLOCK_REALTIME: Self

The standard realtime clock on unix systems.

use clock_steering::unix::UnixClock;
use statime_base::Clock;

fn main() {
    let clock = UnixClock::CLOCK_REALTIME;
    let now = clock.now().unwrap();

    println!("{now:?}");
}

impl UnixClock<TAI>

pub const CLOCK_TAI: Self

TAI time on linux systems.

use clock_steering::unix::UnixClock;
use statime_base::Clock;

fn main() {
    let clock = UnixClock::CLOCK_TAI;
    let now = clock.now().unwrap();

    println!("{now:?}");
}

pub fn open(path: impl AsRef<Path>) -> Result<Self>

Open a clock device.

use clock_steering::unix::UnixClock;
use statime_base::Clock;

fn main() {
    let clock = UnixClock::open("/dev/ptp0").unwrap();
    let now = clock.now().unwrap();

    println!("{now:?}");
}

Errors

Returns an error if the given path cannot be opened.

Examples found in repository

examples/basic.rs (line 18)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    #[cfg(target_os = "linux")]
    let arg = std::env::args().nth(1);

    #[cfg(target_os = "linux")]
    match arg.as_deref() {
        None | Some("realtime") => exercise_clock(UnixClock::CLOCK_REALTIME),
        Some("tai") => exercise_clock(UnixClock::CLOCK_TAI),
        Some(path) if path.starts_with("/dev/") => exercise_clock(UnixClock::open(path)?),
        Some(other) => {
            eprintln!("unknown clock: {other}");
            eprintln!("usage: basic [realtime|tai|/dev/ptpN]");
            std::process::exit(1);
        }
    }

    #[cfg(not(target_os = "linux"))]
    exercise_clock(UnixClock::CLOCK_REALTIME)
}

pub fn system_offset( &self, ) -> Result<(Timestamp<TAI>, Timestamp<TAI>, Timestamp<TAI>), ClockError>

Determine offset between file clock and TAI clock (if any) Returns two system timestamps sandwhiching a timestamp from the hardware clock.

Errors

Returns an error fi the system offset could not be provided.

impl<Timescale> UnixClock<Timescale>

pub fn disable_kernel(&self) -> Result<(), ClockError>

Disable any kernel disciplining of this clock.

Errors

May error if the clock has gone away.

Examples found in repository

examples/basic.rs (line 93)

fn exercise_clock<Timescale: Send + 'static>(
    clock: UnixClock<Timescale>,
) -> Result<(), Box<dyn std::error::Error>> {
    // Read-only operations

    let now = clock.now()?;
    let nanos = (now - Timestamp::UNIX_EPOCH).as_nanos();
    let seconds = nanos / 1_000_000_000;
    let nanos = nanos % 1_000_000_000;
    println!("now:         {}.{:09}", seconds, nanos);

    let res = clock.resolution()?;
    println!("resolution:  {}ns", res.as_nanos());

    let max_freq = clock.max_frequency()?;
    println!("max freq:    {} ppm", max_freq * 1e6);

    match clock.get_frequency() {
        Ok(f) => println!("frequency:   {:.6} us/s", f * 1e6),
        Err(e) => println!("frequency:   {e}"),
    }

    #[cfg(target_os = "linux")]
    match clock.get_tai() {
        Ok(tai) => println!("TAI offset:  {tai}s"),
        Err(e) => println!("TAI offset:  {e}"),
    }

    // Write operations — require root

    println!();

    match clock.set_frequency(0.0) {
        Ok(t) => println!(
            "set_frequency(0.0):     ok at {}.{:09}",
            (t - Timestamp::UNIX_EPOCH).as_nanos() / 1_000_000_000,
            (t - Timestamp::UNIX_EPOCH).as_nanos() % 1_000_000_000
        ),
        Err(e) => println!("set_frequency(0.0):     {e}"),
    }

    match clock.step_clock(Duration::from_seconds_nanos(0, 0)) {
        Ok(t) => println!(
            "step_clock(0):          ok at {}.{:09}",
            (t - Timestamp::UNIX_EPOCH).as_nanos() / 1_000_000_000,
            (t - Timestamp::UNIX_EPOCH).as_nanos() % 1_000_000_000
        ),
        Err(e) => println!("step_clock(0):          {e}"),
    }

    match clock.leap_update(LeapStatus::None) {
        Ok(()) => println!("set_leap_seconds:       ok"),
        Err(e) => println!("set_leap_seconds:       {e}"),
    }

    match clock.error_estimate_update(
        Duration::from_seconds_nanos(0, 100_000),
        Duration::from_seconds_nanos(0, 1_000_000),
    ) {
        Ok(()) => println!("error_estimate_update:  ok"),
        Err(e) => println!("error_estimate_update:  {e}"),
    }

    match clock.disable_kernel() {
        Ok(()) => println!("disable_kernel_ntp:     ok"),
        Err(e) => println!("disable_kernel_ntp:     {e}"),
    }

    Ok(())
}

pub fn set_tai(&self, tai_offset: i32) -> Result<(), ClockError>

Set the TAI offset on the given clock.

Errors

May error if the clock does not support setting the TAI offset.

pub fn get_tai(&self) -> Result<i32, ClockError>

Get the TAI offset on the given clock.

Errors

May error if the clock does not support getting the TAI offset.

Examples found in repository

examples/basic.rs (line 53)

fn exercise_clock<Timescale: Send + 'static>(
    clock: UnixClock<Timescale>,
) -> Result<(), Box<dyn std::error::Error>> {
    // Read-only operations

    let now = clock.now()?;
    let nanos = (now - Timestamp::UNIX_EPOCH).as_nanos();
    let seconds = nanos / 1_000_000_000;
    let nanos = nanos % 1_000_000_000;
    println!("now:         {}.{:09}", seconds, nanos);

    let res = clock.resolution()?;
    println!("resolution:  {}ns", res.as_nanos());

    let max_freq = clock.max_frequency()?;
    println!("max freq:    {} ppm", max_freq * 1e6);

    match clock.get_frequency() {
        Ok(f) => println!("frequency:   {:.6} us/s", f * 1e6),
        Err(e) => println!("frequency:   {e}"),
    }

    #[cfg(target_os = "linux")]
    match clock.get_tai() {
        Ok(tai) => println!("TAI offset:  {tai}s"),
        Err(e) => println!("TAI offset:  {e}"),
    }

    // Write operations — require root

    println!();

    match clock.set_frequency(0.0) {
        Ok(t) => println!(
            "set_frequency(0.0):     ok at {}.{:09}",
            (t - Timestamp::UNIX_EPOCH).as_nanos() / 1_000_000_000,
            (t - Timestamp::UNIX_EPOCH).as_nanos() % 1_000_000_000
        ),
        Err(e) => println!("set_frequency(0.0):     {e}"),
    }

    match clock.step_clock(Duration::from_seconds_nanos(0, 0)) {
        Ok(t) => println!(
            "step_clock(0):          ok at {}.{:09}",
            (t - Timestamp::UNIX_EPOCH).as_nanos() / 1_000_000_000,
            (t - Timestamp::UNIX_EPOCH).as_nanos() % 1_000_000_000
        ),
        Err(e) => println!("step_clock(0):          {e}"),
    }

    match clock.leap_update(LeapStatus::None) {
        Ok(()) => println!("set_leap_seconds:       ok"),
        Err(e) => println!("set_leap_seconds:       {e}"),
    }

    match clock.error_estimate_update(
        Duration::from_seconds_nanos(0, 100_000),
        Duration::from_seconds_nanos(0, 1_000_000),
    ) {
        Ok(()) => println!("error_estimate_update:  ok"),
        Err(e) => println!("error_estimate_update:  {e}"),
    }

    match clock.disable_kernel() {
        Ok(()) => println!("disable_kernel_ntp:     ok"),
        Err(e) => println!("disable_kernel_ntp:     {e}"),
    }

    Ok(())
}

pub fn resolution(&self) -> Result<Duration, ClockError>

Get the clock’s resolution.

The output Timestamp will be all zeros when the resolution is unavailable.

Errors

May error if the clcok has gone away

Examples found in repository

examples/basic.rs (line 41)

fn exercise_clock<Timescale: Send + 'static>(
    clock: UnixClock<Timescale>,
) -> Result<(), Box<dyn std::error::Error>> {
    // Read-only operations

    let now = clock.now()?;
    let nanos = (now - Timestamp::UNIX_EPOCH).as_nanos();
    let seconds = nanos / 1_000_000_000;
    let nanos = nanos % 1_000_000_000;
    println!("now:         {}.{:09}", seconds, nanos);

    let res = clock.resolution()?;
    println!("resolution:  {}ns", res.as_nanos());

    let max_freq = clock.max_frequency()?;
    println!("max freq:    {} ppm", max_freq * 1e6);

    match clock.get_frequency() {
        Ok(f) => println!("frequency:   {:.6} us/s", f * 1e6),
        Err(e) => println!("frequency:   {e}"),
    }

    #[cfg(target_os = "linux")]
    match clock.get_tai() {
        Ok(tai) => println!("TAI offset:  {tai}s"),
        Err(e) => println!("TAI offset:  {e}"),
    }

    // Write operations — require root

    println!();

    match clock.set_frequency(0.0) {
        Ok(t) => println!(
            "set_frequency(0.0):     ok at {}.{:09}",
            (t - Timestamp::UNIX_EPOCH).as_nanos() / 1_000_000_000,
            (t - Timestamp::UNIX_EPOCH).as_nanos() % 1_000_000_000
        ),
        Err(e) => println!("set_frequency(0.0):     {e}"),
    }

    match clock.step_clock(Duration::from_seconds_nanos(0, 0)) {
        Ok(t) => println!(
            "step_clock(0):          ok at {}.{:09}",
            (t - Timestamp::UNIX_EPOCH).as_nanos() / 1_000_000_000,
            (t - Timestamp::UNIX_EPOCH).as_nanos() % 1_000_000_000
        ),
        Err(e) => println!("step_clock(0):          {e}"),
    }

    match clock.leap_update(LeapStatus::None) {
        Ok(()) => println!("set_leap_seconds:       ok"),
        Err(e) => println!("set_leap_seconds:       {e}"),
    }

    match clock.error_estimate_update(
        Duration::from_seconds_nanos(0, 100_000),
        Duration::from_seconds_nanos(0, 1_000_000),
    ) {
        Ok(()) => println!("error_estimate_update:  ok"),
        Err(e) => println!("error_estimate_update:  {e}"),
    }

    match clock.disable_kernel() {
        Ok(()) => println!("disable_kernel_ntp:     ok"),
        Err(e) => println!("disable_kernel_ntp:     {e}"),
    }

    Ok(())
}

Trait Implementations

impl<Timescale: Send + 'static> Clock<Timescale> for UnixClock<Timescale>

fn now(&self) -> Result<Timestamp<Timescale>, ClockError>

Get current time

fn set_frequency(&self, freq: f64) -> Result<Timestamp<Timescale>, ClockError>

Change the frequency of the clock, returning the time at which the change was applied. The frequency is in seconds per second deviation.

fn get_frequency(&self) -> Result<f64, ClockError>

Get the frequency of the clock, in seconds per second deviation

fn max_frequency(&self) -> Result<f64, ClockError>

Maximum frequency offset the clock is capable of, in seconds per second deviation.

fn step_clock( &self, offset: Duration, ) -> Result<Timestamp<Timescale>, ClockError>

Change the current time of the clock by offset. Returns the time at which the change was applied.

fn error_estimate_update( &self, est_error: Duration, max_error: Duration, ) -> Result<(), ClockError>

Provide the system with our current best estimates for the statistical error of the clock (est_error), and the maximum deviation due to frequency error and distance to the root clock.

fn leap_update(&self, leap_status: LeapStatus) -> Result<(), ClockError>

Change the indicators for upcoming leap seconds. Application should happen at the end of the UTC month.

fn synchronization_update(&self, synchronized: bool) -> Result<(), ClockError>

Change the synchronization indicator.

impl<Timescale> Clone for UnixClock<Timescale>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<Timescale> Copy for UnixClock<Timescale>

impl<Timescale> Debug for UnixClock<Timescale>

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

Formats the value using the given formatter.