helios::ecs::details::QueryCacheManager Class Reference

Manages query state caching with Bevy-inspired optimizations. More...

#include <query_cache.hpp>

Public Member Functions
	QueryCacheManager ()=default
	QueryCacheManager (const QueryCacheManager &)=delete
	QueryCacheManager (QueryCacheManager &&other) noexcept
	~QueryCacheManager ()=default
QueryCacheManager &	operator= (const QueryCacheManager &)=delete
QueryCacheManager &	operator= (QueryCacheManager &&other) noexcept
void	Clear () noexcept
	Clears all cached query states and resets statistics.
void	ResetStats () noexcept
	Resets cache statistics without clearing query states.
const QueryState *	TryGetCache (std::span< const ComponentTypeId > with_components, std::span< const ComponentTypeId > without_components, size_t current_generation) const
	Tries to retrieve a valid cached query state.
void	StoreCache (std::span< const ComponentTypeId > with_components, std::span< const ComponentTypeId > without_components, std::vector< std::reference_wrapper< const Archetype > > matching_archetypes, size_t current_generation)
	Stores or updates a query state in the cache.
void	InvalidateAll ()
	Invalidates all cached query states.
void	InvalidateForComponents (std::span< const ComponentTypeId > component_ids)
	Invalidates query states that involve specific components.
void	NotifyArchetypeChange ()
	Notifies the cache of an archetype structural change.
size_t	CacheSize () const noexcept
	Gets the number of cached query states.
QueryCacheStats	Stats () const noexcept
	Gets cache performance statistics.

Static Public Member Functions
static bool	ValidateQueryState (const QueryState &state, size_t current_generation)
	Validates a cached query state against current archetype generations.

Detailed Description

Manages query state caching with Bevy-inspired optimizations.

Provides efficient caching of archetype matching results with smart invalidation.

Key features:

• Archetype generation tracking: Each archetype has a generation counter that increments on structural changes. Query states cache these generations and can detect stale data.
• Component-aware invalidation: Only queries using specific components are invalidated when those components are modified.
• Query state reuse: Pre-computed query metadata is cached and reused across frames.
• Efficient validation: Quick checks using generation counters avoid full re-computation.

Note

Thread-safe for read operations, single-writer for updates.

Definition at line 204 of file query_cache.hpp.

Constructor & Destructor Documentation

QueryCacheManager() [1/3]

helios::ecs::details::QueryCacheManager::QueryCacheManager ( )

default

QueryCacheManager() [2/3]

helios::ecs::details::QueryCacheManager::QueryCacheManager ( const QueryCacheManager &  )

delete

QueryCacheManager() [3/3]

helios::ecs::details::QueryCacheManager::QueryCacheManager ( QueryCacheManager &&  other )

inlinenoexcept

Definition at line 328 of file query_cache.hpp.

    : cache_(std::move(other.cache_)),
      stats_(std::move(other.stats_)),
      access_counter_(other.access_counter_.load(std::memory_order_relaxed)) {}

~QueryCacheManager()

helios::ecs::details::QueryCacheManager::~QueryCacheManager ( )

default

Member Function Documentation

CacheSize()

size_t helios::ecs::details::QueryCacheManager::CacheSize ( ) const

inlinenoexcept

Gets the number of cached query states.

Returns

Cache entry count

Definition at line 275 of file query_cache.hpp.

{ return cache_.size(); }

Clear()

void helios::ecs::details::QueryCacheManager::Clear ( )

inlinenoexcept

Clears all cached query states and resets statistics.

Definition at line 345 of file query_cache.hpp.

                                              {
  cache_.clear();
  stats_.Reset();
  access_counter_.store(0, std::memory_order_relaxed);
}

InvalidateAll()

void helios::ecs::details::QueryCacheManager::InvalidateAll ( )

inline

Invalidates all cached query states.

Called when major structural changes occur that affect many queries. Increments global invalidation counter.

Definition at line 379 of file query_cache.hpp.

                                             {
  cache_.clear();
  ++stats_.invalidation_count;
}

InvalidateForComponents()

void helios::ecs::details::QueryCacheManager::InvalidateForComponents ( std::span< const ComponentTypeId >  component_ids )

inline

Invalidates query states that involve specific components.

Selective invalidation - only queries using the specified components need to be recomputed. More efficient than full invalidation.

Parameters

component_ids

Component types that were modified

Definition at line 384 of file query_cache.hpp.

                                                                                                   {
  if (component_ids.empty()) {
    return;
  }
 
  // Remove cache entries that involve any of the specified components
  std::vector<size_t> keys_to_remove;
  cache_.cvisit_all([&keys_to_remove, component_ids](const auto& pair) {
    if (QueryInvolvesAnyComponents(pair.second, component_ids)) {
      keys_to_remove.push_back(pair.first);
    }
  });
 
  for (const size_t key : keys_to_remove) {
    cache_.erase(key);
  }
 
  if (!keys_to_remove.empty()) {
    stats_.partial_invalidations.fetch_add(keys_to_remove.size(), std::memory_order_relaxed);
  }
}

NotifyArchetypeChange()

void helios::ecs::details::QueryCacheManager::NotifyArchetypeChange ( )

inline

Notifies the cache of an archetype structural change.

Increments archetype change counter for statistics tracking. Does not directly invalidate - queries validate themselves using generation checks.

