helios::app::details::Scheduler Class Reference

Main scheduler that manages all schedules. More...

#include <scheduler.hpp>

Public Member Functions
	Scheduler ()=default
	Scheduler (const Scheduler &)=delete
	Scheduler (Scheduler &&) noexcept=default
	~Scheduler ()=default
Scheduler &	operator= (const Scheduler &)=delete
Scheduler &	operator= (Scheduler &&) noexcept=default
void	Clear ()
	Clears all schedules and systems.
template<ScheduleTrait T>
void	RegisterSchedule ()
	Registers a schedule type.
template<ecs::SystemTrait T, ScheduleTrait S>
void	AddSystem (S schedule={})
	Adds a system to the specified schedule.
template<ecs::SystemTrait T, ScheduleTrait S>
void	RegisterOrdering (S schedule, SystemOrdering ordering)
	Registers ordering constraint for a system.
template<ScheduleTrait S>
void	ExecuteSchedule (ecs::World &world, async::Executor &executor)
	Executes all systems in the specified schedule.
void	ExecuteScheduleById (ScheduleId schedule_id, ecs::World &world, async::Executor &executor)
	Executes all systems in the specified schedule by ID.
template<StageTrait S>
void	ExecuteStage (ecs::World &world, async::Executor &executor)
	Executes all schedules in the specified stage.
void	MergeCommandsToWorld (ecs::World &world)
	Merges all system local commands into the world's main command queue.
void	ResetFrameAllocators () noexcept
	Resets all system frame allocators.
void	BuildAllGraphs (ecs::World &world)
	Builds execution graphs for all schedules.
template<ecs::SystemTrait T, ScheduleTrait S>
void	AppendSystemOrderingMetadata (S schedule, std::span< const ecs::SystemTypeId > before, std::span< const ecs::SystemTypeId > after)
	Appends system ordering constraints to a system's metadata in a specific schedule.
template<ecs::SystemTrait T, ScheduleTrait S>
void	AppendSystemSetMetadata (S schedule, std::span< const SystemSetId > sets)
	Appends system set membership to a system's metadata in a specific schedule.
template<SystemSetTrait Set>
SystemSetInfo &	GetOrRegisterSystemSet ()
	Gets or registers a system set in the global registry.
void	AddSystemToSet (SystemSetId set_id, ecs::SystemTypeId system_id)
	Adds a system to a system set's membership list.
void	AddSetRunsBefore (SystemSetId before_id, SystemSetId after_id)
	Adds a set-level ordering constraint: set A runs before set B.
void	AddSetRunsAfter (SystemSetId after_id, SystemSetId before_id)
	Adds a set-level ordering constraint: set A runs after set B.
template<ecs::SystemTrait T>
bool	ContainsSystem () const noexcept
	Checks if a system of type T is in any schedule.
template<ecs::SystemTrait T, ScheduleTrait S>
bool	ContainsSystem (S schedule={}) const noexcept
	Checks if a system of type T is in the specified schedule.
size_t	SystemCount () const noexcept
	Gets the total number of systems across all schedules.
template<ScheduleTrait S>
size_t	SystemCount (S schedule={}) const noexcept
	Gets the number of systems in the specified schedule.
auto	GetSystemStorage () const noexcept -> const std::vector< SystemStorage > &
	Gets const reference to system storage.
auto	GetScheduleOrder () const noexcept -> const std::vector< ScheduleId > &
	Gets the schedule execution order (topologically sorted).
template<StageTrait S>
auto	GetSchedulesInStage () const noexcept -> std::vector< ScheduleId >
	Gets schedules that belong to a specific stage.

Detailed Description

Main scheduler that manages all schedules.

Holds multiple ScheduleExecutors for different execution stages.

Note

Not thread-safe.

Definition at line 263 of file scheduler.hpp.

Constructor & Destructor Documentation

Scheduler() [1/3]

helios::app::details::Scheduler::Scheduler ( )

default

Scheduler() [2/3]

