#include <tess/storage/sparse_world.h>

Classes
struct	ResidentChunkRef

Public Types
using	shape_type = Shape
using	schema_type = Schema
using	residency_type = SparseResident
using	page_type = ChunkPage<Shape, Schema>

Public Member Functions
	World (ResidencyConfig config)
std::size_t	capacity () const noexcept
std::size_t	byte_budget () const noexcept
std::size_t	resident_count () const noexcept
std::size_t	resident_byte_size () const noexcept
bool	is_resident (ChunkKey key) const noexcept
std::size_t	resident_slot (ChunkKey key) const noexcept
auto	resident_ref (ChunkKey key) const noexcept -> ResidentChunkRef
ResidencyGeneration	residency_generation (ChunkKey key) const noexcept
bool	valid (ResidencyHandle handle) const noexcept
std::span< const ChunkKey >	resident_chunk_keys () const noexcept
std::uint64_t	residency_fingerprint () const noexcept
ResidencyHandle	ensure_resident (ChunkKey key)
bool	touch (ChunkKey key) noexcept
bool	evict (ChunkKey key)
auto	chunk (ChunkKey key) noexcept -> page_type &
auto	chunk (ChunkKey key) const noexcept -> const page_type &
auto	try_chunk (ChunkKey key) noexcept -> page_type *
auto	try_chunk (ChunkKey key) const noexcept -> const page_type *
auto	meta (ChunkKey key) noexcept -> ChunkMeta &
auto	meta (ChunkKey key) const noexcept -> const ChunkMeta &
auto	try_meta (ChunkKey key) noexcept -> ChunkMeta *
auto	try_meta (ChunkKey key) const noexcept -> const ChunkMeta *
auto	chunk_activity (ChunkKey key) const noexcept -> ChunkActivity
auto	active_category_count (ChunkKey key) const noexcept -> std::uint32_t
auto	dirty_mask (ChunkKey key) const noexcept -> DirtyMask
auto	active_mask (ChunkKey key) const noexcept -> ActiveMask
auto	dirty_bounds (ChunkKey key) const noexcept -> Box3
void	mark_dirty (ChunkKey key, DirtyMask mask, Box3 bounds) noexcept
void	mark_content_changed (ChunkKey key) noexcept
void	mark_topology_dirty (ChunkKey key, DirtyMask mask, Box3 bounds) noexcept
void	mark_topology_rebuilt (ChunkKey key) noexcept
void	clear_dirty (ChunkKey key, DirtyMask mask) noexcept
auto	observe_dirty (ChunkKey key, DirtyMask mask) const noexcept -> DirtyObservation
bool	clear_dirty_observed (ChunkKey key, DirtyObservation observed) noexcept
void	mark_active (ChunkKey key, ActiveMask mask) noexcept
void	clear_active (ChunkKey key, ActiveMask mask) noexcept
void	collect_dirty_chunks (DirtyMask mask, std::vector< ChunkKey > &out) const
void	collect_active_chunks (ActiveMask mask, std::vector< ChunkKey > &out) const
auto	dirty_chunks (DirtyMask mask) const -> std::vector< ChunkKey >
auto	active_chunks (ActiveMask mask) const -> std::vector< ChunkKey >
auto	resolve (Coord3 coord) const noexcept -> ResolvedTile< Shape >
auto	try_resolve (Coord3 coord) const noexcept -> std::optional< ResolvedTile< Shape > >
template<typename Tag>
auto	field (Coord3 coord) noexcept -> Schema::template value_type< Tag > &
template<typename Tag>
auto	field (Coord3 coord) const noexcept -> const Schema::template value_type< Tag > &
template<typename Tag>
auto	try_field (Coord3 coord) noexcept -> Schema::template value_type< Tag > *
template<typename Tag>
auto	try_field (Coord3 coord) const noexcept -> const Schema::template value_type< Tag > *
template<typename Tag>
auto	field_span (ChunkKey key) noexcept
template<typename Tag>
auto	field_span (ChunkKey key) const noexcept

Static Public Member Functions
static constexpr bool	contains (ChunkKey key) noexcept

Static Public Attributes
static constexpr std::uint64_t	chunk_count = ShapeTraits<Shape>::chunk_count
static constexpr std::uint64_t	local_tile_count
static constexpr std::size_t	field_count = Schema::field_count
static constexpr std::size_t	page_byte_size = page_type::byte_size
static constexpr std::size_t	npos_slot = detail::ChunkDirectory::npos

Detailed Description

template<typename Shape, typename Schema>
class tess::World< Shape, Schema, SparseResident >

Byte-budgeted owner of a sparse, least-recently-used chunk set.

