rust-mc-status 3.0.0

//! Monotonic latency measurement for protocol implementations.
//!
//! Uses [`tokio::time::Instant`] instead of [`std::time::SystemTime`] because:
//!
//! - `Instant` is **monotonic** — it never goes backwards, even when the
//!   system clock is adjusted by NTP or the user.
//! - `SystemTime` can go backwards on clock corrections, which would cause
//!   `elapsed()` to return an error or a negative duration.
//! - `Instant` has no epoch — it cannot be serialised or compared across
//!   process restarts, but that is fine here since we only measure short
//!   durations within a single ping.
//!
//! # Usage
//!
//! ```rust,ignore
//! use rust_mc_status::core::time::{start_timer, elapsed_ms};
//!
//! let start = start_timer();
//! // … network operation …
//! let latency = elapsed_ms(start); // f64, always ≥ 0
//! ```

use tokio::time::Instant;

/// Record the start of a latency measurement.
///
/// Returns a [`tokio::time::Instant`] that should be passed to [`elapsed_ms`]
/// after the operation completes.
///
/// # Example
///
/// ```rust,ignore
/// let start = start_timer();
/// do_something().await;
/// let ms = elapsed_ms(start);
/// ```
#[inline]
pub fn start_timer() -> Instant {
    Instant::now()
}

/// Return elapsed milliseconds since `start` as `f64`.
///
/// Always returns a non-negative value — the underlying monotonic clock
/// guarantees that `Instant::elapsed` never goes backwards.
///
/// # Example
///
/// ```rust,ignore
/// let start = start_timer();
/// do_something().await;
/// println!("{:.2} ms", elapsed_ms(start));
/// ```
#[inline]
pub fn elapsed_ms(start: Instant) -> f64 {
    start.elapsed().as_secs_f64() * 1000.0
}