Helios Engine
A modular ECS based data-oriented C++23 game engine framework
Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | Friends | List of all members
helios::ecs::Schedule Class Reference

A collection of systems, sets, and run conditions with ordering constraints. More...

#include <schedule.hpp>

Public Member Functions

 Schedule ()=default
 Schedule (std::string name)
 Constructs a schedule with the given name.
 Schedule (const Schedule &)=delete
 Schedule (Schedule &&) noexcept=default
 ~Schedule ()=default
Schedule & operator= (const Schedule &)=delete
Schedule & operator= (Schedule &&) noexcept=default
void Run (World &world, Executor &executor)
 Submits the compiled schedule for execution using the provided executor.
void Run (World &world)
 Submits the compiled schedule for execution using the stored executor.
void RunAndWait (World &world, Executor &executor)
 Executes the compiled schedule and blocks until completion.
void RunAndWait (World &world)
 Executes the compiled schedule using the stored executor and blocks until completion.
void ApplyDeferred (World &world)
 Flushes world state and applies all pending system-local data.
auto Build () -> ScheduleResult< void >
 Compiles the schedule into an executable plan.
void Clear ()
 Clears all systems, sets, and compiled state from this schedule.
template<FunctorSystemTrait T>
SystemHandle Add (T &&system, SystemLocalDataOptions options={})
 Adds a param-style functor system to the schedule.
template<SystemTrait T>
SystemHandle Add (std::string name, T &&system, SystemLocalDataOptions options={})
 Adds a param-style system to the schedule with an explicit name.
template<FunctorSystemTrait... Ts>
requires (sizeof...(Ts) > 1)
SystemGroupHandle Add (Ts &&... systems)
 Adds multiple param-style functor systems as a system group.
SystemHandle Add (std::string name, SystemCallable system, AccessPolicy policy={}, SystemLocalDataOptions options={})
 Adds a callable system to the schedule with explicit name and access policy.
SystemSetHandle Set (SystemSetId id)
 Gets or creates a system set with the given identifier.
template<SystemSetTrait T>
SystemSetHandle Set (const T &={})
 Gets or creates a system set with the given label type.
void SetExecutor (std::unique_ptr< Executor > executor) noexcept
 Sets the executor for this schedule.
void SetName (std::string name) noexcept
 Sets the human-readable schedule name.
bool IsDirty () const noexcept
 Checks whether the schedule requires recompilation.
bool HasPendingLocalData () const noexcept
 Checks whether any system still has unapplied local commands or messages.
const std::string & GetName () const noexcept
 Gets the human-readable schedule name.
ScheduleSettings & Settings () noexcept
 Gets scheduler-local settings for this schedule.
const ScheduleSettings & Settings () const noexcept
 Gets scheduler-local settings for this schedule.
Executor * GetExecutor () noexcept
 Gets the stored executor.
const Executor * GetExecutor () const noexcept
 Gets the stored executor.

Static Public Member Functions

template<ScheduleTrait T>
static Schedule From (const T &schedule={})
 Creates a schedule named after the given label type.

Friends

class MainThreadExecutor
class SingleThreadedExecutor
class MultiThreadedExecutor
class SystemHandle
class SystemSetHandle
class SystemGroupHandle

Detailed Description

A collection of systems, sets, and run conditions with ordering constraints.

Compile the schedule with Build() to produce an executable plan, then call Run() with an executor to execute it. Adding, removing, or modifying any configuration invalidates the plan and requires recompilation.

Definition at line 182 of file schedule.hpp.

Constructor & Destructor Documentation

◆ Schedule() [1/4]

helios::ecs::Schedule::Schedule ( )
default

◆ Schedule() [2/4]

helios::ecs::Schedule::Schedule ( std::string name)
inlineexplicit

Constructs a schedule with the given name.

Parameters
nameHuman-readable schedule name

Definition at line 190 of file schedule.hpp.

◆ Schedule() [3/4]

helios::ecs::Schedule::Schedule ( const Schedule & )
delete

◆ Schedule() [4/4]

helios::ecs::Schedule::Schedule ( Schedule && )
defaultnoexcept

◆ ~Schedule()

helios::ecs::Schedule::~Schedule ( )
default

Member Function Documentation

◆ Add() [1/4]

SystemHandle helios::ecs::Schedule::Add ( std::string name,
SystemCallable system,
AccessPolicy policy = {},
SystemLocalDataOptions options = {} )
inline

Adds a callable system to the schedule with explicit name and access policy.

Parameters
nameSystem name
systemCallable that accepts (World&, SystemLocalData&)
policyAccess policy for the system
optionsLocal data options
Returns
Handle for further configuration

