ntp-timer 0.2.0

A lightweight NTP time synchronization library for Rust applications. Provides in-process cached global time with background sync and clock-jump detection.
Documentation

NTP Timer

⏱️ A lightweight NTP time synchronization library for Rust applications.

Provides in-process cached global time with automatic background synchronization and clock-jump detection. Perfect for services that need reliable time without depending on system clock.

中文版本

Features

  • ✅ NTP Time Synchronization: Fetch precise timestamps from multiple NTP servers
  • ✅ In-Memory Cache: <0.1ms fast local calculation
  • ✅ Clock Jump Detection: Automatically detect and handle system clock adjustments
  • ✅ Background Synchronization: Async periodic sync tasks that don't block the main thread
  • ✅ Fully Configurable: All critical parameters are customizable (sync interval, jump threshold, etc.)
  • ✅ Thread-Safe: Concurrent access supported via Arc
  • ✅ Complete Error Handling: Custom TimerError type with detailed error information

Quick Start

Add to your Cargo.toml:

[dependencies]
ntp-timer = "0.1"

Basic usage:

use ntp_timer::{Config, TimerManager};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create configuration
    let config = Config::default()
        .with_sync_interval(600)   // Sync every 10 minutes
        .with_jump_threshold(5);   // Clock jump threshold: 5 seconds

    // Initialize global timer
    TimerManager::init_global_timer(Arc::new(config)).await?;

    // Check if initialization is complete
    if TimerManager::is_initialized() {
        // Get current timestamp after successful initialization
        let timestamp = TimerManager::get_timestamp()?;
        println!("Current timestamp: {}", timestamp);

        // Manual synchronization
        let synced_ts = TimerManager::manual_sync().await?;
        println!("Synced timestamp: {}", synced_ts);
    }

    Ok(())
}

Configuration

Parameter Default Description
sync_interval_secs 600 Background sync interval (seconds)
clock_jump_threshold_secs 5 Clock jump detection threshold (seconds)
ntp_servers [ntp.ntsc.ac.cn, ...] List of NTP servers
max_retries 10 Maximum retry attempts per server
socket_timeout_secs 5 Socket timeout (seconds)
initial_retry_interval_secs 1 Initial retry delay (seconds, exponential backoff)

API Reference

TimerManager::init_global_timer(config)

Initializes the global timer. On first call, fetches timestamp from NTP servers using exponential backoff retry mechanism and starts background sync task.

Behavior:

  • Performs automatic retry with exponential backoff (1s → 2s → 4s → ...)
  • Enters death loop retry mode if all servers fail in a round, continuously retries until at least one server succeeds
  • Marks timer as initialized after successful NTP timestamp acquisition
  • Sets initialization flag to true after successful sync

Returns: Result<(), TimerError>

TimerManager::get_timestamp()

Gets the current timestamp via fast local path (<0.1ms).

⚠️ Important: Call is_initialized() before using this method to ensure initialization is complete.

Returns: Result<i64, TimerError>

TimerManager::is_initialized()

Checks whether the global timer has been successfully initialized.

Returns: bool

  • true: Timer has been successfully initialized from NTP
  • false: Timer has not been initialized or initialization is still in progress

TimerManager::manual_sync()

Manually triggers NTP synchronization using the same exponential backoff and retry mechanism as initialization.

Behavior:

  • Uses identical retry strategy as initialization
  • Performs exponential backoff between retries
  • Continues retrying all servers until at least one succeeds
  • Updates initialization flag to true after successful sync

Returns: Result<i64, TimerError>

Architecture

TimerManager (Public API)
├── GlobalTimer (Core Data Structure)
│   ├── base_timestamp (NTP initial timestamp)
│   ├── base_instant (System clock reference point)
│   ├── last_sync_at (Last sync time)
│   └── initialized (Initialization state flag)
├── Config (Configurable Parameters)
└── NTP Module (NTP Protocol Implementation)
    ├── Exponential Backoff Strategy
    └── Death Loop Retry Mechanism

Design Highlights

Fast Path

get_timestamp() completes <0.1ms in 99.9% of cases:
    = base_timestamp + (Instant::now() - base_instant).as_secs()

Retry Strategy with Exponential Backoff

For each NTP server (up to max_retries times):
    - First attempt: no delay
    - Subsequent failures: 2^(n-1) second delay
    - Sequence: 1s → 2s → 4s → 8s → ...

If all servers fail in a round:
    - Automatically enters death loop retry mode
    - Continuously retries from the first server
    - Keeps trying until at least one server succeeds
    - No artificial limit on total attempts

Initialization State Management

is_initialized() returns:
    - false: Timer not yet initialized or still initializing
    - true: Timer successfully synchronized with NTP
    
Recommended usage:
    if TimerManager::is_initialized() {
        let ts = TimerManager::get_timestamp()?;  // Safe to use
    }

Clock Jump Detection

Checked during each sync:
    |new_ntp_timestamp - current_estimate| > threshold
    - Exceeds threshold → Reinitialize timer
    - Otherwise → Smooth baseline update (drift correction)

Background Synchronization

Async task runs every sync_interval_secs:
    - Non-blocking main thread
    - Uses same retry strategy as initialization
    - Continues using local timer on failure
    - Automatically detects and recovers from clock jumps
    - Updates initialization flag on successful sync

Performance Metrics

Operation Duration Notes
get_timestamp() <0.1ms Fast path (pure local calculation)
init_global_timer() 50-100ms Initial setup (NTP request)
manual_sync() 50-100ms Manual sync (NTP request)
NTP sync frequency 1/10min Background task interval

Testing

# Run unit tests
cargo test --lib

# Run documentation tests
cargo test --doc

# Run all tests including integration tests
cargo test

Use Cases

  • Distributed systems requiring synchronized timestamps
  • Rate limiting and traffic shaping (time-window based)
  • Cache expiration management
  • Log aggregation and correlation
  • Scheduled task execution
  • Any application needing reliable time without system clock dependency

Limitations

  • Precision: Returns time in seconds (not sub-millisecond precision)
  • Scope: Single application process (not system-wide)
  • Dependencies: Requires async runtime (tokio)

Future Plans

  • Millisecond/microsecond precision support
  • Configurable NTP server lists
  • Support for alternative time sources (PTP, Roughtime)
  • Performance benchmarks and optimizations

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

For Chinese contributors, see README.zh.md.


Made with ❤️ for reliable time synchronization in Rust