Gaia-ECS v0.9.3
A simple and powerful entity component system
Loading...
Searching...
No Matches
gaia::ecs::QueryInfo Class Reference

Classes

struct  CleanUpTmpArchetypeMatches
 

Public Types

enum class  MatchArchetypeQueryRet : uint8_t { Fail , Ok , Skip }
 Query matching result.
 
enum class  InvalidationKind : uint8_t { Result , Seed , All }
 

Public Member Functions

void add_ref ()
 Adds one external reference to this query slot.
 
void dec_ref ()
 Releases one external reference to this query slot.
 
uint32_t refs () const
 Returns the current external reference count.
 
void init (World *world)
 Binds this query info to a world after slot allocation.
 
void reset ()
 Resets cached query state for slot reuse while keeping the compiled context object.
 
void invalidate (InvalidationKind kind=InvalidationKind::All)
 Marks cached query results stale.
 
void invalidate_seed ()
 Marks structural seed matches stale.
 
void invalidate_result ()
 Marks final result matches stale while preserving structural seed matches.
 
void invalidate_sort ()
 Marks the cached sorted slices dirty without invalidating query membership.
 
void compile (const EntityToArchetypeMap &entityToArchetypeMap, std::span< const Archetype * > allArchetypes)
 Compile the query terms into a form we can easily process.
 
void recompile ()
 Recompile the query.
 
GAIA_NODISCARD QueryCtx::CachePolicy cache_policy () const
 Returns the query cache policy selected during compilation.
 
GAIA_NODISCARD bool has_grouped_payload () const
 Returns true when grouped-query payloads are active for this query.
 
GAIA_NODISCARD bool has_sorted_payload () const
 Returns true when sorted-query payloads are active for this query.
 
GAIA_NODISCARD uint32_t result_cache_rev () const
 Returns the result membership revision used by reverse-index cache users.
 
GAIA_NODISCARD bool can_update_with_new_archetype () const
 Returns true when a new archetype can be propagated into the current cache incrementally.
 
GAIA_NODISCARD bool can_use_direct_create_archetype_match () const
 Returns whether create-time matching should bypass the temporary one-archetype VM path.
 
GAIA_NODISCARD bool direct_create_archetype_match_uses_is () const
 Returns whether direct create-time matching needs Is-aware id checks.
 
GAIA_NODISCARD bool operator== (const QueryCtx &other) const
 
GAIA_NODISCARD bool operator!= (const QueryCtx &other) const
 
template<typename ArchetypeLookup >
void match (const ArchetypeLookup &entityToArchetypeMap, std::span< const Archetype * > allArchetypes, const EntityToArchetypeVersionMap *pEntityToArchetypeMapVersions, ArchetypeId archetypeLastId, const cnt::sarray< Entity, MaxVarCnt > &runtimeVarBindings, uint8_t runtimeVarBindingMask)
 Tries to match the query against archetypes in entityToArchetypeMap. This is necessary so we do not iterate all chunks over and over again when running queries.
 
bool match_one (const Archetype &archetype, EntitySpan targetEntities, const cnt::sarray< Entity, MaxVarCnt > &runtimeVarBindings, uint8_t runtimeVarBindingMask)
 Tries to match the query against the provided archetype. This is necessary so we do not iterate all chunks over and over again when running queries.
 
void ensure_matches (const EntityToArchetypeMap &entityToArchetypeMap, std::span< const Archetype * > allArchetypes, const EntityToArchetypeVersionMap &entityToArchetypeMapVersions, ArchetypeId archetypeLastId, const cnt::sarray< Entity, MaxVarCnt > &runtimeVarBindings, uint8_t runtimeVarBindingMask)
 
void ensure_matches_transient (const EntityToArchetypeMap &entityToArchetypeMap, std::span< const Archetype * > allArchetypes, const EntityToArchetypeVersionMap &entityToArchetypeMapVersions, const cnt::sarray< Entity, MaxVarCnt > &runtimeVarBindings, uint8_t runtimeVarBindingMask)
 
bool ensure_matches_one (const Archetype &archetype, EntitySpan targetEntities, const cnt::sarray< Entity, MaxVarCnt > &runtimeVarBindings, uint8_t runtimeVarBindingMask)
 