Definition at line 269 of file query_cache.hpp.

{ ++stats_.archetype_changes; }

operator=() [1/2]

QueryCacheManager & helios::ecs::details::QueryCacheManager::operator= ( const QueryCacheManager &  )

delete

operator=() [2/2]

QueryCacheManager & helios::ecs::details::QueryCacheManager::operator= ( QueryCacheManager &&  other )

inlinenoexcept

Definition at line 333 of file query_cache.hpp.

                                                                                         {
  if (this == &other) {
    return *this;
  }
 
  cache_ = std::move(other.cache_);
  stats_ = other.stats_;
  access_counter_.store(other.access_counter_.load(std::memory_order_relaxed), std::memory_order_relaxed);
 
  return *this;
}

ResetStats()

void helios::ecs::details::QueryCacheManager::ResetStats ( )

inlinenoexcept

Resets cache statistics without clearing query states.

Definition at line 222 of file query_cache.hpp.

{ stats_.Reset(); }

Stats()

QueryCacheStats helios::ecs::details::QueryCacheManager::Stats ( ) const

inlinenoexcept

Gets cache performance statistics.

Returns

Struct containing hit/miss counts and other metrics

Definition at line 281 of file query_cache.hpp.

{ return stats_; }

StoreCache()

void helios::ecs::details::QueryCacheManager::StoreCache	(	std::span< const ComponentTypeId >	with_components,
		std::span< const ComponentTypeId >	without_components,
		std::vector< std::reference_wrapper< const Archetype > >	matching_archetypes,
		size_t	current_generation
	)

Stores or updates a query state in the cache.

Caches the matched archetypes along with their current generation counters. This allows future queries to validate the cache using generation checks.

Parameters

with_components	Component types that must be present (must be sorted)
without_components	Component types that must not be present (must be sorted)
matching_archetypes	Archetypes that match the query criteria
current_generation	Current world structural generation

Definition at line 43 of file query_cache.cpp.

                                                              {
  const size_t hash = ComputeQueryHash(with_components, without_components);
 
  QueryState state;
  state.matching_archetypes = std::move(matching_archetypes);
  state.archetype_generations.reserve(state.matching_archetypes.size());
 
  // Store each archetype's current generation for validation
  for (const auto& archetype_ref : state.matching_archetypes) {
    state.archetype_generations.push_back(archetype_ref.get().GetGeneration());
  }
 
  state.with_component_types.assign(with_components.begin(), with_components.end());
  state.without_component_types.assign(without_components.begin(), without_components.end());
  state.query_generation = current_generation;
  state.query_hash = hash;
  state.last_access_time.store(access_counter_.fetch_add(1, std::memory_order_relaxed), std::memory_order_relaxed);
 
  cache_.insert_or_assign(hash, std::move(state));
}

TryGetCache()

const QueryState * helios::ecs::details::QueryCacheManager::TryGetCache ( std::span< const ComponentTypeId >  with_components, std::span< const ComponentTypeId >  without_components, size_t  current_generation  ) const

inline

Tries to retrieve a valid cached query state.

Checks if cached state exists and validates it against current archetype generations. If state is stale (archetypes changed), returns nullptr to trigger re-computation.

Parameters

with_components	Component types that must be present (must be sorted)
without_components	Component types that must not be present (must be sorted)
current_generation	Current world structural generation

Returns

Pointer to valid cached state, or nullptr if cache miss/stale

Definition at line 351 of file query_cache.hpp.

                                                                                         {
  const size_t hash = ComputeQueryHash(with_components, without_components);
  const QueryState* found = nullptr;
 
  cache_.cvisit(hash, [this, &found, current_generation](const auto& pair) {
    auto& state = const_cast<QueryState&>(pair.second);
 
    // Validate state against current generation
    if (!ValidateQueryState(state, current_generation)) {
      return;  // State is stale
    }
 
    UpdateAccessTime(state);
    found = &state;
  });
 
  if (found == nullptr) {
    ++stats_.miss_count;
  } else {
    ++stats_.hit_count;
  }
  ++stats_.total_queries;
 
  return found;
}

ValidateQueryState()

bool helios::ecs::details::QueryCacheManager::ValidateQueryState ( const QueryState &  state, size_t  current_generation  )

static

Validates a cached query state against current archetype generations.

Compares cached archetype generations with current ones to detect if any archetypes have changed structure since caching.

Parameters

state	Query state to validate
current_generation	Current world structural generation

Returns

True if state is still valid, false if stale

Definition at line 67 of file query_cache.cpp.

                                                                                             {
  // Quick check: world generation mismatch
  if (state.query_generation != current_generation) {
    return false;
  }
 
  // Validate each cached archetype's generation
  HELIOS_ASSERT(state.matching_archetypes.size() == state.archetype_generations.size(),
                "Archetype count mismatch in query state! Expected {}, got {}", state.matching_archetypes.size(),
                state.archetype_generations.size());
 
  for (size_t i = 0; i < state.matching_archetypes.size(); ++i) {
    const Archetype& archetype = state.matching_archetypes[i].get();
    const size_t cached_generation = state.archetype_generations[i];
 
    // Check if archetype structure has changed
    if (archetype.GetGeneration() != cached_generation) {
      return false;
    }
  }
 
  return true;
}