Struct MeasurementAggregate 

pub struct MeasurementAggregate { /* private fields */ }

Canonical shared arithmetic for local diagnostic summaries and distributions.

Re-exported so callers can name returned summaries without selecting a separate Metrics dependency. This is the shared type, with no local wrapper or arithmetic. Mergeable count, total and maximum in one consumer-selected unit.

Counts clip at u64::MAX and totals at u128::MAX; sticky flags record actual overflow, so an exactly reached cap remains exact. Maximum is an individual observation and remains valid after overflow. There is no latest observation: unordered batches cannot establish ordering. Every u64 sample fits in a u128 total while the sample count remains exact. No allocation or platform reads.

Implementations

impl MeasurementAggregate

pub const EMPTY: MeasurementAggregate

Empty aggregate, without a maximum observation.

pub const fn from_parts( samples: u64, total: u128, maximum: Option<u64>, samples_saturated: bool, total_saturated: bool, ) -> Result<MeasurementAggregate, MeasurementStateError>

Restore explicit fields after numeric consistency checks.

Exactly reached caps with false flags stay exact. This admits arithmetic consistency only; the caller owns provenance, units and window identity.

Errors

Rejects invalid empty state, missing maxima, inconsistent saturation flags and totals outside the range allowed by count and maximum.

pub const fn record(&mut self, value: u64)

Record one admitted observation, including zero, in the existing unit.

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

Combine observations from a batch without claiming ordering or identity.

Consumers must establish common units and deliberate sample attribution. This is addition, not deduplication: merging the same batch twice records it twice. Source overflow remains sticky even when its clipped value fits.

pub const fn samples(self) -> u64

Sample count, clipped at u64::MAX; check Self::samples_saturated.

pub const fn total(self) -> u128

Total, clipped at u128::MAX; check Self::total_saturated.

pub const fn samples_saturated(self) -> bool

Whether recording or merging has actually overflowed the sample count.

pub const fn total_saturated(self) -> bool

Whether recording or merging has actually overflowed the value total.

pub const fn maximum(self) -> Option<u64>

Largest observation, or None when empty, including after overflow.

pub const fn mean(self) -> Result<Option<u128>, MeasurementMeanError>

Floor-rounded mean, or None when empty. Exactly reached caps are valid.

Errors

Returns MeasurementMeanError::SaturatedSamples before MeasurementMeanError::SaturatedTotal when actual overflow is recorded.

pub const fn scaled_mean( self, scale: u64, ) -> Result<Option<u128>, MeasurementMeanError>

Compute floor(total * scale / samples) after checking actual overflow.

Scales the exact total before division, retaining fractional information that multiplying the integer mean would lose. A scale of ten reports tenths; callers own units and display. Empty is None, measured zero is Some(0), and an exactly reached count cap remains exact.

Errors

Rejects sample overflow, then total overflow, even with scale zero. A failed exact-ratio projection is MeasurementMeanError::Projection.

use ic_metrics::MeasurementAggregate;
let mut values = MeasurementAggregate::EMPTY;
assert_eq!(values.scaled_mean(10)?, None);
values.record(3);
values.record(4);
assert_eq!(values.mean()?, Some(3));
assert_eq!(values.scaled_mean(10)?, Some(35));

pub const fn interval_since( self, previous: MeasurementAggregate, ) -> Result<MeasurementInterval, MeasurementIntervalError>

Exact count/total difference from an earlier snapshot of this accumulator.

Consumers must first establish matching units, window/reset identity and append-only continuity. This cannot detect a reset followed by numerically larger values or changed attribution. Maxima and latest values are not subtractable and are not returned. Empty intervals differ from added zeros.

Errors

Rejects sample overflow, total overflow, decreasing samples, decreasing totals, then a changed total with no added samples, in that order.

Trait Implementations

impl Clone for MeasurementAggregate

fn clone(&self) -> MeasurementAggregate

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for MeasurementAggregate

impl Debug for MeasurementAggregate

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

Formats the value using the given formatter.

impl Default for MeasurementAggregate

fn default() -> MeasurementAggregate

Returns the “default value” for a type.

impl Eq for MeasurementAggregate

impl PartialEq for MeasurementAggregate

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for MeasurementAggregate