Definition at line 631 of file schedule.hpp.

◆ Add() [2/4]

template<SystemTrait T>
SystemHandle helios::ecs::Schedule::Add ( std::string name,
T && system,
SystemLocalDataOptions options = {} )
inline

Adds a param-style system to the schedule with an explicit name.

Auto-deduces the access policy from the system's parameter types and derives the SystemId from the provided name. Required for lambdas and recommended when multiple instances of the same functor type need distinct identities within a single schedule.

Template Parameters
TSystem type satisfying SystemTrait
Parameters
nameHuman-readable system name
systemSystem instance
optionsLocal data options
Returns
Handle for further configuration

Definition at line 606 of file schedule.hpp.

◆ Add() [3/4]

template<FunctorSystemTrait T>
SystemHandle helios::ecs::Schedule::Add ( T && system,
SystemLocalDataOptions options = {} )
inline

Adds a param-style functor system to the schedule.

Auto-deduces the access policy from the system's parameter types and derives the system name and SystemId from the functor type. Lambdas are rejected; use Add(std::string, T&&, ...) to register them with an explicit name.

Template Parameters
TSystem type satisfying FunctorSystemTrait
Parameters
systemSystem instance
optionsLocal data options
Returns
Handle for further configuration

Definition at line 596 of file schedule.hpp.

◆ Add() [4/4]

template<FunctorSystemTrait... Ts>
requires (sizeof...(Ts) > 1)
SystemGroupHandle helios::ecs::Schedule::Add ( Ts &&... systems)
inline

Adds multiple param-style functor systems as a system group.

Each system is added to the schedule and assigned to a unique anonymous group. The returned handle configures all members collectively and can assign them to a named set via InSet. Lambdas must be registered individually with explicit names.

Template Parameters
TsSystem types satisfying FunctorSystemTrait
Parameters
systemsSystem instances
Returns
Handle for configuring the system group

Definition at line 618 of file schedule.hpp.

◆ ApplyDeferred()

void helios::ecs::Schedule::ApplyDeferred ( World & world)

Flushes world state and applies all pending system-local data.

Calls World::Flush() (entity reservations and World::EnqueueCommand queue), then runs SystemLocalData::Update for every system in this schedule. Required after Run() once the executor has finished; called automatically by RunAndWait().

Parameters
worldWorld to flush and update

Definition at line 106 of file schedule.cpp.

◆ Build()

auto helios::ecs::Schedule::Build ( ) -> ScheduleResult< void >
nodiscard

Compiles the schedule into an executable plan.

Validates for cycles, unknown references, and ambiguous access. Produces a topological order and conflict matrix for parallel execution.

Returns
Empty on success, or a ScheduleError with diagnostics

Definition at line 117 of file schedule.cpp.

◆ Clear()

void helios::ecs::Schedule::Clear ( )

Clears all systems, sets, and compiled state from this schedule.

Preserves Settings() and the stored executor for reuse.

Definition at line 160 of file schedule.cpp.

◆ From()

template<ScheduleTrait T>
Schedule helios::ecs::Schedule::From ( const T & schedule = {})
inlinestaticnodiscard

Creates a schedule named after the given label type.

Template Parameters
TSchedule type satisfying ScheduleTrait
Parameters
scheduleSchedule type instance
Returns
Schedule with name derived from the type

Definition at line 206 of file schedule.hpp.

◆ GetExecutor() [1/2]

const Executor * helios::ecs::Schedule::GetExecutor ( ) const
inlinenodiscardnoexcept

Gets the stored executor.

Returns
Const pointer to the stored executor, or nullptr if not set

Definition at line 417 of file schedule.hpp.

◆ GetExecutor() [2/2]

Executor * helios::ecs::Schedule::GetExecutor ( )
inlinenodiscardnoexcept

Gets the stored executor.

Returns
Pointer to the stored executor, or nullptr if not set

Definition at line 411 of file schedule.hpp.

◆ GetName()

const std::string & helios::ecs::Schedule::GetName ( ) const
inlinenodiscardnoexcept

Gets the human-readable schedule name.

Returns
Schedule name

Definition at line 391 of file schedule.hpp.

◆ HasPendingLocalData()

bool helios::ecs::Schedule::HasPendingLocalData ( ) const
inlinenodiscardnoexcept

Checks whether any system still has unapplied local commands or messages.

Returns
True if ApplyDeferred is still required before the next Run()

Definition at line 381 of file schedule.hpp.

◆ IsDirty()

bool helios::ecs::Schedule::IsDirty ( ) const
inlinenodiscardnoexcept

Checks whether the schedule requires recompilation.

Returns
True if any configuration has changed since the last Build()

