Struct MeasurementCounter 

pub struct MeasurementCounter { /* private fields */ }

Shared, inert measurement arithmetic; registration identity remains timer-owned. A scalar total in one consumer-selected unit with tracked actual overflow.

Use for diagnostic event counts, item counts or quantities such as bytes. Each addition increases the total without retaining a sample count, maximum, latest value or distribution. Zero is an exact total, not an absent metric; consumers own whether a counter exists and which events may increment it.

Totals clip at u128::MAX with a sticky flag for actual overflow. An exactly reached cap remains exact. Inputs must already be exact: adding a clamped quantity cannot restore its lost quality. Consumers own units, identities, reset boundaries and reporting. No allocation, platform reads or logging. Diagnostic totals do not replace authoritative budgets, balances or debt.

use ic_metrics::MeasurementCounter;
let mut retries = MeasurementCounter::ZERO;
retries.add(1);
retries.add(1);
assert_eq!(retries.exact_total()?, 2);
let mut bytes = MeasurementCounter::ZERO;
let before = bytes;
bytes.add(32_768);
bytes.add(0);
assert_eq!(bytes.delta_since(before)?, 32_768);

Implementations

impl MeasurementCounter

pub const ZERO: MeasurementCounter

Zero total with no actual overflow; zero additions remain exact.

pub const fn from_parts( total: u128, total_overflowed: bool, ) -> Result<MeasurementCounter, MeasurementStateError>

Restore a total and its actual-overflow flag after numeric admission.

A cap with a false flag remains exact. The caller owns provenance, units and identity; missing or previously discarded quality cannot be inferred.

Errors

Returns MeasurementStateError::InvalidOverflowFlag when a true flag accompanies a total below its clipped cap.

pub const fn add(&mut self, amount: u128)

Add an admitted exact quantity, including zero, in the existing unit.

Use one for an event; larger quantities can account for a whole batch. This never wraps or clears an existing overflow flag.

pub const fn merge(&mut self, other: MeasurementCounter)

Add a counter’s total while preserving any source overflow.

Consumers establish matching units and deliberate attribution. This is addition, not deduplication: merging the same batch twice counts it twice.

pub const fn total(self) -> u128

Total clipped at u128::MAX; check Self::total_overflowed.

pub const fn total_overflowed(self) -> bool

Whether addition or merging has actually overflowed the total.

pub const fn exact_total(self) -> Result<u128, MeasurementCounterError>

Exact total, including zero and an exactly reached cap.

Use a checked conversion when a consumer report requires a narrower type; a narrowing failure is distinct from this accumulator’s overflow.

Errors

Returns MeasurementCounterError::TotalOverflow on actual overflow.

pub const fn delta_since( self, previous: MeasurementCounter, ) -> Result<u128, MeasurementCounterError>

Exact difference from an earlier snapshot of this counter, including zero.

Consumers must first establish matching units, counter/window identity and append-only continuity. Numeric success cannot detect a reset followed by larger values, changed attribution or an unrelated counter.

Errors

Rejects actual overflow in either snapshot before a decreasing total.

Trait Implementations

impl Clone for MeasurementCounter

fn clone(&self) -> MeasurementCounter

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for MeasurementCounter

impl Debug for MeasurementCounter

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

Formats the value using the given formatter.

impl Default for MeasurementCounter

fn default() -> MeasurementCounter

Returns the “default value” for a type.

impl Eq for MeasurementCounter

impl PartialEq for MeasurementCounter

fn eq(&self, other: &MeasurementCounter) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for MeasurementCounter