helios::ecs::details::Entities Class Reference

Entity manager responsible for entity creation, destruction, and validation. More...

#include <entities_manager.hpp>

Public Member Functions
	Entities ()=default
	Entities (const Entities &)=delete
	Entities (Entities &&) noexcept
	~Entities ()=default
Entities &	operator= (const Entities &)=delete
Entities &	operator= (Entities &&) noexcept
void	FlushReservedEntities ()
	Creates reserved entities in the metadata.
void	Clear () noexcept
	Clears all entities.
void	Reserve (size_t count)
	Reserves space for entities to minimize allocations.
Entity	ReserveEntity ()
	Reserves an entity ID that can be used immediately.
Entity	CreateEntity ()
	Creates a new entity.
template<std::output_iterator< Entity > OutputIt>
OutputIt	CreateEntities (size_t count, OutputIt out)
void	Destroy (Entity entity)
	Destroys an entity by incrementing its generation.
template<std::ranges::range R> requires std::same_as<std::ranges::range_value_t<R>, Entity>
void	Destroy (const R &entities)
	Destroys an entity by incrementing its generation.
bool	IsValid (Entity entity) const noexcept
	Checks if an entity exists and is valid.
size_t	Count () const noexcept
	Gets the current number of living entities.
Entity::GenerationType	GetGeneration (Entity::IndexType index) const noexcept
	Returns current generation value for a given index (or kInvalidGeneration if out of range).

Detailed Description

Entity manager responsible for entity creation, destruction, and validation.

Manages entity lifecycle with generation counters to handle entity recycling safely.

Note

Thread-safe only for validation operations.

Definition at line 26 of file entities_manager.hpp.

Constructor & Destructor Documentation

Entities() [1/3]

helios::ecs::details::Entities::Entities ( )

default

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/ecs/details/entities_manager.hpp.

Entities() [2/3]

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

delete

Entities() [3/3]

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

inlinenoexcept

Definition at line 158 of file entities_manager.hpp.

    : generations_(std::move(other.generations_)),
      free_indices_(std::move(other.free_indices_)),
      entity_count_(other.entity_count_.load(std::memory_order_relaxed)),
      next_index_(other.next_index_.load(std::memory_order_relaxed)),
      free_cursor_(other.free_cursor_.load(std::memory_order_relaxed)) {
  other.entity_count_.store(0, std::memory_order_relaxed);
  other.next_index_.store(0, std::memory_order_relaxed);
  other.free_cursor_.store(0, std::memory_order_relaxed);
}

~Entities()

helios::ecs::details::Entities::~Entities ( )

default

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/ecs/details/entities_manager.hpp.

Member Function Documentation

Clear()

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

inlinenoexcept

Clears all entities.

Destroys all entities and resets the manager state.

Note

Not thread-safe, should be called from main thread only.

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/ecs/details/entities_manager.hpp.

Definition at line 183 of file entities_manager.hpp.

                                     {
  std::ranges::fill(generations_, Entity::kInvalidGeneration);
  free_indices_.clear();
  next_index_.store(0, std::memory_order_relaxed);
  free_cursor_.store(0, std::memory_order_relaxed);
  entity_count_.store(0, std::memory_order_relaxed);
}

Count()

size_t helios::ecs::details::Entities::Count ( ) const

inlinenoexcept

Gets the current number of living entities.

Returns count of entities that are currently alive.

Note

Thread-safe.

Returns

Number of living entities

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/ecs/details/entities_manager.hpp.

Definition at line 140 of file entities_manager.hpp.

{ return entity_count_.load(std::memory_order_relaxed); }

CreateEntities()

template<std::output_iterator< Entity > OutputIt>

OutputIt helios::ecs::details::Entities::CreateEntities ( size_t  count, OutputIt  out  )

inline

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/ecs/details/entities_manager.hpp.

