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.

See VM-1 in module doc.

Implementations

impl<T> ValueMesh<T>

pub fn empty() -> ValueMesh<T>

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.

pub fn new( region: Region, ranks: Vec<T>, ) -> Result<ValueMesh<T>, ValueMeshError>

Creates a new ValueMesh for region with exactly one value per rank.

Invariants

This constructor validates that the number of provided values (ranks.len()) matches the region’s cardinality (region.num_ranks()). A value mesh must be complete: every rank in region has a corresponding T.

Errors

Returns ValueMeshError::InvalidRankCardinality if ranks.len() != region.num_ranks().

impl<T> ValueMesh<T>

where T: Clone,

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

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> ValueMesh<T>

where T: Clone + Default,

pub fn from_default(region: Region) -> ValueMesh<T>

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

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

impl<T> ValueMesh<T>

where T: Eq + Hash,

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

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<ValueMesh<T>, ValueMeshError>

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> ValueMesh<F>

where F: Future,

pub async fn join(self) -> ValueMesh<<F as Future>::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> ValueMesh<T>

where T: 'static,

pub fn get_by_base_rank(&self, base_rank: usize) -> Option<&T>

Look up the value at base_rank — the rank in the base space of this mesh’s region, not the linearized ordinal that view::Ranked::get takes.

For a full region the two coincide; for a sliced sub-region they differ — e.g. a row slice over base ranks {2, 3, 4, 5} has ordinals {0, 1, 2, 3}. This resolves base_rank through the region’s geometry (point_of_base_rank → ordinal) and then indexes, so callers address by the stable base-space rank and never touch the ordinal.

Returns None if base_rank is not contained in this region.

impl<T> ValueMesh<T>

where T: PartialEq,

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> ValueMesh<T>

where T: Clone + Eq,

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 <ValueMesh<T> as Accumulator>::State, update: <ValueMesh<T> as Accumulator>::Update, ) -> Result<(), Error>

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 = ValueMeshError

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

Validates cardinality/shape and constructs a mesh.

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

Caller guarantees correct cardinality/order; no validation.

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

type Error = ValueMeshError

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

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

impl<T> Clone for ValueMesh<T>

where T: Clone,

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 for ValueMesh<T>

where T: Debug,

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

Formats the value using the given formatter.

impl<T> Default for ValueMesh<T>

fn default() -> ValueMesh<T>

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<ValueMesh<T>, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T> Hash for ValueMesh<T>

where T: Hash,

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

where __H: Hasher,

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 for ValueMesh<T>

where T: PartialEq,

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> Ranked for ValueMesh<T>

where T: 'static,

fn region(&self) -> &Region

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

fn get(&self, rank: usize) -> Option<&<ValueMesh<T> as Ranked>::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> RankedSliceable for ValueMesh<T>

where T: Clone + 'static,

fn sliced(&self, region: Region) -> ValueMesh<T>

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 as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<T> Eq for ValueMesh<T>

where T: Eq,

impl<T> StructuralPartialEq for ValueMesh<T>