AttributeIndex
Attribute indexing for mesh polytopes.
Defined in Rodin/Geometry/AttributeIndex.h
class AttributeIndex;
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
din [0, meshDim], aDimensionstores:slots:stable attribute slots indexed by polytope index.mutex:a mutex protecting storage growth.
Thread-Safety Model
This class provides fine-grained thread-safety at the level of individual dimensions. Slot values and the published storage extent are atomic, so repeated reads require no lock. Storage growth and writes are serialized per dimension.
After initialization, concurrent calls to the following methods are safe w.r.t. each other (subject to each method's preconditions):
- resize(size_
t,size_ t) set(const std::pair<size_t,Index>&, Attribute)set(const std::pair<size_t,Index>&, size_t, Attribute)- pair<size_
t,Index>&,size_ t) - pair<size_
t,Index>&,size_ t) const - getAttributes(size_
t) const
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 while serializing source storage growth.
Copy assignment:
- Requires both objects to be initialized with the same number of dimensions.
- Copies per dimension while serializing storage growth.
- 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
- Call initialize() exactly once (or idempotently with the same value) before any concurrent use.
- Do not change the mesh dimension after initialization.
- Ensure storage exists (via resize() or via set()) before relying on reads returning non-null values.
- 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 version)
- Serialization method for Boost.Serialization.
Function documentation
AttributeIndex() defaulted
Default constructor.
Constructs an uninitialized index. Call initialize() before use.
AttributeIndex(const AttributeIndex& other)
Copy constructor.
| Parameters | |
|---|---|
| other | Object to copy from. |
Copies all dimensions from other.
AttributeIndex(AttributeIndex&& other) noexcept
Move constructor.
| Parameters | |
|---|---|
| other | Object to move from. |
Transfers internal dimension storage from other.
AttributeIndex& operator=(const AttributeIndex& other)
Copy assignment operator.
| Parameters | |
|---|---|
| other | Object to copy from. |
| Returns | Reference to this object after the operation. |
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()).
AttributeIndex& operator=(AttributeIndex&& other) noexcept
Move assignment operator.
| Parameters | |
|---|---|
| other | Object to move from. |
| Returns | Reference to this object after the operation. |
Transfers internal dimension storage from other into *this.
void 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.
void 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.
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.
| 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.
void 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.
Optional<Attribute> 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 an atomic snapshot of the slot at idx.
Notes:
- This method does not resize. If
idxis out of range, returnsstd::nullopt.
Preconditions:
idx<count(debug-checked).
FlatSet<Attribute> 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.
template<class Archive>
void serialize(Archive& ar,
const unsigned int version)
Serialization method for Boost.Serialization.
| Parameters | |
|---|---|
| ar in/out | Archive object |
| version | Boost.Serialization class version; unused by this implementation. |