Paged implicit list declaration. More...

#include <ilist.h>

Public Types
using	value_type = TListItem

using	reference = TListItem &

using	const_reference = const TListItem &

using	pointer = TListItem *

using	const_pointer = const TListItem *

using	difference_type = std::ptrdiff_t

using	size_type = uint32_t

using	iterator_category = core::forward_iterator_tag

using	iterator = paged_ilist_iterator< paged_ilist, false >

using	const_iterator = paged_ilist_iterator< paged_ilist, true >

Public Member Functions
	paged_ilist (const paged_ilist &)=delete

paged_ilist &	operator= (const paged_ilist &)=delete

	paged_ilist (paged_ilist &&other) noexcept

paged_ilist &	operator= (paged_ilist &&other) noexcept

GAIA_NODISCARD pointer	data () noexcept

GAIA_NODISCARD const_pointer	data () const noexcept

GAIA_NODISCARD bool	has (size_type index) const noexcept

GAIA_NODISCARD bool	has (TItemHandle handle) const noexcept

GAIA_NODISCARD TItemHandle	handle (size_type index) const noexcept

GAIA_NODISCARD uint32_t	generation (size_type index) const noexcept

GAIA_NODISCARD uint32_t	next_free (size_type index) const noexcept

GAIA_NODISCARD reference	operator[] (size_type index)

GAIA_NODISCARD const_reference	operator[] (size_type index) const

void	clear ()

GAIA_NODISCARD size_type	get_next_free_item () const noexcept

GAIA_NODISCARD size_type	get_free_items () const noexcept

GAIA_NODISCARD size_type	item_count () const noexcept

GAIA_NODISCARD size_type	size () const noexcept

GAIA_NODISCARD bool	empty () const noexcept

GAIA_NODISCARD size_type	capacity () const noexcept

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

GAIA_NODISCARD const_iterator	begin () const noexcept

GAIA_NODISCARD const_iterator	cbegin () const noexcept

GAIA_NODISCARD iterator	end () noexcept

GAIA_NODISCARD const_iterator	end () const noexcept

GAIA_NODISCARD const_iterator	cend () const noexcept

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 pointer	try_get (size_type index) noexcept

GAIA_NODISCARD const_pointer	try_get (size_type index) const noexcept

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.

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.

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

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

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

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

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

Member Function Documentation

◆ add_free() [1/2]

◆ add_free() [2/2]

◆ add_live()

◆ alloc() [1/2]

◆ alloc() [2/2]

◆ free()

◆ free_keep_live()

◆ live_unsafe() [1/2]

◆ live_unsafe() [2/2]

◆ page_capacity()

◆ page_count_for_capacity()

◆ reserve()

◆ reserve_slot_table()