helios::app::details::Scheduler::Scheduler ( const Scheduler &  )

delete

Scheduler() [3/3]

helios::app::details::Scheduler::Scheduler ( Scheduler &&  )

defaultnoexcept

~Scheduler()

helios::app::details::Scheduler::~Scheduler ( )

default

Member Function Documentation

AddSetRunsAfter()

void helios::app::details::Scheduler::AddSetRunsAfter ( SystemSetId  after_id, SystemSetId  before_id  )

inline

Adds a set-level ordering constraint: set A runs after set B.

Convenience wrapper around AddSetRunsBefore(B, A).

Parameters

after_id	Identifier of the set that must run after
before_id	Identifier of the set that must run before

Definition at line 413 of file scheduler.hpp.

{ AddSetRunsBefore(before_id, after_id); }

AddSetRunsBefore()

void helios::app::details::Scheduler::AddSetRunsBefore ( SystemSetId  before_id, SystemSetId  after_id  )

inline

Adds a set-level ordering constraint: set A runs before set B.

All systems that are members of set A must run before systems that are members of set B. This relationship is schedule-agnostic at registration time; it is applied when building graphs for each schedule based on actual system membership in that schedule.

Parameters

before_id	Identifier of the set that must run before
after_id	Identifier of the set that must run after

Definition at line 638 of file scheduler.hpp.

                                                                                   {
  if (before_id == after_id) [[unlikely]] {
    return;
  }
 
  auto before_it = system_sets_.find(before_id);
  if (before_it == system_sets_.end()) {
    // Set may not have been explicitly registered yet; create a minimal entry.
    SystemSetInfo info{};
    info.id = before_id;
    before_it = system_sets_.emplace(before_id, std::move(info)).first;
  }
 
  auto after_it = system_sets_.find(after_id);
  if (after_it == system_sets_.end()) {
    SystemSetInfo info{};
    info.id = after_id;
    after_it = system_sets_.emplace(after_id, std::move(info)).first;
  }
 
  auto& before_info = before_it->second;
  auto& after_info = after_it->second;
 
  // Encode relationship:
  //  - before_info.before_sets contains after_id (before runs before after)
  //  - after_info.after_sets contains before_id
  if (std::ranges::find(before_info.before_sets, after_id) == before_info.before_sets.end()) {
    before_info.before_sets.push_back(after_id);
  }
  if (std::ranges::find(after_info.after_sets, before_id) == after_info.after_sets.end()) {
    after_info.after_sets.push_back(before_id);
  }
}

AddSystem()

template<ecs::SystemTrait T, ScheduleTrait S>

void helios::app::details::Scheduler::AddSystem ( S  schedule = {} )

inline

Adds a system to the specified schedule.

Warning

Triggers assertion if system T is already added to the schedule.

Template Parameters

T	System type
S	Schedule type

Parameters

schedule

Schedule to add system to

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/sub_app.hpp.

Definition at line 565 of file scheduler.hpp.

                                    {
  HELIOS_ASSERT((!ContainsSystem<T>(S{})), "Failed to add system '{}': System already exists in schedule '{}'!",
                ecs::SystemNameOf<T>(), ScheduleNameOf<S>());
 
  RegisterSchedule<S>();
  constexpr ScheduleId schedule_id = ScheduleIdOf<S>();
  constexpr ecs::SystemTypeId system_id = ecs::SystemTypeIdOf<T>();
 
  // Create system storage
  SystemStorage storage{};
  storage.system = std::make_unique<T>();
  storage.info.name = std::string(ecs::SystemNameOf<T>());
  storage.info.type_id = system_id;
  storage.info.access_policy = T::GetAccessPolicy();
  storage.info.execution_count = 0;
 
  const size_t index = system_storage_.size();
  system_storage_.push_back(std::move(storage));
 
  schedules_.at(schedule_id).AddSystem(index);
}

AddSystemToSet()

void helios::app::details::Scheduler::AddSystemToSet ( SystemSetId  set_id, ecs::SystemTypeId  system_id  )

inline

