Module time_source 

Time source abstraction for rate limiting operations.

This module provides the TimeSource trait which abstracts different time sources while maintaining a clean separation of concerns. TimeSource is responsible for providing elapsed Duration since some starting point, while Precision handles the conversion to tick values.

Design Philosophy

The TimeSource abstraction enables:

• Testability: MockTimeSource for deterministic testing
• Flexibility: Support for different time sources (std::time, tokio, etc.)
• Isolation: Clean separation between time acquisition and precision conversion
• Performance: Zero-cost abstractions through static dispatch

Time Model

TimeSource implementations follow an “elapsed time” model similar to std::time::Instant::elapsed(). Each TimeSource has an implicit starting point and returns the Duration elapsed since that point.

This model ensures:

• Monotonic time progression
• Consistent behavior across different sources
• Natural integration with Duration-based APIs

Examples

Basic Usage

use rate_guard::time_source::{TimeSource, MockTimeSource};
use std::time::Duration;

let time_source = MockTimeSource::new();
let elapsed = time_source.now();
assert_eq!(elapsed, Duration::ZERO);

time_source.advance(Duration::from_millis(100));
let elapsed = time_source.now();
assert_eq!(elapsed, Duration::from_millis(100));

Integration with Precision

use rate_guard::time_source::{TimeSource, MockTimeSource};
use rate_guard::precision::{Precision, Millis};
use std::time::Duration;

let time_source = MockTimeSource::new();
time_source.advance(Duration::from_millis(250));

let elapsed = time_source.now();
let ticks = Millis::to_ticks(elapsed);
assert_eq!(ticks, 250);

Re-exports

pub use mock::MockTimeSource;

pub use std_time::StdTimeSource;

pub use tokio_time::TokioTimeSource;

Modules

mock

Mock time source implementation for deterministic testing.

std_time

Standard library time source implementation using std::time::Instant.

tokio_time

Tokio time source implementation using tokio::time::Instant.

Traits

TimeSource

Trait for providing elapsed time since a starting point.