Struct ValueMesh

pub struct ValueMesh<T> { /* private fields */ }

A mesh of values, one per rank in region.

The internal representation (rep) may be dense or compressed, but externally the mesh always behaves as a complete mapping from rank index → value.

Invariants

• Complete: every rank in region has exactly one value.
• Order: iteration and indexing follow the region’s linearization.

Implementations

impl<T> ValueMesh<T>

pub fn empty() -> Self

Returns an empty mesh: a 1-dimensional region of length 0.

This differs from a dimensionless (0-D) region, which represents a single scalar element. A zero-length 1-D region has no elements at all, making it the natural Default placeholder for accumulator state initialization.

impl<T: Clone> ValueMesh<T>

pub fn from_single(region: Region, s: T) -> Self

Builds a ValueMesh that assigns the single value s to every rank in region, without materializing a dense Vec<T>. The result is stored in compressed (RLE) form as a single run [0..N).

If region.num_ranks() == 0, the mesh contains no runs (and an empty table), regardless of s.

impl<T: Clone + Default> ValueMesh<T>

pub fn from_default(region: Region) -> Self

Builds a ValueMesh covering the region, filled with T::default().

Equivalent to [ValueMesh::from_single(region, T::default())].

impl<T: Eq + Hash> ValueMesh<T>

pub fn from_ranges_with_default( region: Region, default: T, ranges: Vec<(Range<usize>, T)>, ) -> Result<Self>

Builds a compressed mesh from a default value and a set of disjoint ranges that override the default.

• ranges may be in any order; they must be non-empty, in-bounds, and non-overlapping.
• Unspecified ranks are filled with default.
• Result is stored in RLE form; no dense Vec<T> is materialized.

pub fn from_dense(region: Region, values: Vec<T>) -> Result<Self>

Builds a ValueMesh from a fully materialized dense vector of per-rank values, then compresses it into run-length–encoded form if possible.

This constructor is intended for callers that already have one value per rank (e.g. computed or received data) but wish to store it efficiently.

Parameters

• region: The logical region describing the mesh’s shape and rank order.
• values: A dense vector of values, one per rank in region.

Returns

A ValueMesh whose internal representation is Compressed if any adjacent elements are equal, or Dense if no compression was possible.

Errors

Returns an error if the number of provided values does not match the number of ranks in region.

Examples

let region: Region = extent!(n = 5).into();
let mesh = ValueMesh::from_dense(region, vec![1, 1, 2, 2, 3]).unwrap();
// Internally compressed to three runs: [1, 1], [2, 2], [3]

impl<F: Future> ValueMesh<F>

pub async fn join(self) -> ValueMesh<F::Output>

Await all futures in the mesh, yielding a ValueMesh of their outputs.

impl<T, E> ValueMesh<Result<T, E>>

pub fn transpose(self) -> Result<ValueMesh<T>, E>

Transposes a ValueMesh<Result<T, E>> into a Result<ValueMesh<T>, E>.

impl<T: PartialEq> ValueMesh<T>

pub fn compress_adjacent_in_place(&mut self)

Compresses the mesh in place using run-length encoding (RLE).

This method scans the mesh’s dense values, coalescing adjacent runs of identical elements into a compact [Rep::Compressed] representation. It replaces the internal storage (rep) with the compressed form.

Behavior

• If the mesh is already compressed, this is a no-op.
• If the mesh is dense, it consumes the current Vec<T> and rebuilds the representation as a run table plus value table.
• Only adjacent equal values are merged; non-contiguous duplicates remain distinct.

Requirements

• T must implement PartialEq (to detect equal values).

This operation is lossless: expanding the compressed mesh back into a dense vector yields the same sequence of values.

impl<T: Clone + Eq> ValueMesh<T>

pub fn merge_from_overlay( &mut self, overlay: ValueOverlay<T>, ) -> Result<(), BuildError>

Merge a sparse overlay into this mesh.

Overlay segments are applied with last-writer-wins precedence on overlap (identical to RankedValues::merge_from behavior). The result is stored compressed.

impl<T> ValueMesh<T>

