Paged implicit list declaration. More...

#include <ilist.h>

Public Types
using	value_type = TListItem
	Stored payload type.

using	reference = TListItem &
	Mutable payload reference.

using	const_reference = const TListItem &
	Immutable payload reference.

using	pointer = TListItem *
	Mutable payload pointer.

using	const_pointer = const TListItem *
	Immutable payload pointer.

using	difference_type = std::ptrdiff_t
	Type used for iterator distances.

using	size_type = uint32_t
	Type used for slot indices and sizes.

using	iterator_category = core::forward_iterator_tag
	Iterator category tag.

using	iterator = paged_ilist_iterator< paged_ilist, false >
	Mutable forward iterator over live payloads.

using	const_iterator = paged_ilist_iterator< paged_ilist, true >
	Immutable forward iterator over live payloads.

Public Member Functions
	paged_ilist (const paged_ilist &)=delete

paged_ilist &	operator= (const paged_ilist &)=delete

	paged_ilist (paged_ilist &&other) noexcept
	Move-constructs a paged list and leaves the source empty.

paged_ilist &	operator= (paged_ilist &&other) noexcept
	Move-assigns a paged list and leaves the source empty.

GAIA_NODISCARD pointer	data () noexcept
	Reports that paged storage is not globally contiguous.

GAIA_NODISCARD const_pointer	data () const noexcept
	Reports that paged storage is not globally contiguous.

GAIA_NODISCARD bool	has (size_type index) const noexcept
	Checks whether a slot contains a live payload.

GAIA_NODISCARD bool	has (TItemHandle handle) const noexcept
	Checks whether a handle identifies its current live payload.

GAIA_NODISCARD TItemHandle	handle (size_type index) const noexcept
	Returns the handle metadata stored for a slot.

GAIA_NODISCARD uint32_t	generation (size_type index) const noexcept
	Returns a slot's generation.

GAIA_NODISCARD uint32_t	next_free (size_type index) const noexcept
	Returns the free-list link stored for a slot.

GAIA_NODISCARD reference	operator[] (size_type index)
	Returns a live payload by slot index.

GAIA_NODISCARD const_reference	operator[] (size_type index) const
	Returns a live payload by slot index.

void	clear ()
	Destroys all live payloads, releases all pages, and resets slot metadata.

GAIA_NODISCARD size_type	get_next_free_item () const noexcept
	Returns the free-list head.

GAIA_NODISCARD size_type	get_free_items () const noexcept
	Returns the number of recyclable slots.

GAIA_NODISCARD size_type	item_count () const noexcept
	Returns the number of live payloads.

GAIA_NODISCARD size_type	size () const noexcept
	Returns the total number of addressable slots in use.

GAIA_NODISCARD bool	empty () const noexcept
	Checks whether no slots are in use.

GAIA_NODISCARD size_type	capacity () const noexcept
	Returns the slot capacity represented by the page table.

GAIA_NODISCARD iterator	begin () noexcept
	Returns an iterator over live payload objects only.

GAIA_NODISCARD const_iterator	begin () const noexcept
	Returns an iterator over live payload objects only.

GAIA_NODISCARD const_iterator	cbegin () const noexcept
	Returns an iterator over live payload objects only.

GAIA_NODISCARD iterator	end () noexcept
	Returns the mutable end sentinel.

GAIA_NODISCARD const_iterator	end () const noexcept
	Returns the immutable end sentinel.

GAIA_NODISCARD const_iterator	cend () const noexcept
	Returns the immutable end sentinel.

void	reserve (size_type cap)
	Reserves page-table capacity for at least cap slots.

void	reserve_slot_table (size_type cap)
	Ensures the page pointer table can address cap slots without resizing later.

GAIA_NODISCARD reference	live_unsafe (size_type index)
	Returns a live payload slot without consulting list-wide size metadata.

GAIA_NODISCARD const_reference	live_unsafe (size_type index) const
	Returns a live payload slot without consulting list-wide size metadata.

GAIA_NODISCARD reference	payload_unsafe (size_type index)
	Returns a constructed payload slot without consulting shared liveness metadata.

GAIA_NODISCARD const_reference	payload_unsafe (size_type index) const
	Returns a constructed payload slot without consulting shared liveness metadata.

GAIA_NODISCARD pointer	try_get (size_type index) noexcept
	Attempts to access a live payload.

GAIA_NODISCARD const_pointer	try_get (size_type index) const noexcept
	Attempts to access a live payload.

void	add_live (TListItem &&item)
	Restores a live slot with a preassigned id/generation.