bool ensure_matches_one_transient (const Archetype &archetype, EntitySpan targetEntities, const cnt::sarray< Entity, MaxVarCnt > &runtimeVarBindings, uint8_t runtimeVarBindingMask)
 
bool register_archetype (const Archetype &archetype, Entity matchedSelector=EntityBad, bool assumeNew=false)
 Registers a new or updated archetype with query caches when it matches this query.
 
void calculate_sort_data ()
 Calculates the sort data for the archetypes in the cache. This allows us to iterate entites in the order they are sorted across all archetypes.
 
void sort_entities ()
 Applies query entity sorting and rebuilds sorted chunk slices when needed.
 
void sort_cache_groups ()
 Sorts cached archetypes by group id when grouped iteration requested ordering.
 
void swap_archetype_cache_entry (uint32_t left, uint32_t right)
 Swaps two result-cache entries and every parallel payload array that mirrors cache order.
 
void ensure_comp_indices ()
 Rebuilds cached component-index payloads for matched archetypes when marked pending.
 
GAIA_NODISCARD bool has_inherited_data_payload () const
 Returns true when query iteration needs cached inherited data payloads.
 
void ensure_inherited_data ()
 Rebuilds inherited-data payloads for matched archetypes when query terms require them.
 
void ensure_group_data (bool orderGroups)
 Rebuilds grouped archetype ranges when a caller needs ordered group data.
 
void ensure_depth_order_hierarchy_barrier_cache_inter ()
 Rebuilds cached depth-order hierarchy barrier results when relation or enabled-state versions changed.
 
ArchetypeCompIndices create_comp_indices (const Archetype *pArchetype)
 Builds field-to-archetype component indices for one matched archetype.
 
void create_inherited_data (const Archetype *pArchetype)
 Builds inherited component data pointers for semantic self-source terms on one archetype.
 
void add_archetype_to_cache_no_grouping (const Archetype *pArchetype, bool trackMembershipChange, bool assumeAbsent=false)
 Adds an archetype to the final result cache for ungrouped queries.
 
void add_archetype_to_seed_cache (const Archetype *pArchetype, bool assumeAbsent=false)
 Adds an archetype to the structural seed cache.
 
void add_new_archetype_to_immediate_caches (const Archetype *pArchetype, bool trackMembershipChange)
 Adds a newly matched archetype to both immediate caches while reusing one computed index mapping.
 
void add_archetype_to_cache_w_grouping (const Archetype *pArchetype, bool trackMembershipChange, bool assumeAbsent=false)
 Adds an archetype to the final result cache and records its group id.
 
void add_archetype_to_cache (const Archetype *pArchetype, bool trackMembershipChange, bool assumeAbsent)
 Adds an archetype to the final result cache and updates derived-payload dirty flags.
 
void add_archetype_to_transient_cache (const Archetype *pArchetype)
 Adds an archetype to the transient result cache used by non-persistent matching paths.
 
GAIA_NODISCARD const GroupData * selected_group_data (GroupId runtimeGroupId) const
 Returns cached group bounds for the currently selected group filter. The cached range is invalidated whenever group layout changes or the selected group id changes.
 
GAIA_NODISCARD bool has_same_result_membership_as_seed_cache () const
 Compares final result-cache membership with the structural seed cache.
 
GAIA_NODISCARD bool has_same_result_membership_as (const CArchetypeDArray &archetypeCache) const
 Compares final result-cache membership with another archetype array.
 
void sync_result_cache_from_seed_cache ()
 Rebuilds the final result cache from structural seed matches. Bumps result membership revision only when the final membership actually changes.
 
bool del_archetype_from_cache (const Archetype *pArchetype)
 Removes an archetype from the final result cache and mirrored payload arrays.
 
bool del_archetype_from_seed_cache (const Archetype *pArchetype)
 Removes an archetype from the structural seed cache.
 
GAIA_NODISCARD Worldworld ()
 Returns the mutable world owning this query.
 
GAIA_NODISCARD const Worldworld () const
 Returns the world owning this query.
 
GAIA_NODISCARD QuerySerBufferser_buffer ()
 Returns the query serialization buffer associated with the owning world.
 