Definition at line 271 of file entities_manager.hpp.

                                                                   {
  if (count == 0) [[unlikely]] {
    return out;
  }
 
  // Try to satisfy as many as possible from the free list first
  size_t remaining = count;
  int64_t cursor = free_cursor_.load(std::memory_order_relaxed);
  // Use std::max with explicit signed type to avoid non-standard integer literal suffix
  const size_t available_free = static_cast<size_t>(std::max<int64_t>(int64_t{0}, cursor));
  const size_t from_free_list = std::min(remaining, available_free);
 
  if (from_free_list > 0) {
    const int64_t new_cursor = cursor - static_cast<int64_t>(from_free_list);
    if (free_cursor_.compare_exchange_strong(cursor, new_cursor, std::memory_order_relaxed)) {
      // Successfully claimed indices from free list
      for (size_t i = 0; i < from_free_list; ++i) {
        const size_t free_index = static_cast<size_t>(new_cursor) + i;
        if (free_index >= free_indices_.size()) {
          continue;
        }
 
        const Entity::IndexType index = free_indices_[free_index];
        if (index >= generations_.size()) {
          continue;
        }
 
        const Entity::GenerationType generation = generations_[index];
        *out = CreateEntityWithId(index, generation);
        ++out;
      }
      remaining -= from_free_list;
    }
  }
 
  // Create new entities for remaining count
  if (remaining > 0) {
    const Entity::IndexType start_index =
        next_index_.fetch_add(static_cast<Entity::IndexType>(remaining), std::memory_order_relaxed);
    const Entity::IndexType end_index = start_index + static_cast<Entity::IndexType>(remaining);
 
    // Ensure generations array is large enough
    if (end_index > generations_.size()) {
      generations_.resize(end_index, Entity::kInvalidGeneration);
    }
 
    // Create entities with generation 1
    for (Entity::IndexType index = start_index; index < end_index; ++index) {
      generations_[index] = 1;
      *out = CreateEntityWithId(index, 1);
      ++out;
    }
  }
 
  return out;
}

CreateEntity()

Entity helios::ecs::details::Entities::CreateEntity

(

)

Creates a new entity.

Reuses dead entity slots when available, otherwise creates new ones.

Note

Not thread-safe, should be called from main thread only during World::Update().

Returns

Newly created entity with valid index and generation

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/ecs/details/entities_manager.hpp.

Definition at line 35 of file entities_manager.cpp.

                              {
  Entity::IndexType index = Entity::kInvalidIndex;
  Entity::GenerationType generation = Entity::kInvalidGeneration;
 
  // Try to reuse a recycled index first
  int64_t cursor = free_cursor_.load(std::memory_order_relaxed);
  if (cursor > 0) {
    // Attempt to pop from free list
    const int64_t new_cursor = cursor - 1;
    if (free_cursor_.compare_exchange_strong(cursor, new_cursor, std::memory_order_relaxed)) {
      // Successfully claimed an index from the free list
      const auto free_index = static_cast<size_t>(new_cursor);
      if (free_index < free_indices_.size()) {
        index = free_indices_[free_index];
        if (index < generations_.size()) {
          generation = generations_[index];
          return CreateEntityWithId(index, generation);
        }
      }
    }
  }
 
  // No free indices available, allocate a new one
  index = next_index_.fetch_add(1, std::memory_order_relaxed);
 
  // Ensure generations array is large enough
  if (index >= generations_.size()) {
    generations_.resize(index + 1, Entity::kInvalidGeneration);
  }
 
  // Start with generation 1 for new entities
  generation = 1;
  generations_[index] = generation;
 
  return CreateEntityWithId(index, generation);
}

Destroy() [1/2]

template<std::ranges::range R>
requires std::same_as<std::ranges::range_value_t<R>, Entity>

void helios::ecs::details::Entities::Destroy ( const R &  entities )

inline

Destroys an entity by incrementing its generation.

Marks entity as dead and adds its index to the free list for reuse.