Only resident pages are materialized, so storage and iteration are bounded by the configured capacity rather than chunk_count. Residency is explicit: call ensure_resident() before unchecked access. Eviction resets the page before reuse and logically invalidates all pointers, references, spans, slot indices, and handles associated with that chunk. Use a ResidencyHandle when validity must be checked across residency mutations.

Construction allocates the fixed-capacity page and bookkeeping storage. Residency changes and hot accessors allocate no Tess-owned storage afterward; a field value's non-throwing default initializer may allocate. Instances are not internally synchronized: external synchronization is required when residency or content can mutate; concurrent reads require an unchanged world.

Constructor & Destructor Documentation

◆ World()

template<typename Shape, typename Schema>

tess::World< Shape, Schema, SparseResident >::World ( ResidencyConfig config )

inlineexplicit

Allocates fixed-capacity storage from config without materializing chunks.

Capacity is clamped to at least one page, even when the byte budget is smaller than page_byte_size.

Member Function Documentation

◆ active_chunks()

template<typename Shape, typename Schema>

auto tess::World< Shape, Schema, SparseResident >::active_chunks ( ActiveMask mask ) const -> std::vector< ChunkKey >

inlinenodiscard

Returns matching resident active keys in a newly allocated vector.

◆ byte_budget()

template<typename Shape, typename Schema>

std::size_t tess::World< Shape, Schema, SparseResident >::byte_budget ( ) const

inlinenodiscardnoexcept

Returns the requested Tess-owned inline page-storage budget in bytes.

◆ capacity()

template<typename Shape, typename Schema>

std::size_t tess::World< Shape, Schema, SparseResident >::capacity ( ) const

inlinenodiscardnoexcept

Returns the maximum number of simultaneously resident chunks.

◆ chunk() [1/2]

template<typename Shape, typename Schema>

auto tess::World< Shape, Schema, SparseResident >::chunk ( ChunkKey key ) const -> const page_type &

inlinenodiscardnoexcept

Const overload of chunk() with the same residency precondition.

◆ chunk() [2/2]

template<typename Shape, typename Schema>

auto tess::World< Shape, Schema, SparseResident >::chunk ( ChunkKey key ) -> page_type &

inlinenodiscardnoexcept

Returns a resident page without runtime error recovery.

Precondition: key is resident; debug builds assert this precondition.

◆ clear_dirty_observed()

template<typename Shape, typename Schema>

bool tess::World< Shape, Schema, SparseResident >::clear_dirty_observed	(	ChunkKey	key,
		DirtyObservation	observed )

inlinenoexcept

Clears the observed mask when the observation is still current.

Refuses an observation from an earlier residency interval: rematerializing a chunk restarts its content version, so that value alone cannot distinguish a mark this observation saw from one made after an eviction.

◆ collect_active_chunks()

template<typename Shape, typename Schema>

void tess::World< Shape, Schema, SparseResident >::collect_active_chunks	(	ActiveMask	mask,
		std::vector< ChunkKey > &	out ) const

inline

Appends matching resident active keys to caller-owned storage.

The scan and allocation contract matches collect_dirty_chunks().

◆ collect_dirty_chunks()

template<typename Shape, typename Schema>

void tess::World< Shape, Schema, SparseResident >::collect_dirty_chunks	(	DirtyMask	mask,
		std::vector< ChunkKey > &	out ) const

inline

Appends matching resident dirty keys to caller-owned storage.

The scan is O(resident_count) and allocates only if out grows.

◆ contains()

template<typename Shape, typename Schema>

constexpr bool tess::World< Shape, Schema, SparseResident >::contains ( ChunkKey key )

inlinestaticnodiscardconstexprnoexcept

Returns whether key is inside the bounded shape.

◆ dirty_chunks()

template<typename Shape, typename Schema>

auto tess::World< Shape, Schema, SparseResident >::dirty_chunks ( DirtyMask mask ) const -> std::vector< ChunkKey >

inlinenodiscard

Returns matching resident dirty keys in a newly allocated vector.

◆ ensure_resident()

template<typename Shape, typename Schema>

ResidencyHandle tess::World< Shape, Schema, SparseResident >::ensure_resident ( ChunkKey key )

inline

Makes an in-bounds key resident and marks it most-recently used.

When full, the least-recently-used chunk is evicted, invalidating its handles and borrowed storage. A newly materialized page is value-initialized and receives a new generation. Calling this for an already resident key is idempotent for data and generation. Tess performs no dynamic allocation after construction; a field value's nothrow default initialization may manage its own allocation while resetting a reused page.

Returns an invalid handle for a key outside the bounded shape, matching try_chunk(), try_meta() and residency_generation(). This is the only residency entry point with no checked counterpart, so it is total rather than asserted: the directory's direct-slot mode indexes its slot table by the key, and an out-of-range key previously wrote past the end wherever assertions were compiled out.

◆ evict()

template<typename Shape, typename Schema>