void ser_buffer_reset ()
 Resets the query serialization buffer associated with the owning world.
 
GAIA_NODISCARD QueryCtxctx ()
 Returns the mutable compiled query context.
 
GAIA_NODISCARD const QueryCtxctx () const
 Returns the compiled query context.
 
GAIA_NODISCARD util::str bytecode () const
 Returns a textual dump of the compiled VM bytecode.
 
GAIA_NODISCARD uint32_t op_count () const
 Returns the number of VM operations in the compiled query.
 
GAIA_NODISCARD uint64_t op_signature () const
 Returns a stable signature for the compiled VM operation stream.
 
GAIA_NODISCARD bool has_filters () const
 Returns true when the query has per-entity changed/filter terms.
 
GAIA_NODISCARD bool has_entity_filter_terms () const
 Returns true when direct non-fragmenting terms must be rechecked per entity.
 
GAIA_NODISCARD bool has_potential_inherited_id_terms () const
 Returns true when the query shape can resolve through inherited-id matching.
 
GAIA_NODISCARD QueryCtx::DirectTargetEvalKind direct_target_eval_kind () const
 Returns the direct target evaluation mode selected during compilation.
 
GAIA_NODISCARD Entity direct_target_eval_id () const
 Returns the concrete direct target id used by direct target evaluation.
 
GAIA_NODISCARD bool can_direct_target_eval () const
 Returns true when the query can evaluate concrete target entities directly.
 
GAIA_NODISCARD bool can_direct_entity_seed_eval_shape () const
 Returns true when the query shape is eligible for direct entity seed evaluation.
 
GAIA_NODISCARD bool has_only_direct_or_terms () const
 Returns true when the query contains only direct OR/NOT terms and at least one OR term.
 
GAIA_NODISCARD bool matches_prefab_entities () const
 Returns true when prefab-tagged entities should participate in query results.
 
template<typename... T>
GAIA_NODISCARD bool has_any () const
 Returns true when any of the requested types is present as an Any term.
 
template<typename... T>
GAIA_NODISCARD bool has_or () const
 Returns true when any of the requested types is present as an Or term.
 
template<typename... T>
GAIA_NODISCARD bool has_all () const
 Returns true when all requested types are present as All terms.
 
template<typename... T>
GAIA_NODISCARD bool has_no () const
 Returns true when none of the requested types is present as a Not term.
 
void remove (Archetype *pArchetype)
 Removes an archetype from cache.
 
std::span< const uint8_t > indices_mapping_view (uint32_t archetypeIdx) const
 Returns a view of indices mapping for component entities in a given archetype.
 
InheritedTermDataView inherited_data_view (uint32_t archetypeIdx) const
 Returns cached inherited-term data for a matched archetype index.
 
InheritedTermDataView inherited_data_view (const Archetype *pArchetype) const
 Returns cached inherited-term data for a matched archetype pointer.
 
void ensure_depth_order_hierarchy_barrier_cache ()
 Ensures depth-order hierarchy barrier results are current before public reads.
 
std::span< const uint8_t > try_indices_mapping_view (const Archetype *pArchetype) const
 Returns a cached indices mapping view for an exact archetype match, or an empty span when absent.
 
InheritedTermDataView try_inherited_data_view (const Archetype *pArchetype) const
 Returns cached inherited-term data if it is already available for a matched archetype.
 
GAIA_NODISCARD GroupId group_id (uint32_t archetypeIdx) const
 Returns the cached group id for a matched archetype index.
 
GAIA_NODISCARD bool barrier_passes (uint32_t archetypeIdx) const
 Returns true when the matched archetype passes the depth-order hierarchy barrier.
 
GAIA_NODISCARD bool barrier_may_prune () const
 Returns true when any cached archetype can be pruned by the hierarchy barrier.
 
GAIA_NODISCARD CArchetypeDArray::iterator begin ()
 Returns a mutable iterator to the first cached result archetype.
 
GAIA_NODISCARD CArchetypeDArray::const_iterator begin () const
 Returns an iterator to the first cached result archetype.
 
GAIA_NODISCARD CArchetypeDArray::const_iterator cbegin () const
 Returns a const iterator to the first cached result archetype.
 
GAIA_NODISCARD CArchetypeDArray::iterator end ()
 Returns a mutable iterator past the last cached result archetype.
 