Note

Not thread-safe, should be called from main thread only during World::Update(). Triggers assertion if any entity is invalid. Entities that do not exist are ignored.

Template Parameters

R	Range type containing Entity elements

Parameters

entities

Entities to destroy

Definition at line 227 of file entities_manager.hpp.

                                               {
  // If the incoming range is sized we can reserve capacity up front to avoid reallocations.
  if constexpr (std::ranges::sized_range<R>) {
    const auto incoming = std::ranges::size(entities);
    free_indices_.reserve(free_indices_.size() + incoming);
  }
 
  // Small local buffer to collect indices we're going to free.
  // We collect them locally so we can do a single insert into free_indices_,
  // and do a single atomic update for free_cursor_ and entity_count_.
  std::vector<Entity::IndexType> batch;
  if constexpr (std::ranges::sized_range<R>) {
    batch.reserve(std::ranges::size(entities));
  } else {
    batch.reserve(16);  // small default to avoid too many reallocs for small ranges
  }
 
  // Process each entity: validate, increment generation, collect index.
  // We increment generation immediately so behaviour matches the single-entity Destroy
  // (i.e. duplicates in the input will fail the second validation).
  for (const Entity& entity : entities) {
    HELIOS_ASSERT(entity.Valid(), "Failed to destroy entities: Entity is invalid!");
    if (!IsValid(entity)) {
      // Skip entities already destroyed / wrong generation
      continue;
    }
 
    const Entity::IndexType index = entity.Index();
    ++generations_[index];  // Invalidate entity
    batch.push_back(index);
  }
 
  if (!batch.empty()) {
#ifdef HELIOS_CONTAINERS_RANGES_AVALIABLE
    free_indices_.append_range(batch);
#else
    free_indices_.insert(free_indices_.end(), batch.begin(), batch.end());
#endif
    free_cursor_.store(static_cast<int64_t>(free_indices_.size()), std::memory_order_relaxed);
    entity_count_.fetch_sub(batch.size(), std::memory_order_relaxed);
  }
}

Destroy() [2/2]

void helios::ecs::details::Entities::Destroy ( Entity  entity )

inline

Destroys an entity by incrementing its generation.

Marks entity as dead and adds its index to the free list for reuse.

Note

Not thread-safe, should be called from main thread only during World::Update(). Triggers assertion if entity is invalid. Ignored if entity do not exist.

Parameters

entity

Entity to destroy

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/ecs/details/entities_manager.hpp.

Definition at line 211 of file entities_manager.hpp.

                                           {
  HELIOS_ASSERT(entity.Valid(), "Failed to destroy entity: Entity is invalid!");
  if (!IsValid(entity)) [[unlikely]] {
    return;
  }
 
  const Entity::IndexType index = entity.Index();
  ++generations_[index];  // Invalidate entity
  free_indices_.push_back(index);
 
  free_cursor_.store(static_cast<int64_t>(free_indices_.size()), std::memory_order_relaxed);
  entity_count_.fetch_sub(1, std::memory_order_relaxed);
}

FlushReservedEntities()

void helios::ecs::details::Entities::FlushReservedEntities

(

)

Creates reserved entities in the metadata.

Processes all reserved entity IDs and creates their metadata.

Note

Not thread-safe, must be called from single thread only (typically during World::Update()).

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/ecs/details/entities_manager.hpp.

Definition at line 12 of file entities_manager.cpp.

                                     {
  const Entity::IndexType current_next_index = next_index_.load(std::memory_order_relaxed);
 
  // Ensure generations array is large enough
  if (current_next_index > generations_.size()) {
    generations_.resize(current_next_index, Entity::kInvalidGeneration);
  }
 
  // Initialize any indices that were reserved but not yet created
  size_t new_entities_count = 0;
  for (size_t i = 0; i < current_next_index; ++i) {
    if (generations_[i] == Entity::kInvalidGeneration) {
      generations_[i] = 1;  // Start with generation 1 for new entities
      ++new_entities_count;
    }
  }
 
  // Update entity count to reflect newly created entities
  if (new_entities_count > 0) {
    entity_count_.fetch_add(new_entities_count, std::memory_order_relaxed);
  }
}

