Summable

ktstr::metric_types

Trait Summable 

Source 
pub trait Summable:
    SummableSealed
    + Sized
    + Copy {
    // Required method
    fn sum_across(items: impl IntoIterator<Item = Self>) -> Self;

    // Provided method
    fn try_sum_across(items: impl IntoIterator<Item = Self>) -> Option<Self> { ... }
}
Expand description

Marker for newtypes that can be summed across a group.

Implemented by MonotonicCount, MonotonicNs, ClockTicks, and Bytes — every newtype whose value is a thread-lifetime accumulator. Summing two such accumulators across a group is well-defined because both contributors carry the same temporal window (each thread’s lifetime), and the group total represents the same window union.

Deliberately NOT implemented by PeakNs / GaugeNs / GaugeCount / OrdinalI32 / OrdinalU32 / OrdinalU64 / CategoricalString / CpuSet — those reductions are category errors and a generic site bound on T: Summable will reject them at compile time.

Sealed via sealed::SummableSealed: a downstream crate cannot write impl Summable for PeakNs because the sealed supertrait is private to this module.

sum_across uses saturating_add to mirror the existing crate::ctprof_compare::aggregate contract: per-thread counters are non-negative u64s, the group total cannot exceed u64::MAX, and a hostile or corrupt reading that would push the sum past u64::MAX saturates rather than wrapping.

sum_across collapses an empty iterator to the additive identity (zero, via Self::default() shape — the four counter newtypes default to Self(0)). Callers that need to distinguish “no contributors” from “all contributors had zero” — for example, to suppress a derived ratio whose denominator bucket was empty rather than zero-valued — use try_sum_across, which returns None for an empty iterator and Some(total) otherwise. The two methods report the same value on every non-empty input. The try_ prefix (rather than checked_) avoids colliding with the stdlib’s checked_* numeric methods, which detect arithmetic overflow — this method only flags an empty iterator (saturation happens unconditionally in sum_across).

Required Methods§

Source

fn sum_across(items: impl IntoIterator<Item = Self>) -> Self

Sum across the iterator, saturating at u64::MAX. Empty input collapses to the additive identity (zero).

Provided Methods§

Source

fn try_sum_across(items: impl IntoIterator<Item = Self>) -> Option<Self>

Same total as sum_across on every non-empty input; returns None for an empty iterator so callers can distinguish “no contributors” from “all contributors summed to zero.” Useful when a downstream derived metric (e.g. a ratio) needs to suppress the row entirely rather than render 0 / 0.

The try_ prefix (rather than checked_) avoids colliding with the stdlib’s checked_* numeric methods, which detect arithmetic overflow. This method only flags an empty iterator — overflow handling is identical to sum_across (saturating, unconditional).

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§