Skip to main content

ntp_timer/
lib.rs

1//! # NTP 计时器
2//!
3//! 一个轻量级的 Rust NTP 时间同步库。
4//! 提供进程内缓存的全局时间,具有自动后台同步和时钟跳跃检测功能。
5//!
6//! ## 特性
7//!
8//! - **NTP 时间同步**:从多个 NTP 服务器获取精准时间戳
9//! - **指数退避重试**:自动采用指数退避策略重试(1秒 → 2秒 → 4秒...)
10//! - **死循环重试**:持续尝试所有服务器,直到至少一个成功
11//! - **内存缓存**:<0.1ms 的快速本地计算
12//! - **时钟跳跃检测**:自动检测和处理系统时钟异常调整
13//! - **后台同步**:异步定期同步任务,不阻塞主线程
14//! - **完全可配置**:所有关键参数都可自定义
15//! - **线程安全**:通过 `Arc<Mutex>` 支持并发访问
16//!
17//! ## 快速开始
18//!
19//! ```no_run
20//! use ntp_timer::{Config, TimerManager};
21//! use std::sync::Arc;
22//!
23//! #[tokio::main]
24//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
25//!     // 创建默认配置
26//!     let config = Config::default()
27//!         .with_sync_interval(600)      // 每 10 分钟同步一次
28//!         .with_jump_threshold(5)       // 时钟跳跃阈值:5 秒
29//!         .with_max_retries(10)         // 每个服务器最多重试 10 次
30//!         .with_initial_retry_interval(1); // 初始延迟 1 秒
31//!
32//!     // 初始化全局计时器
33//!     TimerManager::init_global_timer(Arc::new(config)).await?;
34//!
35//!     // 检查初始化是否完成
36//!     if TimerManager::is_initialized() {
37//!         // 获取当前时间戳(快速路径,<0.1ms)
38//!         let timestamp = TimerManager::get_timestamp()?;
39//!         println!("当前时间戳: {}", timestamp);
40//!
41//!         // 手动同步
42//!         let synced_ts = TimerManager::manual_sync().await?;
43//!         println!("同步后的时间戳: {}", synced_ts);
44//!     }
45//!
46//!     Ok(())
47//! }
48//! ```
49//!
50//! ## 架构
51//!
52//! - **GlobalTimer**:核心数据结构,保存 NTP 时间戳和初始化状态
53//! - **TimerManager**:公开 API,提供全局计时器访问(单例模式)
54//! - **Config**:可配置参数(同步间隔、NTP 服务器、重试策略等)
55//! - **NTP Module**:低层 NTP 协议实现,包括指数退避和死循环重试
56
57pub mod config;
58pub mod error;
59pub mod ntp;
60pub mod sync;
61pub mod timer;
62
63pub use config::Config;
64pub use error::TimerError;
65pub use sync::TimerManager;
66pub use timer::GlobalTimer;
67
68/// 本 crate 中 Result 的便利类型别名
69pub type Result<T> = std::result::Result<T, TimerError>;