High Precision Clock

high_precision_clock is a Rust library designed for high-precision timekeeping, especially useful for applications that require accurate time drift correction in cloud environments. The crate leverages system features like the Time Stamp Counter (TSC) for x86_64 Linux systems to provide highly precise timestamps with minimal drift. It is suitable for both synchronous and asynchronous contexts, making it versatile for various applications, including trading systems and time-sensitive analytics.

Key Features

• High Precision Timekeeping: Provides timestamps with minimal drift and high accuracy.
• TSC-based Timing: Uses the CPU’s Time Stamp Counter (TSC) for precise timing on supported systems.
• Drift Correction: Periodically recalibrates to correct drift against the system clock.
• Async Compatibility: Works seamlessly in both async and sync contexts.
• Cloud-Friendly: Optimized for cloud environments with potentially non-invariant TSC.

Example Usage

Here’s how you can initialize and use high_precision_clock in both synchronous and asynchronous contexts.

Synchronous Example

use high_precision_clock::HighPrecisionClock;
use std::time::Duration;

fn main() {
    // Initialize the high precision clock with a drift warning threshold (in nanoseconds) and drift correction interval
    let clock = HighPrecisionClock::new(100_000, Duration::from_secs(1));

    // Access the current precise time
    {
        let clock_read = clock.read().unwrap();
        let current_time = clock_read.now();
        println!("Current high-precision time: {}", current_time);
    }

    // Periodically check time drift
    std::thread::sleep(Duration::from_secs(3));
    {
        let clock_read = clock.read().unwrap();
        let drift_ns = clock_read.now() - chrono::Utc::now();
        println!("Time drift: {} ns", drift_ns.num_nanoseconds().unwrap_or_default());
    }
}

Asynchronous Example

To run the crate in an asynchronous context, enable the async feature in your Cargo.toml:

[dependencies]
high_precision_clock = { version = "0.1", features = ["async"] }
tokio = { version = "1", features = ["full"] }

Then, use it as shown below:

use high_precision_clock::HighPrecisionClock;
use tokio::time::Duration;

#[tokio::main]
async fn main() {
    // Initialize the high precision clock with drift threshold and interval
    let clock = HighPrecisionClock::new(100_000, Duration::from_secs(1));

    // Access the current precise time in async context
    {
        let clock_read = clock.read().await;
        let current_time = clock_read.now();
        println!("Current high-precision time: {}", current_time);
    }

    // Periodically check for drift
    tokio::time::sleep(Duration::from_secs(3)).await;
    {
        let clock_read = clock.read().await;
        let drift_ns = clock_read.now() - chrono::Utc::now();
        println!("Time drift: {} ns", drift_ns.num_nanoseconds().unwrap_or_default());
    }
}

Installation

To use high_precision_clock, add it to your Cargo.toml:

[dependencies]
high_precision_clock = "0.1"

If you want to use it in an async context, enable the async feature as shown:

[dependencies]
high_precision_clock = { version = "0.1", features = ["async"] }
tokio = { version = "1", features = ["full"] }

License

This project is licensed under the MIT License.