pub fn compress_adjacent_in_place_by<F>(&mut self, same: F)

where F: FnMut(&T, &T) -> bool,

Compresses the mesh in place using a custom equivalence predicate.

This is a generalized form of [compress_adjacent_in_place] that merges adjacent values according to an arbitrary predicate same(a, b), rather than relying on PartialEq.

Behavior

• If the mesh is already compressed, this is a no-op.
• Otherwise, consumes the dense Vec<T> and replaces it with a run-length encoded (Rep::Compressed) representation, where consecutive elements satisfying same(a, b) are coalesced into a single run.

Requirements

• The predicate must be reflexive and symmetric for correctness.

This operation is lossless: expanding the compressed mesh reproduces the original sequence exactly under the same equivalence.

Trait Implementations

impl<T> Accumulator for ValueMesh<T>

where T: Eq + Clone + Named,

Accumulates sparse overlay updates into an authoritative mesh.

Lifecycle:

• Mailbox initializes State via Default (empty mesh).
• On the first update, the accumulator clones self (the template passed to open_accum_port_opts) into state. Callers pass a template such as StatusMesh::from_single(region, NotExist).
• Each overlay update is merged with right-wins semantics via merge_from_overlay, and the accumulator emits a full ValueMesh.

The accumulator’s state is a ValueMesh<T> and its updates are ValueOverlay<T> instances. On each update, the overlay’s normalized runs are merged into the mesh using ValueMesh::merge_from_overlay with right-wins semantics.

This enables incremental reduction of sparse updates across distributed reducers without materializing dense data.

type State = ValueMesh<T>

The type of the accumulated state.

type Update = ValueOverlay<T>

The type of the updates sent to the accumulator. Updates will be accumulated into type Self::State.

fn accumulate( &self, state: &mut Self::State, update: Self::Update, ) -> Result<()>

Accumulate an update into the current state.

fn reducer_spec(&self) -> Option<ReducerSpec>

The specification used to build the reducer.

impl<T> BuildFromRegion<T> for ValueMesh<T>

type Error = Error

fn build_dense(region: Region, values: Vec<T>) -> Result<Self, Self::Error>

Validates cardinality/shape and constructs a mesh.

fn build_dense_unchecked(region: Region, values: Vec<T>) -> Self

Caller guarantees correct cardinality/order; no validation.

impl<T> BuildFromRegionIndexed<T> for ValueMesh<T>

type Error = Error

fn build_indexed( region: Region, pairs: impl IntoIterator<Item = (usize, T)>, ) -> Result<Self, Self::Error>

Validates coverage and bounds, and constructs a mesh from (rank, value) pairs.

impl<T: Clone> Clone for ValueMesh<T>

fn clone(&self) -> ValueMesh<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for ValueMesh<T>

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

Formats the value using the given formatter.

impl<T> Default for ValueMesh<T>

fn default() -> Self

Returns the “default value” for a type.

impl<'de, T> Deserialize<'de> for ValueMesh<T>

where T: Deserialize<'de>,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T: Hash> Hash for ValueMesh<T>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T: PartialEq> PartialEq for ValueMesh<T>

fn eq(&self, other: &ValueMesh<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: 'static> Ranked for ValueMesh<T>

fn region(&self) -> &Region

Returns the region that defines this mesh’s shape and rank order.

fn get(&self, rank: usize) -> Option<&Self::Item>

Looks up the value at the given linearized rank.

Works transparently for both dense and compressed representations:

• In the dense case, it simply indexes into the values vector.
• In the compressed case, it performs a binary search over run boundaries to find which run contains the given rank, then returns the corresponding entry from table.

Returns None if the rank is out of bounds.

type Item = T

The type of item in this view.

impl<T: Clone + 'static> RankedSliceable for ValueMesh<T>

fn sliced(&self, region: Region) -> Self

Construct a new Ranked containing the ranks in this view that are part of region. The caller guarantees that region.is_subset(self.region()).

impl<T> Serialize for ValueMesh<T>

where T: Serialize,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<T: Eq> Eq for ValueMesh<T>

impl<T> StructuralPartialEq for ValueMesh<T>