Module time

Expand description

Time and timestamp utilities

§IMPORTANT: Clock::raw() vs SystemTime for timestamps

This module provides utilities for both monotonic time (for performance measurements) and epoch time (for persistence, APIs, and logging).

§System Clock Error Handling

By default, timestamp functions return a sentinel value (near u64::MAX) when the system clock is broken. For production HFT systems, enable the panic-on-clock-error feature to panic immediately on clock errors:

[dependencies]
rusty-common = { path = "../rusty-common", features = ["panic-on-clock-error"] }

This ensures fail-fast behavior when timestamps cannot be trusted, preventing potential trading errors or authentication failures.

§Clock::raw() - Monotonic Time (NOT epoch time)

quanta::Clock::raw() returns nanoseconds since program start (monotonic time). This is ideal for:

Performance measurements and benchmarking
Duration calculations
Rate limiting windows
Internal sequence numbers
WebSocket ping/pong timing

§SystemTime - Epoch Time

SystemTime::now() returns time since Unix epoch (January 1, 1970 UTC). This is required for:

External API timestamps
Database timestamps
JWT token timestamps
Log timestamps
File timestamps
Any timestamp that needs to survive program restarts

§Common Mistakes to Avoid

❌ DON’T use Clock::raw() for epoch timestamps:

// WRONG - This is monotonic time, not epoch time!
let timestamp = clock.raw();
save_to_database(timestamp); // This will be wrong!

✅ DO use SystemTime for epoch timestamps:

use std::time::{SystemTime, UNIX_EPOCH};

let timestamp = SystemTime::now()
    .duration_since(UNIX_EPOCH)
    .unwrap()
    .as_nanos() as u64;
save_to_database(timestamp); // Correct!

✅ DO use Clock::raw() for performance measurements:

use quanta::Clock;

let clock = Clock::new();
let start = clock.raw();
// ... some operation ...
let end = clock.raw();
let duration_ns = end - start; // Correct for duration!

§Additional Tips

When working with timestamps, always consider the context and choose the correct type of timestamp. Monotonic time is suitable for performance measurements and internal sequence numbers, while epoch time is necessary for persistence and external APIs.

Functions§

days_since_epoch_to_date: Convert days since Unix epoch to (year, month, day)
format_current_time_fix: Format current time for FIX protocol (YYYYMMDD-HH:MM:SS)
format_timestamp_fix: Format timestamp for FIX protocol (YYYYMMDD-HH:MM:SS)
format_timestamp_fix_millis: Format timestamp for FIX protocol with milliseconds (YYYYMMDD-HH:MM:SS.sss)
format_timestamp_iso8601: Format timestamp for API requests (ISO 8601)
get_epoch_timestamp_ns: Get epoch timestamp for external systems, APIs, and persistence
get_epoch_timestamp_ns_safe: Get epoch timestamp for external systems (safe version)
get_monotonic_timestamp_ns: Get monotonic timestamp for performance measurements (NOT epoch time)
get_quanta_timestamp_ns: Get high-precision monotonic timestamp using quanta Clock
get_timestamp_ms: Get current timestamp in milliseconds
get_timestamp_ms_safe: Get current timestamp in milliseconds (safe version)
get_timestamp_ns_result: Get current timestamp in nanoseconds with proper error handling
get_timestamp_ns_safe: Get current timestamp in nanoseconds (safe version)
parse_rfc3339_timestamp: Parse RFC3339 timestamp string to nanoseconds with error handling Returns Result where the u64 is nanoseconds since Unix epoch On error, provides descriptive error message for debugging
parse_timestamp_with_fallback: Parse timestamp string with fallback to system time on error Logs warnings but never panics - returns current system time on parse failure
system_time_to_nanos: Convert a specific SystemTime to nanoseconds since Unix epoch

Module timeCopy item path