Struct Counter

Source

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

Expand description

Ultra-fast atomic counter

Optimized for maximum throughput with minimal memory overhead. Cache-line aligned to prevent false sharing.

Implementations§

Source §

impl Counter

Source

pub fn new() -> Self

Create new counter starting at zero

Source

pub fn with_value(initial: u64) -> Self

Create counter with initial value

Source

pub fn inc(&self)

Increment by 1 - THE FASTEST PATH

This is optimized to be as fast as physically possible:

Single atomic fetch_add instruction
Relaxed memory ordering for maximum speed
Inlined for zero function call overhead

Source

pub fn try_inc(&self) -> Result<()>

Try to increment by 1 with overflow check

Returns Ok(()) on success, or Err(MetricsError::Overflow) if the increment would overflow u64::MAX.

Example

use metrics_lib::{Counter, MetricsError};
let c = Counter::with_value(u64::MAX - 1);
c.try_inc().unwrap();
assert_eq!(c.get(), u64::MAX);
assert!(matches!(c.try_inc(), Err(MetricsError::Overflow)));

Source

pub fn add(&self, amount: u64)

Add arbitrary amount - also blazingly fast

Zero branch optimization - if amount is 0, still does the atomic operation to maintain consistent performance characteristics

Source

pub fn try_add(&self, amount: u64) -> Result<()>

Try to add an arbitrary amount with overflow check

Returns Ok(()) on success, or Err(MetricsError::Overflow) if the addition would overflow u64::MAX.

Example

use metrics_lib::{Counter, MetricsError};
let c = Counter::with_value(u64::MAX - 5);
assert!(c.try_add(4).is_ok());
assert!(matches!(c.try_add(2), Err(MetricsError::Overflow)));

Source

pub fn get(&self) -> u64

Get current value - single atomic load

Source

pub fn reset(&self)

Reset to zero - use sparingly

Note: This uses SeqCst ordering to ensure all threads see the reset

Source

pub fn set(&self, value: u64)

Set to specific value - use sparingly

Note: This uses SeqCst ordering for consistency

Source

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

Try to set to a specific value (always succeeds for u64)

This method never fails and always returns Ok(()).

Source

pub fn compare_and_swap(&self, expected: u64, new: u64) -> Result<u64, u64>

Atomic compare-and-swap

Returns Ok(previous_value) if successful, Err(current_value) if failed

Source

pub fn fetch_add(&self, amount: u64) -> u64

Add amount and return previous value

Source

pub fn try_fetch_add(&self, amount: u64) -> Result<u64>

Checked fetch_add that returns the previous value or error on overflow

Returns the previous value on success, or Err(MetricsError::Overflow) if adding amount would overflow u64::MAX.

Example

use metrics_lib::{Counter, MetricsError};
let c = Counter::with_value(u64::MAX - 1);
assert_eq!(c.try_fetch_add(1).unwrap(), u64::MAX - 1);
assert!(matches!(c.try_fetch_add(1), Err(MetricsError::Overflow)));

Source

pub fn add_and_get(&self, amount: u64) -> u64

Add amount and return new value

Source

pub fn inc_and_get(&self) -> u64

Increment and return new value

Source

pub fn try_inc_and_get(&self) -> Result<u64>

Checked increment that returns new value or error on overflow

Returns the new value, or Err(MetricsError::Overflow) if the increment would overflow u64::MAX.

Example

use metrics_lib::{Counter, MetricsError};
let c = Counter::with_value(u64::MAX - 1);
assert_eq!(c.try_inc_and_get().unwrap(), u64::MAX);
assert!(matches!(c.try_inc_and_get(), Err(MetricsError::Overflow)));

Source