Adds a system to a system set's membership list.

If the set is not present in the registry this call is a no-op.

Parameters

set_id	Identifier of the system set
system_id	Identifier of the system to add

Definition at line 688 of file scheduler.hpp.

                                                                                   {
  const auto it = system_sets_.find(set_id);
  if (it == system_sets_.end()) {
    return;
  }
 
  auto& members = it->second.member_systems;
  if (std::ranges::find(members, system_id) == members.end()) {
    members.push_back(system_id);
  }
}

AppendSystemOrderingMetadata()

template<ecs::SystemTrait T, ScheduleTrait S>

void helios::app::details::Scheduler::AppendSystemOrderingMetadata ( S  schedule, std::span< const ecs::SystemTypeId >  before, std::span< const ecs::SystemTypeId >  after  )

inline

Appends system ordering constraints to a system's metadata in a specific schedule.

This updates SystemInfo.before_systems and SystemInfo.after_systems for the given system type within the specified schedule. If the system has not been added to the schedule yet, this call is a no-op.

Template Parameters

T	System type
S	Schedule type

Parameters

schedule	Schedule where the system is registered
before	Systems that must run after T in this schedule
after	Systems that must run before T in this schedule

Definition at line 701 of file scheduler.hpp.

                                                                                          {
  constexpr ScheduleId schedule_id = ScheduleIdOf<S>();
  constexpr ecs::SystemTypeId system_id = ecs::SystemTypeIdOf<T>();
 
  // Find the schedule
  const auto schedule_it = schedules_.find(schedule_id);
  if (schedule_it == schedules_.end()) {
    return;
  }
 
  // Find the system index within this specific schedule
  const auto index_opt = schedule_it->second.FindSystemIndexByType(system_id, system_storage_);
  if (!index_opt.has_value()) {
    return;
  }
 
  auto& info = system_storage_[index_opt.value()].info;
  if (!before.empty()) {
#ifdef HELIOS_CONTAINERS_RANGES_AVALIABLE
    info.before_systems.append_range(before);
#else
    info.before_systems.insert(info.before_systems.end(), before.begin(), before.end());
#endif
  }
  if (!after.empty()) {
#ifdef HELIOS_CONTAINERS_RANGES_AVALIABLE
    info.after_systems.append_range(after);
#else
    info.after_systems.insert(info.after_systems.end(), after.begin(), after.end());
#endif
  }
}

AppendSystemSetMetadata()

template<ecs::SystemTrait T, ScheduleTrait S>

void helios::app::details::Scheduler::AppendSystemSetMetadata ( S  schedule, std::span< const SystemSetId >  sets  )

inline

Appends system set membership to a system's metadata in a specific schedule.

This updates SystemInfo.system_sets for the given system type within the specified schedule. If the system has not been added to the schedule yet, this call is a no-op.

Template Parameters

T	System type
S	Schedule type

Parameters

schedule	Schedule where the system is registered
sets	System set identifiers to append

Definition at line 736 of file scheduler.hpp.

                                                                                   {
  if (sets.empty()) [[unlikely]] {
    return;
  }
 
  constexpr ScheduleId schedule_id = ScheduleIdOf<S>();
  constexpr ecs::SystemTypeId system_id = ecs::SystemTypeIdOf<T>();
 
  // Find the schedule
  const auto schedule_it = schedules_.find(schedule_id);
  if (schedule_it == schedules_.end()) {
    return;
  }
 
  // Find the system index within this specific schedule
  const auto index_opt = schedule_it->second.FindSystemIndexByType(system_id, system_storage_);
  if (!index_opt.has_value()) {
    return;
  }
 
  auto& info = system_storage_[index_opt.value()].info;
#ifdef HELIOS_CONTAINERS_RANGES_AVALIABLE
  info.system_sets.append_range(sets);
#else
  info.system_sets.insert(info.system_sets.end(), sets.begin(), sets.end());
#endif
}

BuildAllGraphs()

void helios::app::details::Scheduler::BuildAllGraphs