GAIA_NODISCARD CArchetypeDArray::const_iterator end () const
 Returns an iterator past the last cached result archetype.
 
GAIA_NODISCARD CArchetypeDArray::const_iterator cend () const
 Returns a const iterator past the last cached result archetype.
 
GAIA_NODISCARD std::span< const Archetype * > cache_archetype_view () const
 Returns the cached result archetypes as a span.
 
GAIA_NODISCARD std::span< const SortData > cache_sort_view () const
 Returns cached sorted chunk slices.
 
GAIA_NODISCARD std::span< const GroupData > group_data_view () const
 Returns cached group ranges, rebuilding grouped data when needed.
 

Static Public Member Functions

static GAIA_NODISCARD QueryInfo create (QueryId id, QueryCtx &&ctx, const EntityToArchetypeMap &entityToArchetypeMap, std::span< const Archetype * > allArchetypes)
 Creates and compiles a query info object from a moved query context.
 
static GAIA_NODISCARD QueryInfo create (uint32_t idx, uint32_t gen, void *pCtx)
 Creates and compiles a query info object from slot creation context.
 
static GAIA_NODISCARD QueryHandle handle (const QueryInfo &info)
 Builds a stable query handle from query slot metadata.
 

Public Attributes

uint32_t idx = 0
 Allocated items: index in the query slot list. Deleted items: index of the next deleted item in the slot list.
 
uint32_t gen = 0
 Generation ID of the query slot.
 

Member Enumeration Documentation

◆ InvalidationKind

enum class gaia::ecs::QueryInfo::InvalidationKind : uint8_t
strong
Enumerator
Result 

Only the final result cache is stale. Structural seed matches remain valid and can be reused.

Seed 

Structural seed matches are stale. This also implies the final result cache must be rebuilt.

All 

Full invalidation of all query cache state.

Member Function Documentation

◆ add_archetype_to_cache()

void gaia::ecs::QueryInfo::add_archetype_to_cache ( const Archetype pArchetype,
bool  trackMembershipChange,
bool  assumeAbsent 
)
inline

Adds an archetype to the final result cache and updates derived-payload dirty flags.

Parameters
pArchetypeMatched archetype to cache.
trackMembershipChangeTrue to bump result membership revision after insertion.
assumeAbsentTrue when the caller already proved the archetype is not cached.

◆ add_archetype_to_cache_no_grouping()

void gaia::ecs::QueryInfo::add_archetype_to_cache_no_grouping ( const Archetype pArchetype,
bool  trackMembershipChange,
bool  assumeAbsent = false 
)
inline

Adds an archetype to the final result cache for ungrouped queries.

Parameters
pArchetypeMatched archetype to cache.
trackMembershipChangeTrue to bump result membership revision after insertion.
assumeAbsentTrue when the caller already proved the archetype is not cached.

◆ add_archetype_to_cache_w_grouping()

void gaia::ecs::QueryInfo::add_archetype_to_cache_w_grouping ( const Archetype pArchetype,
bool  trackMembershipChange,
bool  assumeAbsent = false 
)
inline

Adds an archetype to the final result cache and records its group id.

Parameters
pArchetypeMatched archetype to cache.
trackMembershipChangeTrue to bump result membership revision after insertion.
assumeAbsentTrue when the caller already proved the archetype is not cached.

◆ add_archetype_to_seed_cache()

void gaia::ecs::QueryInfo::add_archetype_to_seed_cache ( const Archetype pArchetype,
bool  assumeAbsent = false 
)
inline

Adds an archetype to the structural seed cache.

Parameters
pArchetypeStructurally matched archetype to cache.
assumeAbsentTrue when the caller already proved the archetype is not cached.

◆ add_archetype_to_transient_cache()

void gaia::ecs::QueryInfo::add_archetype_to_transient_cache ( const Archetype pArchetype)
inline

Adds an archetype to the transient result cache used by non-persistent matching paths.

Parameters
pArchetypeMatched archetype to cache for this transient result.

◆ add_new_archetype_to_immediate_caches()

void gaia::ecs::QueryInfo::add_new_archetype_to_immediate_caches ( const Archetype pArchetype,
bool  trackMembershipChange 
)
inline