Definition at line 374 of file schedule.hpp.

◆ operator=() [1/2]

Schedule & helios::ecs::Schedule::operator= ( const Schedule & )
delete

◆ operator=() [2/2]

Schedule & helios::ecs::Schedule::operator= ( Schedule && )
defaultnoexcept

◆ Run() [1/2]

void helios::ecs::Schedule::Run ( World & world)
inline

Submits the compiled schedule for execution using the stored executor.

Same semantics as Run(world, executor); see that overload.

Warning
Triggers assertion if the schedule has not been built, is dirty, no executor has been set, or still has unapplied local data from a prior Run().
Parameters
worldWorld to pass to each system

Definition at line 567 of file schedule.hpp.

◆ Run() [2/2]

void helios::ecs::Schedule::Run ( World & world,
Executor & executor )

Submits the compiled schedule for execution using the provided executor.

Resets per-system arenas and submits systems for execution. Does not call World::Flush() or SystemLocalData::Update. When execution finishes (Executor::Wait() on the same executor), call ApplyDeferred(world) before the next Run() — otherwise pending commands and messages are discarded on the next arena reset.

Warning
Triggers assertion if the schedule has not been built, is dirty, or still has unapplied local data from a prior Run().
Parameters
worldWorld to pass to each system
executorExecutor strategy to use

Definition at line 55 of file schedule.cpp.

◆ RunAndWait() [1/2]

void helios::ecs::Schedule::RunAndWait ( World & world)
inline

Executes the compiled schedule using the stored executor and blocks until completion.

Same semantics as RunAndWait(world, executor); see that overload.

Warning
Triggers assertion if the schedule has not been built, is dirty, or no executor has been set.
Parameters
worldWorld to pass to each system

Definition at line 581 of file schedule.hpp.

◆ RunAndWait() [2/2]

void helios::ecs::Schedule::RunAndWait ( World & world,
Executor & executor )

Executes the compiled schedule and blocks until completion.

Equivalent to Run(), waiting on the executor, then ApplyDeferred(world).

Warning
Triggers assertion if the schedule has not been built or is dirty.
Parameters
worldWorld to pass to each system
executorExecutor strategy to use

Definition at line 80 of file schedule.cpp.

◆ Set() [1/2]

template<SystemSetTrait T>
SystemSetHandle helios::ecs::Schedule::Set ( const T & = {})
inlinenodiscard

Gets or creates a system set with the given label type.

Template Parameters
TSet type satisfying SystemSetTrait
Returns
Handle for configuring the set

Definition at line 351 of file schedule.hpp.

◆ Set() [2/2]

SystemSetHandle helios::ecs::Schedule::Set ( SystemSetId id)
inlinenodiscard

Gets or creates a system set with the given identifier.

Parameters
idSet identifier
Returns
Handle for configuring the set

Definition at line 642 of file schedule.hpp.

◆ SetExecutor()

void helios::ecs::Schedule::SetExecutor ( std::unique_ptr< Executor > executor)
inlinenoexcept

Sets the executor for this schedule.

Parameters
executorExecutor to use when Run/AndWait is called without an explicit executor

Definition at line 360 of file schedule.hpp.

◆ SetName()

void helios::ecs::Schedule::SetName ( std::string name)
inlinenoexcept

Sets the human-readable schedule name.

Parameters
nameSchedule name

Definition at line 368 of file schedule.hpp.

◆ Settings() [1/2]

const ScheduleSettings & helios::ecs::Schedule::Settings ( ) const
inlinenodiscardnoexcept

Gets scheduler-local settings for this schedule.

Returns
Const reference to the settings

Definition at line 403 of file schedule.hpp.

◆ Settings() [2/2]

ScheduleSettings & helios::ecs::Schedule::Settings ( )
inlinenodiscardnoexcept

Gets scheduler-local settings for this schedule.

Returns
Mutable reference to the settings

Definition at line 397 of file schedule.hpp.

◆ MainThreadExecutor

friend class MainThreadExecutor
friend

Definition at line 559 of file schedule.hpp.

◆ MultiThreadedExecutor

friend class MultiThreadedExecutor
friend

Definition at line 561 of file schedule.hpp.

◆ SingleThreadedExecutor

friend class SingleThreadedExecutor
friend

Definition at line 560 of file schedule.hpp.

◆ SystemGroupHandle

friend class SystemGroupHandle
friend

Definition at line 564 of file schedule.hpp.

◆ SystemHandle

friend class SystemHandle
friend

Definition at line 562 of file schedule.hpp.

◆ SystemSetHandle

friend class SystemSetHandle
friend

Definition at line 563 of file schedule.hpp.