(

ecs::World &

world

)

Builds execution graphs for all schedules.

Should be called after all systems are added and before execution. This method also propagates system set ordering constraints into explicit system-to-system ordering edges for each schedule.

Parameters

world

World to execute systems on

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/sub_app.hpp.

Definition at line 60 of file scheduler.cpp.

                                              {
  schedule_order_.clear();
 
  const auto all_schedules = CollectAllScheduleIds();
  if (all_schedules.empty()) {
    return;
  }
 
  auto [adjacency, in_degree] = BuildScheduleDependencyGraph(all_schedules);
  schedule_order_ = TopologicalSort(all_schedules, adjacency, in_degree);
 
  // Build execution graphs for all schedules
  for (auto& [_, schedule] : schedules_) {
    schedule.BuildExecutionGraph(world, system_storage_, system_sets_);
  }
}

Clear()

void helios::app::details::Scheduler::Clear ( )

inline

Clears all schedules and systems.

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/sub_app.hpp.

Definition at line 508 of file scheduler.hpp.

                             {
  system_storage_.clear();
  for (auto& [id, schedule] : schedules_) {
    schedule.Clear();
  }
  schedules_.clear();
  schedule_constraints_.clear();
  schedule_order_.clear();
  system_sets_.clear();
}

ContainsSystem() [1/2]

template<ecs::SystemTrait T>

bool helios::app::details::Scheduler::ContainsSystem ( ) const

inlinenoexcept

Checks if a system of type T is in any schedule.

Template Parameters

T	System type

Returns

True if system is present, false otherwise

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/sub_app.hpp.

Definition at line 774 of file scheduler.hpp.

                                                     {
  constexpr ecs::SystemTypeId system_id = ecs::SystemTypeIdOf<T>();
  // Check if any schedule contains a system of this type
  return std::ranges::any_of(schedules_, [this, system_id](const auto& pair) {
    return pair.second.ContainsSystemOfType(system_id, system_storage_);
  });
}

ContainsSystem() [2/2]

template<ecs::SystemTrait T, ScheduleTrait S>

bool helios::app::details::Scheduler::ContainsSystem ( S  schedule = {} ) const

inlinenoexcept

Checks if a system of type T is in the specified schedule.

Template Parameters

T	System type
S	Schedule type

Parameters

schedule

Schedule to check

Returns

True if system is present, false otherwise

Definition at line 783 of file scheduler.hpp.

                                                        {
  constexpr ScheduleId schedule_id = ScheduleIdOf<S>();
  const auto it = schedules_.find(schedule_id);
  if (it == schedules_.end()) {
    return false;
  }
 
  constexpr ecs::SystemTypeId system_id = ecs::SystemTypeIdOf<T>();
  return it->second.ContainsSystemOfType(system_id, system_storage_);
}

ExecuteSchedule()

template<ScheduleTrait S>

void helios::app::details::Scheduler::ExecuteSchedule ( ecs::World &  world, async::Executor &  executor  )

inline

Executes all systems in the specified schedule.

Template Parameters

S	Schedule type

Parameters

world	World to execute systems on
executor	Async executor for parallel execution

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/sub_app.hpp.

Definition at line 588 of file scheduler.hpp.

                                                                               {
  constexpr ScheduleId schedule_id = ScheduleIdOf<S>();
  ExecuteScheduleById(schedule_id, world, executor);
}

ExecuteScheduleById()

void helios::app::details::Scheduler::ExecuteScheduleById ( ScheduleId  schedule_id, ecs::World &  world, async::Executor &  executor  )

inline

Executes all systems in the specified schedule by ID.

Parameters

schedule_id	Schedule ID to execute
world	World to execute systems on
executor	Async executor for parallel execution

Definition at line 593 of file scheduler.hpp.

                                                                                                           {
  const auto it = schedules_.find(schedule_id);
  if (it == schedules_.end()) [[unlikely]] {
    return;  // Schedule not registered or has no systems
  }
 
  it->second.Execute(world, executor, system_storage_);
 
  // After each schedule, merge all commands into world's main queue
  MergeCommandsToWorld(world);
}