Adds a newly matched archetype to both immediate caches while reusing one computed index mapping.

Parameters
pArchetypeNewly matched archetype to cache.
trackMembershipChangeTrue to bump result membership revision after insertion.

◆ barrier_passes()

GAIA_NODISCARD bool gaia::ecs::QueryInfo::barrier_passes ( uint32_t  archetypeIdx) const
inline

Returns true when the matched archetype passes the depth-order hierarchy barrier.

Parameters
archetypeIdxResult-cache archetype index.

◆ create() [1/2]

static GAIA_NODISCARD QueryInfo gaia::ecs::QueryInfo::create ( QueryId  id,
QueryCtx &&  ctx,
const EntityToArchetypeMap entityToArchetypeMap,
std::span< const Archetype * >  allArchetypes 
)
inlinestatic

Creates and compiles a query info object from a moved query context.

Parameters
idQuery slot id.
ctxQuery context to take ownership of.
entityToArchetypeMapWorld archetype lookup used during compilation.
allArchetypesCurrent world archetype list.

◆ create() [2/2]

static GAIA_NODISCARD QueryInfo gaia::ecs::QueryInfo::create ( uint32_t  idx,
uint32_t  gen,
void *  pCtx 
)
inlinestatic

Creates and compiles a query info object from slot creation context.

Parameters
idxQuery slot index.
genQuery slot generation.
pCtxPointer to QueryInfoCreationCtx.

◆ create_comp_indices()

ArchetypeCompIndices gaia::ecs::QueryInfo::create_comp_indices ( const Archetype pArchetype)
inline

Builds field-to-archetype component indices for one matched archetype.

Parameters
pArchetypeMatched archetype whose layout is mapped to query fields.
Returns
Component-index mapping consumed by query iteration.

◆ create_inherited_data()

void gaia::ecs::QueryInfo::create_inherited_data ( const Archetype pArchetype)
inline

Builds inherited component data pointers for semantic self-source terms on one archetype.

Parameters
pArchetypeMatched archetype whose inherited term data is cached.

◆ del_archetype_from_cache()

bool gaia::ecs::QueryInfo::del_archetype_from_cache ( const Archetype pArchetype)
inline

Removes an archetype from the final result cache and mirrored payload arrays.

Parameters
pArchetypeArchetype to remove.
Returns
True if the archetype was present or its set entry was removed.

◆ del_archetype_from_seed_cache()

bool gaia::ecs::QueryInfo::del_archetype_from_seed_cache ( const Archetype pArchetype)
inline

Removes an archetype from the structural seed cache.

Parameters
pArchetypeArchetype to remove.
Returns
True if the archetype was present or its set entry was removed.

◆ ensure_group_data()

void gaia::ecs::QueryInfo::ensure_group_data ( bool  orderGroups)
inline

Rebuilds grouped archetype ranges when a caller needs ordered group data.

Parameters
orderGroupsTrue to order archetypes by group id even when the query was not explicitly ordered.
Note
Plain grouped iteration passes false so group_by(...) does not sort the cache by itself.

◆ group_id()

GAIA_NODISCARD GroupId gaia::ecs::QueryInfo::group_id ( uint32_t  archetypeIdx) const
inline

Returns the cached group id for a matched archetype index.

Parameters
archetypeIdxResult-cache archetype index.

◆ has_same_result_membership_as()

GAIA_NODISCARD bool gaia::ecs::QueryInfo::has_same_result_membership_as ( const CArchetypeDArray archetypeCache) const
inline

Compares final result-cache membership with another archetype array.

Parameters
archetypeCacheArchetype membership to compare against the final result cache.
Returns
True when both collections contain the same archetypes.

◆ has_same_result_membership_as_seed_cache()

GAIA_NODISCARD bool gaia::ecs::QueryInfo::has_same_result_membership_as_seed_cache ( ) const
inline

Compares final result-cache membership with the structural seed cache.

Returns
True when both caches contain the same archetypes.

◆ inherited_data_view() [1/2]

InheritedTermDataView gaia::ecs::QueryInfo::inherited_data_view ( const Archetype pArchetype) const
inline

Returns cached inherited-term data for a matched archetype pointer.