GetGeneration()

Entity::GenerationType helios::ecs::details::Entities::GetGeneration ( Entity::IndexType  index ) const

inlinenoexcept

Returns current generation value for a given index (or kInvalidGeneration if out of range).

Warning

Triggers assertion if index is invalid.

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/ecs/details/entities_manager.hpp.

Definition at line 338 of file entities_manager.hpp.

                                                                                        {
  HELIOS_ASSERT(index != Entity::kInvalidIndex, "Failed to get generation: index is invalid!");
  return index < generations_.size() ? generations_[index] : Entity::kInvalidGeneration;
}

IsValid()

bool helios::ecs::details::Entities::IsValid ( Entity  entity ) const

inlinenoexcept

Checks if an entity exists and is valid.

Validates both the entity structure and its current generation.

Note

Thread-safe for read operations.

Parameters

entity

Entity to validate

Returns

True if entity exists and is valid, false otherwise

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/ecs/details/entities_manager.hpp.

Definition at line 328 of file entities_manager.hpp.

                                                          {
  if (!entity.Valid()) [[unlikely]] {
    return false;
  }
 
  const Entity::IndexType index = entity.Index();
  return index < generations_.size() && generations_[index] == entity.Generation() &&
         generations_[index] != Entity::kInvalidGeneration;
}

operator=() [1/2]

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

delete

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/ecs/details/entities_manager.hpp.

operator=() [2/2]

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

inlinenoexcept

Definition at line 169 of file entities_manager.hpp.

                                                              {
  if (this == &other) [[unlikely]] {
    return *this;
  }
 
  generations_ = std::move(other.generations_);
  free_indices_ = std::move(other.free_indices_);
  entity_count_.store(other.entity_count_.load(std::memory_order_relaxed), std::memory_order_relaxed);
  next_index_.store(other.next_index_.load(std::memory_order_relaxed), std::memory_order_relaxed);
  free_cursor_.store(other.free_cursor_.load(std::memory_order_relaxed), std::memory_order_relaxed);
 
  return *this;
}

Reserve()

void helios::ecs::details::Entities::Reserve ( size_t  count )

inline

Reserves space for entities to minimize allocations.

Pre-allocates storage for the specified number of entities.

Note

Not thread-safe, should be called from main thread only.

Parameters

count

Number of entities to reserve space for

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/ecs/details/entities_manager.hpp.

Definition at line 191 of file entities_manager.hpp.

                                          {
  if (count > generations_.size()) {
    generations_.resize(count, Entity::kInvalidGeneration);
  }
  free_indices_.reserve(count);
}

ReserveEntity()

Entity helios::ecs::details::Entities::ReserveEntity ( )

inline

Reserves an entity ID that can be used immediately.

The actual entity creation is deferred until FlushReservedEntities() is called.

Note

Thread-safe.

Returns

Reserved entity with valid index and generation

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/ecs/details/entities_manager.hpp.

Definition at line 198 of file entities_manager.hpp.

                                      {
  // Atomically reserve an index by incrementing the next available index.
  // NOTE: Do NOT mutate metadata (e.g. `generations_` or `entity_count_`) here because
  // this function is thread-safe and may be called concurrently. The actual metadata
  // initialization for reserved indices is performed in `FlushReservedEntities()` which
  // must be called from the main thread.
  const Entity::IndexType index = next_index_.fetch_add(1, std::memory_order_relaxed);
 
  // Return a placeholder entity with generation 1. This is only a reservation handle;
  // the real creation/metadata setup happens in FlushReservedEntities().
  return {index, 1};
}