prism3_clock/
lib.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2025.
4 *    3-Prism Co. Ltd.
5 *
6 *    All rights reserved.
7 *
8 ******************************************************************************/
9//! Thread-safe clock abstractions for Rust.
10//!
11//! This crate provides a flexible and type-safe clock abstraction system with
12//! support for:
13//!
14//! - **Basic time access**: Get current UTC time
15//! - **High precision**: Nanosecond-level time measurements
16//! - **Timezone support**: Convert to local time in any timezone
17//! - **Monotonic time**: Time that never goes backwards
18//! - **Testing support**: Controllable mock clocks for tests
19//!
20//! # Architecture
21//!
22//! The crate is built around several orthogonal traits:
23//!
24//! - [`Clock`]: Base trait providing UTC time
25//! - [`NanoClock`]: Extension for nanosecond precision
26//! - [`ZonedClock`]: Extension for timezone support
27//! - [`ControllableClock`]: Extension for time control (testing)
28//!
29//! # Implementations
30//!
31//! Several clock implementations are provided:
32//!
33//! - [`SystemClock`]: Uses system wall clock time
34//! - [`MonotonicClock`]: Monotonic time (unaffected by system time changes)
35//! - [`NanoMonotonicClock`]: Monotonic time with nanosecond precision
36//! - [`MockClock`]: Controllable clock for testing
37//! - [`Zoned<C>`](Zoned): Wrapper that adds timezone support to any clock
38//!
39//! # Examples
40//!
41//! ## Basic Usage
42//!
43//! ```
44//! use prism3_clock::{Clock, SystemClock};
45//!
46//! let clock = SystemClock::new();
47//! let timestamp = clock.millis();
48//! let time = clock.time();
49//! println!("Current time: {}", time);
50//! ```
51//!
52//! ## With Timezone
53//!
54//! ```
55//! use prism3_clock::{Clock, ZonedClock, SystemClock, Zoned};
56//! use chrono_tz::Asia::Shanghai;
57//!
58//! let clock = Zoned::new(SystemClock::new(), Shanghai);
59//! let local = clock.local_time();
60//! println!("Local time in Shanghai: {}", local);
61//! ```
62//!
63//! ## Monotonic Time for Performance Measurement
64//!
65//! ```
66//! use prism3_clock::{Clock, MonotonicClock};
67//! use std::thread;
68//! use std::time::Duration;
69//!
70//! let clock = MonotonicClock::new();
71//! let start = clock.millis();
72//!
73//! thread::sleep(Duration::from_millis(100));
74//!
75//! let elapsed = clock.millis() - start;
76//! println!("Elapsed: {} ms", elapsed);
77//! ```
78//!
79//! ## Testing with MockClock
80//!
81//! ```
82//! use prism3_clock::{Clock, ControllableClock, MockClock};
83//! use chrono::{DateTime, Duration, Utc};
84//!
85//! let clock = MockClock::new();
86//!
87//! // Set to a specific time
88//! let fixed_time = DateTime::parse_from_rfc3339(
89//!     "2024-01-01T00:00:00Z"
90//! ).unwrap().with_timezone(&Utc);
91//! clock.set_time(fixed_time);
92//!
93//! assert_eq!(clock.time(), fixed_time);
94//!
95//! // Advance time
96//! clock.add_duration(Duration::hours(1));
97//! assert_eq!(clock.time(), fixed_time + Duration::hours(1));
98//! ```
99//!
100//! ## High-Precision Measurements
101//!
102//! ```
103//! use prism3_clock::{NanoClock, NanoMonotonicClock};
104//!
105//! let clock = NanoMonotonicClock::new();
106//! let start = clock.nanos();
107//!
108//! // Perform some operation
109//! for _ in 0..1000 {
110//!     // Some work
111//! }
112//!
113//! let elapsed = clock.nanos() - start;
114//! println!("Elapsed: {} ns", elapsed);
115//! ```
116//!
117//! ## Time Meters for Elapsed Time Measurement
118//!
119//! ```
120//! use prism3_clock::meter::TimeMeter;
121//! use std::thread;
122//! use std::time::Duration;
123//!
124//! let mut meter = TimeMeter::new();
125//! meter.start();
126//! thread::sleep(Duration::from_millis(100));
127//! meter.stop();
128//! println!("Elapsed: {}", meter.readable_duration());
129//! ```
130//!
131//! # Design Principles
132//!
133//! - **Interface Segregation**: Don't force implementations to provide
134//!   features they don't need
135//! - **Single Responsibility**: Each trait and type has one clear purpose
136//! - **Composition over Inheritance**: Extend functionality through wrappers
137//! - **Zero-Cost Abstractions**: Pay only for what you use
138//!
139//! # Author
140//!
141//! Haixing Hu
142
143// Re-export chrono types for convenience
144pub use chrono::{DateTime, Duration, Utc};
145pub use chrono_tz::Tz;
146
147// Traits
148mod clock;
149mod controllable_clock;
150mod nano_clock;
151mod zoned_clock;
152
153pub use clock::Clock;
154pub use controllable_clock::ControllableClock;
155pub use nano_clock::NanoClock;
156pub use zoned_clock::ZonedClock;
157
158// Implementations
159mod mock;
160mod monotonic;
161mod nano_monotonic;
162mod system;
163mod zoned;
164
165pub use mock::MockClock;
166pub use monotonic::MonotonicClock;
167pub use nano_monotonic::NanoMonotonicClock;
168pub use system::SystemClock;
169pub use zoned::Zoned;
170
171// Time meters
172pub mod meter;
prism3_clock/lib.rs

prism3_clock/
lib.rs