bool tess::World< Shape, Schema, SparseResident >::evict ( ChunkKey key )

inline

Evicts a key immediately, or returns false if it is not resident.

Success invalidates the chunk's handle, slot, page and metadata borrows, field references, and resident-key views.

◆ field() [1/2]

template<typename Shape, typename Schema>

template<typename Tag>

auto tess::World< Shape, Schema, SparseResident >::field ( Coord3 coord ) const -> const Schema::template value_type< Tag > &

inlinenodiscardnoexcept

Const overload of field() with the same preconditions.

◆ field() [2/2]

template<typename Shape, typename Schema>

template<typename Tag>

auto tess::World< Shape, Schema, SparseResident >::field ( Coord3 coord ) -> Schema::template value_type< Tag > &

inlinenodiscardnoexcept

Returns mutable field storage without runtime error recovery.

Precondition: coord is in bounds, its chunk is resident, and Tag is in schema.

◆ field_span() [1/2]

template<typename Shape, typename Schema>

template<typename Tag>

auto tess::World< Shape, Schema, SparseResident >::field_span ( ChunkKey key ) const

inlinenodiscardnoexcept

Const overload of field_span() with the same lifetime contract.

◆ field_span() [2/2]

template<typename Shape, typename Schema>

template<typename Tag>

auto tess::World< Shape, Schema, SparseResident >::field_span ( ChunkKey key )

inlinenodiscardnoexcept

Returns a resident chunk's contiguous field column without allocating.

Precondition: key is resident and Tag belongs to the schema.

◆ is_resident()

template<typename Shape, typename Schema>

bool tess::World< Shape, Schema, SparseResident >::is_resident ( ChunkKey key ) const

inlinenodiscardnoexcept

Returns whether an in-bounds key currently has a resident page.

◆ mark_content_changed()

template<typename Shape, typename Schema>

void tess::World< Shape, Schema, SparseResident >::mark_content_changed ( ChunkKey key )

inlinenoexcept

Advances the resident chunk's content version without marking dirty work.

Use this after a content write that must invalidate version-keyed derived state but does not concern any dirty-mask consumer. This changes only the content version. Use mark_dirty for dirty-metadata consumers, mark_topology_dirty when topology freshness must change, and the schedule's notification protocol when an OnDirty task must run. An intervening call also makes an earlier DirtyObservation stale.

The key must be resident, matching the precondition of mark_dirty.

◆ meta()

template<typename Shape, typename Schema>

auto tess::World< Shape, Schema, SparseResident >::meta ( ChunkKey key ) -> ChunkMeta &

inlinenodiscardnoexcept

Returns resident metadata without runtime error recovery.

Precondition: key is resident; debug builds assert this precondition.

◆ residency_fingerprint()

template<typename Shape, typename Schema>

std::uint64_t tess::World< Shape, Schema, SparseResident >::residency_fingerprint ( ) const

inlinenodiscardnoexcept

Returns an order-independent fingerprint of resident content and slots.

It incorporates eviction/rematerialization generations, content versions, keys, and slot bindings, so consumers can probabilistically invalidate artifacts indexed by resident slot. Computing it is O(resident_count), allocation-free, and never visits non-resident chunks. It is not a persistent identifier or a collision-proof digest.

◆ residency_generation()

template<typename Shape, typename Schema>

ResidencyGeneration tess::World< Shape, Schema, SparseResident >::residency_generation ( ChunkKey key ) const

inlinenodiscardnoexcept

Returns a resident chunk's world-monotonic generation, or zero if absent.

◆ resident_byte_size()

template<typename Shape, typename Schema>

std::size_t tess::World< Shape, Schema, SparseResident >::resident_byte_size ( ) const

inlinenodiscardnoexcept

Returns resident inline page bytes, excluding metadata and value-owned dynamic or referenced storage.

◆ resident_chunk_keys()

template<typename Shape, typename Schema>

std::span< const ChunkKey > tess::World< Shape, Schema, SparseResident >::resident_chunk_keys ( ) const

inlinenodiscardnoexcept

Borrows the current resident-key set without allocating.

Order is unspecified. Any ensure_resident() or evict() call invalidates the span's contents and iterators; copy keys when a snapshot is required.

◆ resident_count()

template<typename Shape, typename Schema>

std::size_t tess::World< Shape, Schema, SparseResident >::resident_count ( ) const

inlinenodiscardnoexcept

Returns the current number of resident chunks.

◆ resident_ref()

template<typename Shape, typename Schema>

auto tess::World< Shape, Schema, SparseResident >::resident_ref ( ChunkKey key ) const -> ResidentChunkRef

inlinenodiscardnoexcept

Returns slot, generation, and metadata with one directory lookup.

For a missing chunk, meta is null, generation is zero, and slot is npos_slot. The metadata pointer is valid only while the chunk remains resident and no non-const world operation runs concurrently.