ExecuteStage()

template<StageTrait S>

void helios::app::details::Scheduler::ExecuteStage ( ecs::World &  world, async::Executor &  executor  )

inline

Executes all schedules in the specified stage.

Executes schedules in topologically sorted order based on Before/After relationships.

Template Parameters

S	Stage type (must satisfy StageTrait)

Parameters

world	World to execute systems on
executor	Async executor for parallel execution

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/sub_app.hpp.

Definition at line 621 of file scheduler.hpp.

                                                                            {
  constexpr ScheduleId stage_id = ScheduleIdOf<S>();
 
  // Execute all schedules that belong to this stage in topological order
  for (const ScheduleId schedule_id : schedule_order_) {
    const auto constraint_it = schedule_constraints_.find(schedule_id);
    if (constraint_it == schedule_constraints_.end()) {
      continue;
    }
 
    // Check if this schedule belongs to this stage
    if (constraint_it->second.stage_id == stage_id) {
      ExecuteScheduleById(schedule_id, world, executor);
    }
  }
}

GetOrRegisterSystemSet()

template<SystemSetTrait Set>

SystemSetInfo & helios::app::details::Scheduler::GetOrRegisterSystemSet ( )

inline

Gets or registers a system set in the global registry.

If the set is not present, it will be created and initialized with its static name and ID.

Template Parameters

Set	System set type

Returns

Reference to the SystemSetInfo for this set

Definition at line 673 of file scheduler.hpp.

                                                        {
  constexpr SystemSetId id = SystemSetIdOf<Set>();
  const auto it = system_sets_.find(id);
  if (it != system_sets_.end()) {
    return it->second;
  }
 
  SystemSetInfo info{};
  info.id = id;
  info.name = std::string(SystemSetNameOf<Set>());
 
  const auto [insert_it, _] = system_sets_.emplace(id, std::move(info));
  return insert_it->second;
}

GetScheduleOrder()

auto helios::app::details::Scheduler::GetScheduleOrder ( ) const -> const std::vector<ScheduleId>&

inlinenoexcept

Gets the schedule execution order (topologically sorted).

Returns

Const reference to vector of Schedule IDs in execution order

Definition at line 458 of file scheduler.hpp.

{ return schedule_order_; }

GetSchedulesInStage()

template<StageTrait S>

auto helios::app::details::Scheduler::GetSchedulesInStage ( ) const -> std::vector<ScheduleId>

inlinenoexcept

Gets schedules that belong to a specific stage.

Template Parameters

S	Stage type

Returns

Vector of schedule IDs that execute within the stage

Definition at line 805 of file scheduler.hpp.

                                                                                   {
  constexpr ScheduleId stage_id = ScheduleIdOf<S>();
  std::vector<ScheduleId> result;
 
  // Iterate through all schedules in topological order and collect those belonging to this stage
  for (const ScheduleId schedule_id : schedule_order_) {
    const auto constraint_it = schedule_constraints_.find(schedule_id);
    if (constraint_it == schedule_constraints_.end()) {
      continue;
    }
 
    // Check if this schedule belongs to this stage
    if (constraint_it->second.stage_id == stage_id) {
      result.push_back(schedule_id);
    }
  }
 
  return result;
}

GetSystemStorage()

auto helios::app::details::Scheduler::GetSystemStorage ( ) const -> const std::vector<SystemStorage>&

inlinenoexcept

Gets const reference to system storage.

Returns

Const reference to vector of SystemStorage

Definition at line 452 of file scheduler.hpp.

{ return system_storage_; }

MergeCommandsToWorld()

void helios::app::details::Scheduler::MergeCommandsToWorld ( ecs::World &  world )

inline

Merges all system local commands into the world's main command queue.

Should be called after Extract schedule to flush all pending commands.

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/sub_app.hpp.