void	add_free (TItemHandle handle, uint32_t nextFreeIdx)
	Restores a free slot with a preassigned id/generation and free-list link.

void	add_free (size_type index, uint32_t generation, uint32_t nextFreeIdx)
	Restores a free slot with a preassigned id/generation and free-list link.

GAIA_NODISCARD TItemHandle	alloc (void *ctx)
	Allocates a new item in the list.

GAIA_NODISCARD TItemHandle	alloc ()
	Allocates a new item in the list.

void	free (TItemHandle handle)
	Frees a live item and destroys its payload immediately.

void	free_keep_live (TItemHandle handle)
	Frees a handle while keeping the payload alive until slot reuse or clear().

void	validate () const
	Verifies that the implicit free-list links are well formed.

Static Public Member Functions
static GAIA_NODISCARD constexpr size_type	page_capacity () noexcept
	Returns the compile-time number of payload slots stored in one page.

static GAIA_NODISCARD constexpr size_type	page_count_for_capacity (size_type slotCnt) noexcept
	Calculates how many pages are needed to address slotCnt slots.

Public Attributes
size_type	m_nextFreeIdx = (size_type)-1
	Head of the implicit free-list, or TItemHandle::IdMask when no slots are free.

size_type	m_freeItems = 0
	Number of slots currently linked through the implicit free-list.

Detailed Description

template<typename TListItem, typename TItemHandle, uint32_t MaxPages>
struct gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >

Paged implicit list declaration.

Paged implicit list with page-local slot metadata and lazily allocated page payloads. Live slots own payload objects. Dead slots keep only handle and free-list metadata, which allows payload storage for fully empty pages to be released.

Template Parameters

TListItem	Payload type stored in the list.
TItemHandle	External handle type used to address slots.
MaxPages	Maximum number of addressable pages. A value of 0 keeps the page table dynamic. A non-zero value embeds a fixed page table in the container so page-table storage never reallocates after construction.
TListItem	Payload type stored in the list. Must expose slot metadata through ilist_item_traits<TListItem> and ilist-compatible create()/handle() helpers.
TItemHandle	External handle type exposing id(), gen(), and IdMask.
MaxPages	Maximum number of page pointers kept by the container. Use 0 for dynamic growth through darray. Use a non-zero value when the maximum slot count is known and pointer-table relocation must be impossible.

Constructor & Destructor Documentation

◆ paged_ilist()

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::paged_ilist ( paged_ilist< TListItem, TItemHandle, MaxPages > && other )

inlinenoexcept

Move-constructs a paged list and leaves the source empty.

Parameters

other Paged list whose pages are transferred.

Member Function Documentation

◆ add_free() [1/2]

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

void gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::add_free	(	size_type	index,
		uint32_t	generation,
		uint32_t	nextFreeIdx
	)

inline

Restores a free slot with a preassigned id/generation and free-list link.

Parameters

index	Slot index to restore.
generation	Generation to store in the restored handle.
nextFreeIdx	Next slot in the implicit free-list, or TItemHandle::IdMask.

◆ add_free() [2/2]

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

void gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::add_free	(	TItemHandle	handle,
		uint32_t	nextFreeIdx
	)

inline

Restores a free slot with a preassigned id/generation and free-list link.

Parameters

handle	Handle metadata to restore for the free slot.
nextFreeIdx	Next slot in the implicit free-list, or TItemHandle::IdMask.

◆ add_live()

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

void gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::add_live ( TListItem && item )

inline

Restores a live slot with a preassigned id/generation.

Parameters

item	Payload carrying the slot index and generation to restore.

Note: Existing live payload at the same slot is destroyed first. Existing free-list metadata for that slot is cleared because the restored slot becomes live.

◆ alloc() [1/2]

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD TItemHandle gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::alloc ( )

inline

Allocates a new item in the list.

Returns: Handle of the allocated item.

Note: Reused slots keep their generation and clear any keep-live payload before construction.

◆ alloc() [2/2]

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD TItemHandle gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::alloc ( void * ctx )

inline

Allocates a new item in the list.

Parameters

ctx	Creation context forwarded to TListItem::create().

Returns: Handle of the allocated item.

Note: Reused slots keep their generation and clear any keep-live payload before construction.

◆ begin() [1/2]

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD const_iterator gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::begin ( ) const

inlinenoexcept

Returns an iterator over live payload objects only.

Returns: Immutable iterator to the first live payload.

◆ begin() [2/2]

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD iterator gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::begin ( )

inlinenoexcept

Returns an iterator over live payload objects only.

Returns: Mutable iterator to the first live payload.