Parameters
pArchetypeMatched archetype to look up.

◆ inherited_data_view() [2/2]

InheritedTermDataView gaia::ecs::QueryInfo::inherited_data_view ( uint32_t  archetypeIdx) const
inline

Returns cached inherited-term data for a matched archetype index.

Parameters
archetypeIdxResult-cache archetype index.

◆ init()

void gaia::ecs::QueryInfo::init ( World world)
inline

Binds this query info to a world after slot allocation.

Parameters
worldWorld owning the query.

◆ invalidate()

void gaia::ecs::QueryInfo::invalidate ( InvalidationKind  kind = InvalidationKind::All)
inline

Marks cached query results stale.

Parameters
kindCache layer to invalidate.

◆ match()

template<typename ArchetypeLookup >
void gaia::ecs::QueryInfo::match ( const ArchetypeLookup &  entityToArchetypeMap,
std::span< const Archetype * >  allArchetypes,
const EntityToArchetypeVersionMap pEntityToArchetypeMapVersions,
ArchetypeId  archetypeLastId,
const cnt::sarray< Entity, MaxVarCnt > &  runtimeVarBindings,
uint8_t  runtimeVarBindingMask 
)
inline

Tries to match the query against archetypes in entityToArchetypeMap. This is necessary so we do not iterate all chunks over and over again when running queries.

Parameters
entityToArchetypeMapLookup of archetypes by entity
allArchetypesList of all archetypes
pEntityToArchetypeMapVersionsOptional version map for archetype lookup validation
archetypeLastIdLast recorded archetype id
runtimeVarBindingsRuntime variable bindings for dynamic queries
runtimeVarBindingMaskMask indicating which runtime variables are bound
Template Parameters
ArchetypeLookupArchetype lookup container/view type used by the query cache.
Warning
Not thread safe. No two threads can call this at the same time.

◆ match_one()

bool gaia::ecs::QueryInfo::match_one ( const Archetype archetype,
EntitySpan  targetEntities,
const cnt::sarray< Entity, MaxVarCnt > &  runtimeVarBindings,
uint8_t  runtimeVarBindingMask 
)
inline

Tries to match the query against the provided archetype. This is necessary so we do not iterate all chunks over and over again when running queries.

Parameters
archetypeArchtype to match
targetEntitiesEntities related to the matched archetype
runtimeVarBindingsRuntime bindings for query variables.
runtimeVarBindingMaskBitmask of variables already bound in runtimeVarBindings.
Warning
Not thread safe. No two threads can call this at the same time.

◆ register_archetype()

bool gaia::ecs::QueryInfo::register_archetype ( const Archetype archetype,
Entity  matchedSelector = EntityBad,
bool  assumeNew = false 
)
inline

Registers a new or updated archetype with query caches when it matches this query.

Parameters
archetypeArchetype to evaluate.
matchedSelectorOptional selector that already matched the archetype.
assumeNewTrue when the caller knows the archetype is not present in the caches.
Returns
True when the archetype was added to a cache.

◆ remove()

void gaia::ecs::QueryInfo::remove ( Archetype pArchetype)
inline

Removes an archetype from cache.

Parameters
pArchetypeArchetype to remove

◆ selected_group_data()

GAIA_NODISCARD const GroupData * gaia::ecs::QueryInfo::selected_group_data ( GroupId  runtimeGroupId) const
inline

Returns cached group bounds for the currently selected group filter. The cached range is invalidated whenever group layout changes or the selected group id changes.

Parameters
runtimeGroupIdGroup id to look up.
Returns
Group range for the requested group, or nullptr if the group does not exist.

◆ swap_archetype_cache_entry()

void gaia::ecs::QueryInfo::swap_archetype_cache_entry ( uint32_t  left,
uint32_t  right 
)
inline

Swaps two result-cache entries and every parallel payload array that mirrors cache order.

Parameters
leftIndex of the first cache entry.
rightIndex of the second cache entry.

◆ try_inherited_data_view()

InheritedTermDataView gaia::ecs::QueryInfo::try_inherited_data_view ( const Archetype pArchetype) const
inline

Returns cached inherited-term data if it is already available for a matched archetype.

Parameters
pArchetypeMatched archetype to look up.

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