◆ resident_slot()

template<typename Shape, typename Schema>

std::size_t tess::World< Shape, Schema, SparseResident >::resident_slot ( ChunkKey key ) const

inlinenodiscardnoexcept

Returns the fixed slot backing a resident chunk, or npos_slot.

The slot identity remains valid only while the chunk stays resident. A traversal may index by slot while holding the world logically const, but must discard that indexing before any residency mutation.

◆ resolve()

template<typename Shape, typename Schema>

auto tess::World< Shape, Schema, SparseResident >::resolve ( Coord3 coord ) const -> ResolvedTile< Shape >

inlinenodiscardnoexcept

Resolves an in-bounds coordinate without checking residency.

Precondition: coord is inside the world; debug builds assert this precondition.

◆ touch()

template<typename Shape, typename Schema>

bool tess::World< Shape, Schema, SparseResident >::touch ( ChunkKey key )

inlinenoexcept

Marks a resident key most-recently used, or returns false if absent.

◆ try_chunk() [1/2]

template<typename Shape, typename Schema>

auto tess::World< Shape, Schema, SparseResident >::try_chunk ( ChunkKey key ) const -> const page_type *

inlinenodiscardnoexcept

Const overload of try_chunk() with the same checked behavior.

◆ try_chunk() [2/2]

template<typename Shape, typename Schema>

auto tess::World< Shape, Schema, SparseResident >::try_chunk ( ChunkKey key ) -> page_type *

inlinenodiscardnoexcept

Returns a resident page, or null for missing or out-of-bounds keys.

◆ try_field() [1/2]

template<typename Shape, typename Schema>

template<typename Tag>

auto tess::World< Shape, Schema, SparseResident >::try_field ( Coord3 coord ) const -> const Schema::template value_type< Tag > *

inlinenodiscardnoexcept

Const overload of try_field() with the same checked behavior.

◆ try_field() [2/2]

template<typename Shape, typename Schema>

template<typename Tag>

auto tess::World< Shape, Schema, SparseResident >::try_field ( Coord3 coord ) -> Schema::template value_type< Tag > *

inlinenodiscardnoexcept

Returns mutable field storage, or null if out of bounds or non-resident. Tag must belong to the schema.

◆ try_meta()

template<typename Shape, typename Schema>

auto tess::World< Shape, Schema, SparseResident >::try_meta ( ChunkKey key ) -> ChunkMeta *

inlinenodiscardnoexcept

Returns resident metadata, or null when the key is not resident.

◆ try_resolve()

template<typename Shape, typename Schema>

auto tess::World< Shape, Schema, SparseResident >::try_resolve ( Coord3 coord ) const -> std::optional< ResolvedTile< Shape > >

inlinenodiscardnoexcept

Returns a resolved tile, or std::nullopt when out of bounds.

A successful result does not imply that the chunk is resident.

◆ valid()

template<typename Shape, typename Schema>

bool tess::World< Shape, Schema, SparseResident >::valid ( ResidencyHandle handle ) const

inlinenodiscardnoexcept

Returns whether a handle still names its original residency interval.

Member Data Documentation

◆ local_tile_count

template<typename Shape, typename Schema>

std::uint64_t tess::World< Shape, Schema, SparseResident >::local_tile_count

staticconstexpr

Initial value:

=

ShapeTraits<Shape>::local_tile_count

◆ npos_slot

template<typename Shape, typename Schema>

std::size_t tess::World< Shape, Schema, SparseResident >::npos_slot = detail::ChunkDirectory::npos

staticconstexpr

Sentinel returned by resident_slot() for a non-resident chunk.

The documentation for this class was generated from the following file:

include/tess/storage/sparse_world.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ World()

Member Function Documentation

◆ active_chunks()

◆ byte_budget()

◆ capacity()

◆ chunk() [1/2]

◆ chunk() [2/2]

◆ clear_dirty_observed()

◆ collect_active_chunks()

◆ collect_dirty_chunks()

◆ contains()

◆ dirty_chunks()

◆ ensure_resident()

◆ evict()

◆ field() [1/2]

◆ field() [2/2]

◆ field_span() [1/2]

◆ field_span() [2/2]

◆ is_resident()

◆ mark_content_changed()

◆ meta()

◆ residency_fingerprint()

◆ residency_generation()

◆ resident_byte_size()

◆ resident_chunk_keys()

◆ resident_count()

◆ resident_ref()

◆ resident_slot()

◆ resolve()

◆ touch()

◆ try_chunk() [1/2]

◆ try_chunk() [2/2]

◆ try_field() [1/2]

◆ try_field() [2/2]

◆ try_meta()

◆ try_resolve()

◆ valid()

Member Data Documentation

◆ local_tile_count

◆ npos_slot