◆ capacity()

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD size_type gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::capacity ( ) const

inlinenoexcept

Returns the slot capacity represented by the page table.

Returns: Maximum addressable slots without growing the page table.

◆ cbegin()

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD const_iterator gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::cbegin ( ) const

inlinenoexcept

Returns an iterator over live payload objects only.

Returns: Immutable iterator to the first live payload.

◆ cend()

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD const_iterator gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::cend ( ) const

inlinenoexcept

Returns the immutable end sentinel.

Returns: Iterator following the last slot.

◆ data() [1/2]

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD const_pointer gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::data ( ) const

inlinenoexcept

Reports that paged storage is not globally contiguous.

Returns: Always nullptr. Access payloads by slot or iterator instead.

◆ data() [2/2]

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD pointer gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::data ( )

inlinenoexcept

Reports that paged storage is not globally contiguous.

Returns: Always nullptr. Access payloads by slot or iterator instead.

◆ empty()

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD bool gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::empty ( ) const

inlinenoexcept

Checks whether no slots are in use.

Returns: True when size() is zero. False otherwise.

◆ end() [1/2]

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD const_iterator gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::end ( ) const

inlinenoexcept

Returns the immutable end sentinel.

Returns: Iterator following the last slot.

◆ end() [2/2]

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD iterator gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::end ( )

inlinenoexcept

Returns the mutable end sentinel.

Returns: Iterator following the last slot.

◆ free()

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

void gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::free ( TItemHandle handle )

inline

Frees a live item and destroys its payload immediately.

Parameters

handle Handle identifying the item to release.

Note: The slot generation is incremented and the slot is linked into the implicit free-list.

◆ free_keep_live()

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

void gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::free_keep_live ( TItemHandle handle )

inline

Frees a handle while keeping the payload alive until slot reuse or clear().

Parameters

handle Handle identifying the item to release.

Warning: The slot becomes part of the free-list even though its payload remains alive. Iteration and has(handle) treat it as released because the generation changes. Callers that inspect the payload afterward must use payload_unsafe() and must guarantee the slot has not been reused.

Note: This is intended for systems that need released-state inspectability without moving page storage while other background work may still observe job data.

◆ generation()

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD uint32_t gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::generation ( size_type index ) const

inlinenoexcept

Returns a slot's generation.

Parameters

index Valid slot index.

Returns: Generation encoded in the stored handle.

◆ get_free_items()

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD size_type gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::get_free_items ( ) const

inlinenoexcept

Returns the number of recyclable slots.

Returns: Number of slots linked through the free list.

◆ get_next_free_item()

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD size_type gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::get_next_free_item ( ) const

inlinenoexcept

Returns the free-list head.

Returns: Index of the next recyclable slot, or the handle type's invalid id.

◆ handle()

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD TItemHandle gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::handle ( size_type index ) const

inlinenoexcept

Returns the handle metadata stored for a slot.

Parameters

index Valid slot index.

Returns: Stored handle.

◆ has() [1/2]

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD bool gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::has ( size_type index ) const

inlinenoexcept

Checks whether a slot contains a live payload.

Parameters

index Slot index to inspect.

Returns: True when index identifies a live payload. False otherwise.

◆ has() [2/2]

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD bool gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::has ( TItemHandle handle ) const

inlinenoexcept

Checks whether a handle identifies its current live payload.

Parameters

handle Handle to validate.

Returns: True when the slot is live and its stored handle equals handle.

◆ item_count()

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD size_type gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::item_count ( ) const

inlinenoexcept

Returns the number of live payloads.

Returns: Total slot count minus recyclable slot count.

◆ live_unsafe() [1/2]

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD reference gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::live_unsafe ( size_type index )

inline

Returns a live payload slot without consulting list-wide size metadata.

Parameters

index Slot index to access.

Returns: Mutable reference to the live payload at index.

Warning: This bypasses index < size() checks. Use only when the caller already validated the handle/index through stronger external synchronization.

◆ live_unsafe() [2/2]

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD const_reference gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::live_unsafe ( size_type index ) const

inline

Returns a live payload slot without consulting list-wide size metadata.

Parameters

index Slot index to access.

Returns: Immutable reference to the live payload at index.

Warning: This bypasses index < size() checks. Use only when the caller already validated the handle/index through stronger external synchronization.

◆ next_free()

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD uint32_t gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::next_free ( size_type index ) const

inlinenoexcept

Returns the free-list link stored for a slot.

Parameters

index Valid slot index.

Returns: Next free slot index or the handle type's invalid id.

◆ operator=()

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

