#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
std::uint64_t	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_state (ChunkKey key) const noexcept -> ChunkState
void	set_chunk_state (ChunkKey key, ChunkState state) noexcept
auto	dirty_flags (ChunkKey key) const noexcept -> std::uint32_t
auto	active_flags (ChunkKey key) const noexcept -> std::uint32_t
auto	dirty_bounds (ChunkKey key) const noexcept -> Box3
void	mark_dirty (ChunkKey key, std::uint32_t flags, Box3 bounds) noexcept
void	mark_topology_dirty (ChunkKey key, std::uint32_t flags, Box3 bounds) noexcept
void	mark_topology_rebuilt (ChunkKey key) noexcept
void	clear_dirty (ChunkKey key, std::uint32_t flags) noexcept
auto	observe_dirty (ChunkKey key, std::uint32_t flags) const noexcept -> DirtyObservation
bool	clear_dirty_observed (ChunkKey key, DirtyObservation observed) noexcept
void	mark_active (ChunkKey key, std::uint32_t flags) noexcept
void	clear_active (ChunkKey key, std::uint32_t flags) noexcept
void	collect_dirty_chunks (std::uint32_t flags, std::vector< ChunkKey > &out) const
void	collect_active_chunks (std::uint32_t flags, std::vector< ChunkKey > &out) const
auto	dirty_chunks (std::uint32_t flags) const -> std::vector< ChunkKey >
auto	active_chunks (std::uint32_t flags) 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 nothing afterward. Instances are not internally synchronized: external synchronization is required when residency or content can mutate; concurrent reads require a stable 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 loading 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 ( std::uint32_t flags ) 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 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.

◆ collect_active_chunks()

template<typename Shape, typename Schema>

void tess::World< Shape, Schema, SparseResident >::collect_active_chunks	(	std::uint32_t	flags,
		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	(	std::uint32_t	flags,
		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 ( std::uint32_t flags ) 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 loaded page is zero-initialized and receives a new generation. Calling this for an already resident key is idempotent for data and generation. This operation does not allocate after construction.

Precondition: key is inside the bounded shape; debug builds assert otherwise.

◆ 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.

◆ 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/reload 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>

std::uint64_t 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 bytes occupied by current resident pages, excluding metadata.

◆ 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 is stable 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]

◆ 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()

◆ 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