Struct Gauge

Source

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

Expand description

Ultra-fast atomic gauge for f64 values

Uses IEEE 754 bit manipulation for atomic operations on floating-point values. Cache-line aligned to prevent false sharing.

Implementations§

Source §

impl Gauge

Source

pub fn new() -> Self

Create new gauge starting at zero

Source

pub fn try_add(&self, delta: f64) -> Result<()>

Try to add to current value with validation

Returns Err(MetricsError::InvalidValue) if delta is not finite (NaN or ±inf) or if the resulting value would become non-finite. Returns Err(MetricsError::Overflow) if the sum overflows to a non-finite value.

Example

use metrics_lib::{Gauge, MetricsError};
let g = Gauge::with_value(1.5);
g.try_add(2.5).unwrap();
assert_eq!(g.get(), 4.0);
assert!(matches!(g.try_add(f64::INFINITY), Err(MetricsError::InvalidValue{..})));

Source

pub fn try_sub(&self, delta: f64) -> Result<()>

Try to subtract from current value (validated)

Validation semantics are identical to Gauge::try_add but apply to subtraction (-delta).

Example

use metrics_lib::Gauge;
let g = Gauge::with_value(10.0);
g.try_sub(4.0).unwrap();
assert_eq!(g.get(), 6.0);

Source

pub fn with_value(initial: f64) -> Self

Create gauge with initial value

Source

pub fn set(&self, value: f64)

Set gauge value - THE FASTEST PATH

This is optimized for maximum speed:

Convert f64 to IEEE 754 bits
Single atomic store instruction
Relaxed memory ordering for speed
Inlined for zero function call overhead

Source

pub fn try_set(&self, value: f64) -> Result<()>

Try to set gauge value with validation

Returns Err(MetricsError::InvalidValue) if value is not finite (NaN or ±inf).

Example

use metrics_lib::{Gauge, MetricsError};
let g = Gauge::new();
assert!(g.try_set(42.0).is_ok());
assert!(matches!(g.try_set(f64::NAN), Err(MetricsError::InvalidValue{..})));

Source

pub fn get(&self) -> f64

Get current value - single atomic load

Source

pub fn add(&self, delta: f64)

Add to current value - atomic read-modify-write loop

Uses compare-and-swap loop for lock-free addition

Source

pub fn sub(&self, delta: f64)

Subtract from current value

Source

pub fn set_max(&self, value: f64)

Set to maximum of current value and new value

Source

pub fn try_set_max(&self, value: f64) -> Result<()>

Try to set to maximum of current value and new value

Returns Err(MetricsError::InvalidValue) if value is not finite. Otherwise sets the gauge to max(current, value) and returns Ok(()).

Example

use metrics_lib::{Gauge, MetricsError};
let g = Gauge::with_value(5.0);
g.try_set_max(10.0).unwrap();
assert_eq!(g.get(), 10.0);
assert!(matches!(g.try_set_max(f64::INFINITY), Err(MetricsError::InvalidValue{..})));

Source

pub fn set_min(&self, value: f64)

Set to minimum of current value and new value

Source

pub fn try_set_min(&self, value: f64) -> Result<()>

Try to set to minimum of current value and new value

Returns Err(MetricsError::InvalidValue) if value is not finite. Otherwise sets the gauge to min(current, value) and returns Ok(()).

Example

use metrics_lib::{Gauge, MetricsError};
let g = Gauge::with_value(10.0);
g.try_set_min(7.0).unwrap();
assert_eq!(g.get(), 7.0);
assert!(matches!(g.try_set_min(f64::NAN), Err(MetricsError::InvalidValue{..})));

Source