Rodin::Geometry::AttributeIndex class
#include <Rodin/Geometry/AttributeIndex.h>

Attribute indexing for mesh polytopes.

This class stores, for each topological dimension d, an array of optional attributes indexed by polytope index. Attributes are typically used as material-region ids, boundary markers, or any other user-defined tags.

Data layout

The storage is organized by dimension:

  • For each d in [0, meshDim], a Dimension stores:
    • slots: a vector of Optional<Attribute>, indexed by polytope index.
    • mutex: a std::shared_mutex protecting accesses to slots.

Thread-Safety Model

This class provides fine-grained thread-safety at the level of individual dimensions:

  • Each dimension owns an independent std::shared_mutex.
  • Operations that read/write attributes in a given dimension synchronize using that dimension's mutex.

After initialization, concurrent calls to the following methods are safe w.r.t. each other (subject to each method's preconditions):

Structural Immutability

After initialize() completes, the number of stored dimensions (i.e. m_dimensions.size()) is immutable for the lifetime of the object. This avoids requiring a global lock on the dimension vector itself.

Therefore:

  • initialize() must be called before any concurrent access.
  • initialize() is not thread-safe and must not be called concurrently.
  • The mesh dimension must remain constant for the lifetime of the object.

Copy and Move Semantics

Copy construction:

  • Copies per-dimension storage using the source per-dimension locks.

Copy assignment:

  • Requires both objects to be initialized with the same number of dimensions.
  • Copies per dimension using the per-dimension locks.
  • Is NOT an atomic snapshot across all dimensions: a concurrent reader may observe a mix of old and new dimension contents while assignment is in progress.

Move construction / move assignment:

  • Transfer ownership of the internal dimension vector.
  • Require external synchronization: no other thread may access either object concurrently with the move.

Usage Contract

  1. Call initialize(meshDim) exactly once (or idempotently with the same value) before any concurrent use.
  2. Do not change the mesh dimension after initialization.
  3. Ensure storage exists (via resize() or via set()) before relying on reads returning non-null values.
  4. Provide external synchronization around move operations.

Constructors, destructors, conversion operators

AttributeIndex() defaulted
Default constructor.
~AttributeIndex() defaulted
Destructor.
AttributeIndex(const AttributeIndex& other)
Copy constructor.
AttributeIndex(AttributeIndex&& other) noexcept
Move constructor.

Public functions

auto operator=(const AttributeIndex& other) -> AttributeIndex&
Copy assignment operator.
auto operator=(AttributeIndex&& other) -> AttributeIndex& noexcept
Move assignment operator.
void initialize(size_t meshDim)
Initializes the index for a mesh of topological dimension meshDim.
void resize(size_t d, size_t count)
Ensures storage capacity for dimension d.
void set(const std::pair<size_t, Index>& p, const Optional<Attribute>& attr)
Sets the attribute for a polytope.
void set(const std::pair<size_t, Index>& p, size_t count, const Optional<Attribute>& attr)
Sets the attribute for a polytope assuming a known count.
void unset(const std::pair<size_t, Index>& p, size_t count)
Clears (unsets) the attribute for a polytope.
auto get(const std::pair<size_t, Index>& p, size_t count) const -> Optional<Attribute>
Gets the attribute for a polytope.
auto getAttributes(size_t d) const -> FlatSet<Attribute>
Returns the set of all attributes present in dimension d.
template<class Archive>
void serialize(Archive& ar, const unsigned int)
Serialization method for Boost.Serialization.

Function documentation

Rodin::Geometry::AttributeIndex::AttributeIndex() defaulted

Default constructor.

Constructs an uninitialized index. Call initialize() before use.

Rodin::Geometry::AttributeIndex::AttributeIndex(const AttributeIndex& other)

Copy constructor.

Copies all dimensions from other.

Thread-safety:

  • Safe if other is not being moved concurrently.
  • Copy is not a globally atomic snapshot across dimensions.

Rodin::Geometry::AttributeIndex::AttributeIndex(AttributeIndex&& other) noexcept

Move constructor.

Transfers internal dimension storage from other.

Thread-safety:

  • Requires external synchronization: no concurrent access to either object.

AttributeIndex& Rodin::Geometry::AttributeIndex::operator=(const AttributeIndex& other)

Copy assignment operator.

Copies all dimensions from other into *this.

Preconditions:

  • Both objects must already be initialized with the same mesh dimension (i.e. same m_dimensions.size()).

Thread-safety:

  • Uses per-dimension locks.
  • Not an atomic snapshot across dimensions.

AttributeIndex& Rodin::Geometry::AttributeIndex::operator=(AttributeIndex&& other) noexcept

Move assignment operator.

Transfers internal dimension storage from other into *this.

Thread-safety:

  • Requires external synchronization: no concurrent access to either object.

void Rodin::Geometry::AttributeIndex::initialize(size_t meshDim)

Initializes the index for a mesh of topological dimension meshDim.

Parameters
meshDim in Topological dimension of the mesh.

Allocates per-dimension storage for dimensions 0..meshDim.

Structural immutability:

  • After initialization, the dimension count is immutable.
  • Calling initialize again is only valid if called idempotently with the same meshDim.

Thread-safety:

  • Not thread-safe. Must be called before any concurrent access.

void Rodin::Geometry::AttributeIndex::resize(size_t d, size_t count)

Ensures storage capacity for dimension d.

Parameters
d in Dimension of polytopes.
count in Minimum number of slots to allocate.

Grows the slot vector for dimension d to at least count, filling new entries with std::nullopt.

Thread-safety:

  • Thread-safe w.r.t. other operations on the same dimension (protected by that dimension's mutex).

void Rodin::Geometry::AttributeIndex::set(const std::pair<size_t, Index>& p, const Optional<Attribute>& attr)

Sets the attribute for a polytope.

Parameters
p in Pair (dimension, index) identifying the polytope.
attr in Attribute value to assign.

If storage is insufficient, grows the slot vector to include idx and assigns attr.

Thread-safety:

  • Thread-safe (dimension-level exclusive lock).

void Rodin::Geometry::AttributeIndex::set(const std::pair<size_t, Index>& p, size_t count, const Optional<Attribute>& attr)

Sets the attribute for a polytope assuming a known count.

Parameters
p in Pair (dimension, index) identifying the polytope.
count in Expected number of polytopes in this dimension.
attr in Attribute value to assign.

Ensures the dimension has at least count slots (growing if necessary), then assigns attr at idx.

Preconditions:

  • idx < count.

Thread-safety:

  • Thread-safe (dimension-level exclusive lock).

void Rodin::Geometry::AttributeIndex::unset(const std::pair<size_t, Index>& p, size_t count)

Clears (unsets) the attribute for a polytope.

Parameters
p in Pair (dimension, index) identifying the polytope.
count in Expected number of polytopes in this dimension.

Ensures the dimension has at least count slots (growing if necessary), then resets the entry at idx to std::nullopt.

Thread-safety:

  • Thread-safe (dimension-level exclusive lock).

Optional<Attribute> Rodin::Geometry::AttributeIndex::get(const std::pair<size_t, Index>& p, size_t count) const

Gets the attribute for a polytope.

Parameters
p in Pair (dimension, index) identifying the polytope.
count in Expected number of polytopes in this dimension.
Returns The optional attribute value.

Reads the slot at idx under a shared lock.

Notes:

  • This method does not resize. If idx is out of range, returns std::nullopt.

Preconditions:

  • idx < count (debug-checked).

Thread-safety:

  • Thread-safe (dimension-level shared lock).

FlatSet<Attribute> Rodin::Geometry::AttributeIndex::getAttributes(size_t d) const

Returns the set of all attributes present in dimension d.

Parameters
d in Dimension of polytopes.
Returns A flat set of unique attribute values.

Iterates over all slots in dimension d and collects all engaged attributes.

Thread-safety:

  • Thread-safe (dimension-level shared lock).

template<class Archive>
void Rodin::Geometry::AttributeIndex::serialize(Archive& ar, const unsigned int)

Serialization method for Boost.Serialization.

Parameters
ar in/out Archive object