paged_ilist & gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::operator= ( paged_ilist< TListItem, TItemHandle, MaxPages > && other )

inlinenoexcept

Move-assigns a paged list and leaves the source empty.

Parameters

other Paged list whose pages are transferred.

Returns: This paged list.

◆ operator[]() [1/2]

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD reference gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::operator[] ( size_type index )

inline

Returns a live payload by slot index.

Parameters

index Live slot index.

Returns: Mutable reference to the payload.

◆ operator[]() [2/2]

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD const_reference gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::operator[] ( size_type index ) const

inline

Returns a live payload by slot index.

Parameters

index Live slot index.

Returns: Immutable reference to the payload.

◆ page_capacity()

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

static GAIA_NODISCARD constexpr size_type gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::page_capacity ( )

inlinestaticconstexprnoexcept

Returns the compile-time number of payload slots stored in one page.

Returns: Number of slots per page.

◆ page_count_for_capacity()

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

static GAIA_NODISCARD constexpr size_type gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::page_count_for_capacity ( size_type slotCnt )

inlinestaticconstexprnoexcept

Calculates how many pages are needed to address slotCnt slots.

Parameters

slotCnt Number of slots that must be addressable.

Returns: Number of pages required for slotCnt.

◆ payload_unsafe() [1/2]

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD reference gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::payload_unsafe ( size_type index )

inline

Returns a constructed payload slot without consulting shared liveness metadata.

Parameters

index Slot index to access.

Returns: Mutable reference to the payload at index.

Warning: The caller must guarantee that the page and payload are constructed and remain alive.

◆ payload_unsafe() [2/2]

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD const_reference gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::payload_unsafe ( size_type index ) const

inline

Returns a constructed payload slot without consulting shared liveness metadata.

Parameters

index Slot index to access.

Returns: Immutable reference to the payload at index.

Warning: The caller must guarantee that the page and payload are constructed and remain alive.

◆ reserve()

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

void gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::reserve ( size_type cap )

inline

Reserves page-table capacity for at least cap slots.

Parameters

cap	Number of slots that should be addressable without growing the page table.

Note: In fixed-page-table mode this only verifies that cap fits into MaxPages. Payload pages remain lazily allocated in both modes.

◆ reserve_slot_table()

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

void gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::reserve_slot_table ( size_type cap )

inline

Ensures the page pointer table can address cap slots without resizing later.

Parameters

cap	Number of slots that must be addressable.

Note: This is stronger than reserve() in dynamic mode because it resizes the pointer table to contain null page entries. It does not allocate payload pages.; In fixed-page-table mode this only verifies that cap fits into MaxPages.

◆ size()

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD size_type gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::size ( ) const

inlinenoexcept

Returns the total number of addressable slots in use.

Returns: Live and recyclable slot count.

◆ try_get() [1/2]

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD const_pointer gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::try_get ( size_type index ) const

inlinenoexcept

Attempts to access a live payload.

Parameters

index Slot index to inspect.

Returns: Const pointer to the live payload, or nullptr when the slot is not live.

◆ try_get() [2/2]

template<typename TListItem , typename TItemHandle , uint32_t MaxPages>

GAIA_NODISCARD pointer gaia::cnt::paged_ilist< TListItem, TItemHandle, MaxPages >::try_get ( size_type index )

inlinenoexcept

Attempts to access a live payload.

Parameters

index Slot index to inspect.

Returns: Pointer to the live payload, or nullptr when the slot is not live.

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

/home/runner/work/gaia-ecs/gaia-ecs/include/gaia/cnt/ilist.h

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ paged_ilist()

Member Function Documentation

◆ add_free() [1/2]

◆ add_free() [2/2]

◆ add_live()

◆ alloc() [1/2]

◆ alloc() [2/2]

◆ begin() [1/2]

◆ begin() [2/2]

◆ capacity()

◆ cbegin()

◆ cend()

◆ data() [1/2]

◆ data() [2/2]

◆ empty()

◆ end() [1/2]

◆ end() [2/2]

◆ free()

◆ free_keep_live()

◆ generation()

◆ get_free_items()

◆ get_next_free_item()

◆ handle()

◆ has() [1/2]

◆ has() [2/2]

◆ item_count()

◆ live_unsafe() [1/2]

◆ live_unsafe() [2/2]

◆ next_free()

◆ operator=()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ page_capacity()

◆ page_count_for_capacity()

◆ payload_unsafe() [1/2]

◆ payload_unsafe() [2/2]

◆ reserve()

◆ reserve_slot_table()

◆ size()

◆ try_get() [1/2]

◆ try_get() [2/2]