ntp_timer/lib.rs
1//! # NTP Timer
2//!
3//! A lightweight NTP time synchronization library for Rust applications.
4//! Provides in-process cached global time with automatic background synchronization
5//! and clock-jump detection.
6//!
7//! ## Features
8//!
9//! - **NTP Time Synchronization**: Fetch precise timestamps from multiple NTP servers
10//! - **In-Memory Cache**: <0.1ms fast local calculation
11//! - **Clock Jump Detection**: Automatically detect and handle system clock adjustments
12//! - **Background Synchronization**: Async periodic sync tasks that don't block the main thread
13//! - **Fully Configurable**: All critical parameters are customizable
14//! - **Thread-Safe**: Concurrent access supported via Arc<Mutex>
15//!
16//! ## Quick Start
17//!
18//! ```no_run
19//! use ntp_timer::{Config, TimerManager};
20//! use std::sync::Arc;
21//!
22//! #[tokio::main]
23//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
24//! // Create configuration with default values
25//! let config = Config::default()
26//! .with_sync_interval(600) // Sync every 10 minutes
27//! .with_jump_threshold(5); // Clock jump threshold: 5 seconds
28//!
29//! // Initialize global timer
30//! TimerManager::init_global_timer(Arc::new(config)).await?;
31//!
32//! // Get current timestamp (fast path, <0.1ms)
33//! let timestamp = TimerManager::get_timestamp()?;
34//! println!("Current timestamp: {}", timestamp);
35//!
36//! // Manual synchronization
37//! let synced_ts = TimerManager::manual_sync().await?;
38//! println!("Synced timestamp: {}", synced_ts);
39//!
40//! Ok(())
41//! }
42//! ```
43//!
44//! ## Architecture
45//!
46//! - **GlobalTimer**: Core data structure holding NTP timestamp and system instant references
47//! - **TimerManager**: Public API providing global timer access (singleton pattern)
48//! - **Config**: Configurable parameters (sync interval, NTP servers, thresholds, etc.)
49//! - **NTP Module**: Low-level NTP protocol implementation
50
51pub mod config;
52pub mod error;
53pub mod ntp;
54pub mod sync;
55pub mod timer;
56
57pub use config::Config;
58pub use error::TimerError;
59pub use sync::TimerManager;
60pub use timer::GlobalTimer;
61
62/// Convenience type alias for Results in this crate
63pub type Result<T> = std::result::Result<T, TimerError>;