Definition at line 605 of file scheduler.hpp.

                                                           {
  for (auto& storage : system_storage_) {
    auto& commands = storage.local_storage.GetCommands();
    if (!commands.empty()) {
      world.MergeCommands(std::move(commands));
    }
  }
}

operator=() [1/2]

Scheduler & helios::app::details::Scheduler::operator= ( const Scheduler &  )

delete

operator=() [2/2]

Scheduler & helios::app::details::Scheduler::operator= ( Scheduler &&  )

defaultnoexcept

RegisterOrdering()

template<ecs::SystemTrait T, ScheduleTrait S>

void helios::app::details::Scheduler::RegisterOrdering ( S  schedule, SystemOrdering  ordering  )

inline

Registers ordering constraint for a system.

Template Parameters

T	System type
S	Schedule type

Parameters

schedule	Schedule to register ordering for
ordering	Ordering constraints

Definition at line 556 of file scheduler.hpp.

                                                                    {
  RegisterSchedule<S>();
  constexpr ScheduleId schedule_id = ScheduleIdOf<S>();
  constexpr ecs::SystemTypeId system_id = ecs::SystemTypeIdOf<T>();
 
  schedules_.at(schedule_id).RegisterOrdering(system_id, std::move(ordering));
}

RegisterSchedule()

template<ScheduleTrait S>

void helios::app::details::Scheduler::RegisterSchedule ( )

inline

Registers a schedule type.

Template Parameters

T	Schedule type

Definition at line 520 of file scheduler.hpp.

                                        {
  constexpr ScheduleId schedule_id = ScheduleIdOf<S>();
  if (schedules_.contains(schedule_id)) [[unlikely]] {
    return;  // Already registered
  }
 
  schedules_.emplace(schedule_id, ScheduleExecutor(schedule_id));
 
  // Store schedule ordering constraints
  ScheduleOrdering ordering;
 
  // Extract Before constraints from schedule type
  if constexpr (ScheduleWithBeforeTrait<S>) {
    constexpr auto before = ScheduleBeforeOf<S>();
    ordering.before.reserve(before.size());
    for (const ScheduleId id : before) {
      ordering.before.push_back(id);
    }
  }
 
  // Extract After constraints from schedule type
  if constexpr (ScheduleWithAfterTrait<S>) {
    constexpr auto after = ScheduleAfterOf<S>();
    ordering.after.reserve(after.size());
    for (const ScheduleId id : after) {
      ordering.after.push_back(id);
    }
  }
 
  // Store stage membership
  ordering.stage_id = ScheduleStageOf<S>();
 
  schedule_constraints_[schedule_id] = std::move(ordering);
}

ResetFrameAllocators()

void helios::app::details::Scheduler::ResetFrameAllocators ( )

inlinenoexcept

Resets all system frame allocators.

Call this at frame boundaries to reclaim all temporary per-system allocations. Should typically be called at the end of App::Update() after all schedules have executed.

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/sub_app.hpp.

Definition at line 614 of file scheduler.hpp.

                                                     {
  for (auto& storage : system_storage_) {
    storage.local_storage.ResetFrameAllocator();
  }
}

SystemCount() [1/2]

size_t helios::app::details::Scheduler::SystemCount ( ) const

inlinenoexcept

Gets the total number of systems across all schedules.

Returns

Total number of systems

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/sub_app.hpp.

Definition at line 437 of file scheduler.hpp.

{ return system_storage_.size(); }

SystemCount() [2/2]

template<ScheduleTrait S>

size_t helios::app::details::Scheduler::SystemCount ( S  schedule = {} ) const

inlinenoexcept

Gets the number of systems in the specified schedule.

Template Parameters

S	Schedule type

Parameters

schedule

Schedule to query

Returns

Number of systems in the schedule

Definition at line 795 of file scheduler.hpp.

                                                       {
  constexpr ScheduleId schedule_id = ScheduleIdOf<S>();
  const auto it = schedules_.find(schedule_id);
  if (it == schedules_.end()) [[unlikely]] {
    return 0;
  }
  return it->second.SystemCount();
}