Struct Timer 

#[repr(align(64))]
pub struct Timer { /* private fields */ }

High-precision timer with automatic statistics

Optimized for sub-10ns timing operations. Cache-line aligned to prevent false sharing.

Implementations

impl Timer

pub fn new() -> Self

Create new timer

pub fn try_record_ns(&self, duration_ns: u64) -> Result<()>

Try to record nanoseconds directly with overflow checks

Returns Err(MetricsError::Overflow) if adding duration_ns would overflow internal counters (total_nanos or count). On success updates min/max as needed.

Example

use metrics_lib::{Timer, MetricsError};
let t = Timer::new();
t.try_record_ns(1_000).unwrap();
assert_eq!(t.count(), 1);
assert!(matches!(t.try_record_ns(u64::MAX), Err(MetricsError::Overflow)));

pub fn start(&self) -> RunningTimer<'_>

Start timing - returns RAII guard that auto-records on drop

pub fn record(&self, duration: Duration)

Record a duration manually

pub fn try_record(&self, duration: Duration) -> Result<()>

Try to record a duration with overflow checks

Returns Err(MetricsError::Overflow) if adding this sample would overflow internal counters.

Example

use metrics_lib::{Timer, MetricsError};
use std::time::Duration;
let t = Timer::new();
assert!(t.try_record(Duration::from_millis(1)).is_ok());

pub fn record_ns(&self, duration_ns: u64)

Record nanoseconds directly - fastest path

pub fn record_batch(&self, durations: &[Duration])

Record multiple durations at once

pub fn try_record_batch(&self, durations: &[Duration]) -> Result<()>

Try to record multiple durations at once with overflow checks

Returns Err(MetricsError::Overflow) if the aggregated additions would overflow internal counters. Updates min/max based on batch extrema.

Example

use metrics_lib::Timer;
use std::time::Duration;
let t = Timer::new();
t.try_record_batch(&[Duration::from_micros(5), Duration::from_micros(10)]).unwrap();
assert_eq!(t.count(), 2);

pub fn count(&self) -> u64

Get current count of samples

Note: #[must_use]. The count informs control flow and sanity checks; ignoring it may indicate a logic bug.

pub fn total(&self) -> Duration

Get total accumulated time

Note: #[must_use]. The total duration is commonly used for reporting and ratios; dropping it may indicate a bug.

pub fn average(&self) -> Duration

Get average duration

Note: #[must_use]. The average is a derived metric; call this only when you consume the result.

pub fn min(&self) -> Duration

Get minimum duration

Note: #[must_use]. Often used for alerting/thresholds.

pub fn max(&self) -> Duration

Get maximum duration

Note: #[must_use]. Often used for alerting/thresholds.

pub fn reset(&self)

Reset all statistics

pub fn stats(&self) -> TimerStats

Get comprehensive statistics

Note: #[must_use]. Statistics summarize current state; dropping the result may indicate a logic bug.

pub fn age(&self) -> Duration

Get age since creation

Note: #[must_use]. Age is used in rate calculations; don’t call for side effects.

pub fn is_empty(&self) -> bool

Check if timer has recorded any samples

Note: #[must_use]. The boolean result determines control flow.

pub fn rate_per_second(&self) -> f64

Get samples per second rate

Note: #[must_use]. Derived metric; consume the result.

Trait Implementations

impl AsyncTimerExt for Timer

fn start_async(&self) -> AsyncTimerGuard<'_>

Start an async-aware timer

fn time_async<F, Fut, T>(&self, f: F) -> TimedFuture<'_, Fut>

where F: FnOnce() -> Fut, Fut: Future<Output = T>,

Time an async function

impl Debug for Timer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Timer

fn default() -> Self

Returns the “default value” for a type.

impl Display for Timer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Send for Timer

impl Sync for Timer