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

A sub-application with its own ECS world and scheduler. More...

#include <sub_app.hpp>

Public Types

using RunnerFn = std::function<void(SubApp&, async::Executor&)>
using ExtractFn = std::function<void(const ecs::World&, ecs::World&)>

Public Member Functions

 SubApp ()
 Constructs a sub-app with built-in schedules registered.
 SubApp (std::string name)
 Constructs a sub-app with the given name and built-in schedules registered.
 SubApp (const SubApp &)=delete
 SubApp (SubApp &&other) noexcept
 Move-constructs a sub-app from another.
 ~SubApp ()=default
SubApp & operator= (const SubApp &)=delete
SubApp & operator= (SubApp &&other) noexcept
 Move-assigns a sub-app from another.
void Clear ()
 Clears the sub-app world, ECS scheduler, and extract function.
void Update (async::Executor &executor)
 Runs the configured update stage.
void Extract (const ecs::World &main_world, bool allow_while_updating=false)
 Copies data from the main world into this sub-app's world.
void WaitUntilFullyIdle () const noexcept
 Blocks until no update is in flight.
void BuildScheduler (async::Executor &executor)
 Builds all ECS schedules when any are dirty.
ecs::ScheduleOrdering AddSchedule (ecs::ScheduleTypeId id, ecs::Schedule &&schedule)
 Adds a schedule with the given label type id.
template<ecs::ScheduleTrait T>
ecs::ScheduleOrdering AddSchedule (const T &label, ecs::Schedule &&schedule)
 Adds a schedule with the given label type.
template<ecs::ScheduleTrait T>
auto InitSchedule (this auto &&self, const T &label={}) -> decltype(std::forward< decltype(self)>(self))
 Creates an empty schedule for the label when it does not exist.
template<ecs::ScheduleTrait L, typename F>
requires std::invocable<F, ecs::Schedule&>
auto EditSchedule (this auto &&self, const L &label, const F &fn) -> decltype(std::forward< decltype(self)>(self))
 Mutates an existing schedule in place.
template<ecs::ScheduleTrait L, ecs::FunctorSystemTrait S>
ecs::SystemHandle AddSystem (const L &label, S &&system, ecs::SystemLocalDataOptions options={})
 Adds a functor system to the given schedule.
template<ecs::ScheduleTrait L, ecs::SystemTrait S>
ecs::SystemHandle AddSystem (const L &label, std::string name, S &&system, ecs::SystemLocalDataOptions options={})
 Adds a system to the given schedule with an explicit name.
template<ecs::ScheduleTrait L, ecs::FunctorSystemTrait... Systems>
requires (sizeof...(Systems) > 1)
ecs::SystemGroupHandle AddSystems (const L &label, Systems &&... systems)
 Adds multiple functor systems to the same schedule as a system group.
template<ecs::ScheduleTrait L, ecs::SystemSetTrait S>
ecs::SystemSetHandle ConfigureSet (const L &label={}, const S &set={})
 Gets or creates a system set in the given schedule.
template<ecs::ResourceTrait... Ts>
auto InsertResources (this auto &&self, Ts &&... resources) -> decltype(std::forward< decltype(self)>(self))
 Inserts or replaces resources in this sub-app's world.
template<ecs::ResourceTrait... Ts>
auto TryInsertResources (this auto &&self, Ts &&... resources) -> decltype(std::forward< decltype(self)>(self))
 Inserts resources only when no instance exists yet.
template<ecs::AnyMessageTrait... Ts>
requires (sizeof...(Ts) > 0)
auto AddMessages (this auto &&self) -> decltype(std::forward< decltype(self)>(self))
 Registers multiple message types on this sub-app's world.
void SetName (std::string name) noexcept
 Sets the human-readable sub-app name.
const std::string & GetName () const noexcept
 Gets the human-readable sub-app name.
void SetRunner (RunnerFn runner) noexcept
 Sets the function invoked each frame to run this sub-app's update pass.
template<typename F>
requires std::invocable<F, const ecs::World&, ecs::World&>
void SetExtractFunction (F &&fn)
 Sets the function invoked by Extract.
void SetAllowOverlappingUpdates (bool allow_overlapping_updates) noexcept
 Sets whether extraction may be skipped while an update is in flight.
void SetMaxExtractionSkips (size_t max_skips) noexcept
 Sets the maximum consecutive extraction skips while updating.
void SetAsync (bool is_async) noexcept
 Sets whether this sub-app runs updates on a background loop.
void SetUpdateStage (ecs::StageTypeIndex index) noexcept
 Sets which stage label Update executes.
template<ecs::StageTrait T>
void SetUpdateStage (const T &stage={}) noexcept
 Sets which stage label Update executes.
template<ecs::ScheduleTrait T>
ecs::Schedule * TryGetSchedule (const T &label={})
 Tries to get the schedule for a label.
template<ecs::ScheduleTrait T>
const ecs::Schedule * TryGetSchedule (const T &label={}) const
 Tries to get the schedule for a label.
bool ShouldExit () const noexcept
 Returns whether this sub-app should stop its update loop.
bool IsUpdating () const noexcept
 Returns whether an update is in flight.
bool AllowsOverlappingUpdates () const noexcept
 Returns whether extraction may be skipped while updating.
bool IsAsync () const noexcept
 Returns whether this sub-app uses a background update loop.
size_t MaxExtractionSkips () const noexcept
 Returns the configured maximum consecutive extraction skips.
ecs::World & GetWorld () noexcept
 Gets this sub-app's ECS world.
const ecs::World & GetWorld () const noexcept
 Gets this sub-app's ECS world.
ecs::Scheduler & GetScheduler () noexcept
 Gets this sub-app's ECS schedule collection.
const ecs::Scheduler & GetScheduler () const noexcept
 Gets this sub-app's ECS schedule collection.

Static Public Member Functions

template<SubAppTrait T>
static SubApp From (const T &sub_app={})
 Creates a sub-app named after the given label type.

Friends

class App
class Scheduler

Detailed Description

A sub-application with its own ECS world and scheduler.

Use SetExtractFunction to copy data from the main world before each update. Overlapping sub-apps may skip extraction while an update is in flight, up to kMaxOverlappingUpdates consecutive frames (0 = unlimited). Async sub-apps run their update pass on a background loop; extraction runs every main frame and thread safety is the user's responsibility.

Warning
Async sub-apps must use a looping runner such as RunDefaultSubApp or RunFixedSubApp via SetRunner() before initialization. The default RunOnceSubApp runs a single update pass and is intended for blocking sub-apps.
Note
Partially thread-safe.

Definition at line 144 of file sub_app.hpp.

Member Typedef Documentation

◆ ExtractFn

using helios::app::SubApp::ExtractFn = std::function<void(const ecs::World&, ecs::World&)>

Definition at line 152 of file sub_app.hpp.

◆ RunnerFn

using helios::app::SubApp::RunnerFn = std::function<void(SubApp&, async::Executor&)>

Definition at line 151 of file sub_app.hpp.

Constructor & Destructor Documentation

◆ SubApp() [1/4]

helios::app::SubApp::SubApp ( )

Constructs a sub-app with built-in schedules registered.

Definition at line 25 of file sub_app.cpp.

◆ SubApp() [2/4]

helios::app::SubApp::SubApp ( std::string name)
explicit

Constructs a sub-app with the given name and built-in schedules registered.

Parameters
nameHuman-readable sub-app name

Definition at line 29 of file sub_app.cpp.

◆ SubApp() [3/4]

helios::app::SubApp::SubApp ( const SubApp & )
delete

◆ SubApp() [4/4]

helios::app::SubApp::SubApp ( SubApp && other)
inlinenoexcept

Move-constructs a sub-app from another.

Warning
Triggers assertion if an update is in progress.
Parameters
otherThe sub-app to move from

Definition at line 638 of file sub_app.hpp.

◆ ~SubApp()

helios::app::SubApp::~SubApp ( )
default

Member Function Documentation

◆ AddMessages()

template<ecs::AnyMessageTrait... Ts>
requires (sizeof...(Ts) > 0)
auto helios::app::SubApp::AddMessages ( this auto && self) -> decltype(std::forward< decltype(self)>(self))
inline

Registers multiple message types on this sub-app's world.

Note
Not thread-safe.
Warning
Triggers assertion if an update is in progress.
Template Parameters
TsMessage types
Returns
Reference to this sub-app for chaining

Definition at line 762 of file sub_app.hpp.

◆ AddSchedule() [1/2]

template<ecs::ScheduleTrait T>
ecs::ScheduleOrdering helios::app::SubApp::AddSchedule ( const T & label,
ecs::Schedule && schedule )
inline

Adds a schedule with the given label type.

Note
Not thread-safe.
Warning
Triggers assertion if an update is in progress.
Template Parameters
TSchedule label type
Parameters
scheduleSchedule instance
labelLabel value
Returns
Ordering handle for configuring placement

Definition at line 259 of file sub_app.hpp.

◆ AddSchedule() [2/2]

ecs::ScheduleOrdering helios::app::SubApp::AddSchedule ( ecs::ScheduleTypeId id,
ecs::Schedule && schedule )
inline

Adds a schedule with the given label type id.

Note
Not thread-safe.
Warning
Triggers assertion if an update is in progress.
Parameters
idSchedule type id
scheduleSchedule instance
Returns
Ordering handle for configuring placement

Definition at line 244 of file sub_app.hpp.

◆ AddSystem() [1/2]

template<ecs::ScheduleTrait L, ecs::FunctorSystemTrait S>
ecs::SystemHandle helios::app::SubApp::AddSystem ( const L & label,
S && system,
ecs::SystemLocalDataOptions options = {} )
inline

Adds a functor system to the given schedule.

Derives name and SystemId from the functor type. Lambdas are rejected; use the AddSystem(label, name, system) overload.

Note
Not thread-safe.
Warning
Triggers assertion if an update is in progress.
Template Parameters
LSchedule label type
SSystem type satisfying FunctorSystemTrait
Parameters
labelTarget schedule label
systemSystem instance
optionsLocal data options for the system
Returns
Handle for ordering and run conditions

Definition at line 303 of file sub_app.hpp.

◆ AddSystem() [2/2]

template<ecs::ScheduleTrait L, ecs::SystemTrait S>
ecs::SystemHandle helios::app::SubApp::AddSystem ( const L & label,
std::string name,
S && system,
ecs::SystemLocalDataOptions options = {} )
inline

Adds a system to the given schedule with an explicit name.

Required for lambdas. Derives the SystemId from the provided name, enabling multiple instances of the same type.

Note
Not thread-safe.
Warning
Triggers assertion if an update is in progress.
Template Parameters
LSchedule label type
SSystem type satisfying SystemTrait
Parameters
labelTarget schedule label
nameHuman-readable system name
systemSystem instance
optionsLocal data options for the system
Returns
Handle for ordering and run conditions

Definition at line 323 of file sub_app.hpp.

◆ AddSystems()

template<ecs::ScheduleTrait L, ecs::FunctorSystemTrait... Systems>
requires (sizeof...(Systems) > 1)
ecs::SystemGroupHandle helios::app::SubApp::AddSystems ( const L & label,
Systems &&... systems )
inline

Adds multiple functor systems to the same schedule as a system group.

Returns a SystemGroupHandle for configuring the batch. Use InSet on the returned handle to assign every system to a named set.

Note
Not thread-safe.
Warning
Triggers assertion if an update is in progress.
Template Parameters
LSchedule label type
SystemsSystem types satisfying FunctorSystemTrait
Parameters
labelTarget schedule label
systemsSystem instances
Returns
Handle for configuring the system group

Definition at line 344 of file sub_app.hpp.

◆ AllowsOverlappingUpdates()

bool helios::app::SubApp::AllowsOverlappingUpdates ( ) const
inlinenodiscardnoexcept

Returns whether extraction may be skipped while updating.

Note
Not thread-safe.
Returns
True if overlapping extraction skips are enabled

Definition at line 531 of file sub_app.hpp.

◆ BuildScheduler()

void helios::app::SubApp::BuildScheduler ( async::Executor & executor)
inline

Builds all ECS schedules when any are dirty.

Note
Not thread-safe.
Warning
Triggers assertion if an update is in progress.
Parameters
executorAsync executor used to create threaded schedule executors

Definition at line 716 of file sub_app.hpp.

◆ Clear()

void helios::app::SubApp::Clear ( )

Clears the sub-app world, ECS scheduler, and extract function.

Note
Not thread-safe.
Warning
Triggers assertion if an update is in progress.

Definition at line 34 of file sub_app.cpp.

◆ ConfigureSet()

template<ecs::ScheduleTrait L, ecs::SystemSetTrait S>
ecs::SystemSetHandle helios::app::SubApp::ConfigureSet ( const L & label = {},
const S & set = {} )
inline

Gets or creates a system set in the given schedule.

Note
Not thread-safe.
Warning
Triggers assertion if an update is in progress.
Template Parameters
LSchedule label type
SSystem set type
Parameters
labelTarget schedule label
setSystem set instance
Returns
Handle for configuring the set

Definition at line 359 of file sub_app.hpp.

◆ EditSchedule()

template<ecs::ScheduleTrait L, typename F>
requires std::invocable<F, ecs::Schedule&>
auto helios::app::SubApp::EditSchedule ( this auto && self,
const L & label,
const F & fn ) -> decltype(std::forward< decltype(self)>(self))
inline

Mutates an existing schedule in place.

Note
Not thread-safe.
Warning
Triggers assertion if an update is in progress.
Template Parameters
LSchedule label type
Parameters
labelTarget schedule label
fnCallable receiving ecs::Schedule&
Returns
Reference to this sub-app for chaining

Definition at line 740 of file sub_app.hpp.

◆ Extract()

void helios::app::SubApp::Extract ( const ecs::World & main_world,
bool allow_while_updating = false )
inline

Copies data from the main world into this sub-app's world.

Calls the function passed to SetExtractFunction when set.

Note
Not thread-safe.
Warning
Triggers assertion if an update is in progress and allow_while_updating is false.
Parameters
main_worldMain application world to read from
allow_while_updatingWhen true, extraction may run during an update

Definition at line 699 of file sub_app.hpp.

◆ From()

template<SubAppTrait T>
SubApp helios::app::SubApp::From ( const T & sub_app = {})
inlinestaticnodiscard

Creates a sub-app named after the given label type.

Template Parameters
TSub-app label type satisfying SubAppTrait
Parameters
sub_appSub-app label instance
Returns
Sub-app with name derived from the label

Definition at line 191 of file sub_app.hpp.

◆ GetName()

const std::string & helios::app::SubApp::GetName ( ) const
inlinenodiscardnoexcept

Gets the human-readable sub-app name.

Note
Not thread-safe.
Returns
Sub-app name

Definition at line 412 of file sub_app.hpp.

◆ GetScheduler() [1/2]

const ecs::Scheduler & helios::app::SubApp::GetScheduler ( ) const
inlinenodiscardnoexcept

Gets this sub-app's ECS schedule collection.

Note
Thread-safe.
Returns
ECS scheduler reference

Definition at line 576 of file sub_app.hpp.

◆ GetScheduler() [2/2]

ecs::Scheduler & helios::app::SubApp::GetScheduler ( )
inlinenodiscardnoexcept

Gets this sub-app's ECS schedule collection.

Note
Thread-safe.
Returns
ECS scheduler reference

Definition at line 569 of file sub_app.hpp.

◆ GetWorld() [1/2]

const ecs::World & helios::app::SubApp::GetWorld ( ) const
inlinenodiscardnoexcept

Gets this sub-app's ECS world.

Returns
ECS world reference

Definition at line 562 of file sub_app.hpp.

◆ GetWorld() [2/2]

ecs::World & helios::app::SubApp::GetWorld ( )
inlinenodiscardnoexcept

Gets this sub-app's ECS world.

Note
Thread-safe for read access to returned world.
Returns
ECS world reference

Definition at line 556 of file sub_app.hpp.

◆ InitSchedule()

template<ecs::ScheduleTrait T>
auto helios::app::SubApp::InitSchedule ( this auto && self,
const T & label = {} ) -> decltype(std::forward< decltype(self)>(self))
inline

Creates an empty schedule for the label when it does not exist.

Note
Not thread-safe.
Warning
Triggers assertion if an update is in progress.
Template Parameters
TSchedule label type
Parameters
labelLabel value
Returns
Reference to this sub-app for chaining

Definition at line 730 of file sub_app.hpp.

◆ InsertResources()

template<ecs::ResourceTrait... Ts>
auto helios::app::SubApp::InsertResources ( this auto && self,
Ts &&... resources ) -> decltype(std::forward< decltype(self)>(self))
inline

Inserts or replaces resources in this sub-app's world.

Note
Not thread-safe.
Warning
Triggers assertion if an update is in progress.
Template Parameters
TsResource types
Parameters
resourcesResource values
Returns
Reference to this sub-app for chaining

Definition at line 747 of file sub_app.hpp.

◆ IsAsync()

bool helios::app::SubApp::IsAsync ( ) const
inlinenodiscardnoexcept

Returns whether this sub-app uses a background update loop.

Note
Not thread-safe.
Returns
True for async sub-apps

Definition at line 540 of file sub_app.hpp.

◆ IsUpdating()

bool helios::app::SubApp::IsUpdating ( ) const
inlinenodiscardnoexcept

Returns whether an update is in flight.

Note
Thread-safe.
Returns
True while an update pass is running, false otherwise

Definition at line 522 of file sub_app.hpp.

◆ MaxExtractionSkips()

size_t helios::app::SubApp::MaxExtractionSkips ( ) const
inlinenodiscardnoexcept

Returns the configured maximum consecutive extraction skips.

Note
Not thread-safe.
Returns
Skip budget; 0 means unlimited

Definition at line 547 of file sub_app.hpp.

◆ operator=() [1/2]

SubApp & helios::app::SubApp::operator= ( const SubApp & )
delete

◆ operator=() [2/2]

SubApp & helios::app::SubApp::operator= ( SubApp && other)
inlinenoexcept

Move-assigns a sub-app from another.

Warning
Triggers assertion if an update is in progress.
Parameters
otherThe sub-app to move from

Definition at line 654 of file sub_app.hpp.

◆ SetAllowOverlappingUpdates()

void helios::app::SubApp::SetAllowOverlappingUpdates ( bool allow_overlapping_updates)
inlinenoexcept

Sets whether extraction may be skipped while an update is in flight.

Note
Not thread-safe.
Warning
Triggers assertion if an update is in progress.
Parameters
allow_overlapping_updatesTrue to permit extraction skips

Definition at line 786 of file sub_app.hpp.

◆ SetAsync()

void helios::app::SubApp::SetAsync ( bool is_async)
inlinenoexcept

Sets whether this sub-app runs updates on a background loop.

Note
Not thread-safe.
Warning
Triggers assertion if an update is in progress.
Does not change the runner. When is_async is true, call SetRunner(RunDefaultSubApp) or SetRunner(RunFixedSubApp) (or a custom equivalent) before App::Initialize() so the background loop keeps updating until ShouldExit() becomes true.
Parameters
is_asyncTrue for continuous background updates

Definition at line 799 of file sub_app.hpp.

◆ SetExtractFunction()

template<typename F>
requires std::invocable<F, const ecs::World&, ecs::World&>
void helios::app::SubApp::SetExtractFunction ( F && fn)
inline

Sets the function invoked by Extract.

Note
Not thread-safe.
Warning
Triggers assertion if an update is in progress.
Template Parameters
FCallable receiving (const ecs::World&, ecs::World&)
Parameters
fnThe function to set

Definition at line 781 of file sub_app.hpp.

◆ SetMaxExtractionSkips()

void helios::app::SubApp::SetMaxExtractionSkips ( size_t max_skips)
inlinenoexcept

Sets the maximum consecutive extraction skips while updating.

0 means unlimited skips. Values 1, 2, ... cap how many main frames may skip extraction before waiting for the in-flight update.

Note
Not thread-safe.
Warning
Triggers assertion if an update is in progress.
Parameters
max_skipsMaximum consecutive extraction skips

Definition at line 793 of file sub_app.hpp.

◆ SetName()

void helios::app::SubApp::SetName ( std::string name)
inlinenoexcept

Sets the human-readable sub-app name.

Note
Not thread-safe.
Warning
Triggers assertion if an update is in progress.
Parameters
nameSub-app name

Definition at line 768 of file sub_app.hpp.

◆ SetRunner()

void helios::app::SubApp::SetRunner ( RunnerFn runner)
inlinenoexcept

Sets the function invoked each frame to run this sub-app's update pass.

Note
Not thread-safe.
Warning
Triggers assertion if an update is in progress.
Parameters
runnerCallable receiving SubApp& and async::Executor&; when set, this is called instead of running the update stage directly

Definition at line 773 of file sub_app.hpp.

◆ SetUpdateStage() [1/2]

template<ecs::StageTrait T>
void helios::app::SubApp::SetUpdateStage ( const T & stage = {})
inlinenoexcept

Sets which stage label Update executes.

Note
Not thread-safe.
Warning
Triggers assertion if an update is in progress.
Template Parameters
TStage label type
Parameters
stageStage label instance

Definition at line 810 of file sub_app.hpp.

◆ SetUpdateStage() [2/2]

void helios::app::SubApp::SetUpdateStage ( ecs::StageTypeIndex index)
inlinenoexcept

Sets which stage label Update executes.

Note
Not thread-safe.
Warning
Triggers assertion if an update is in progress.
Parameters
indexStage label type index

Definition at line 804 of file sub_app.hpp.

◆ ShouldExit()

bool helios::app::SubApp::ShouldExit ( ) const
nodiscardnoexcept

Returns whether this sub-app should stop its update loop.

Propagates App::ShouldExit() from the owning application when set. Also returns true when an async loop stop was requested during shutdown.

Note
Thread-safe.
Returns
True when the sub-app should exit its runner loop

Definition at line 60 of file sub_app.cpp.

◆ TryGetSchedule() [1/2]

template<ecs::ScheduleTrait T>
ecs::Schedule * helios::app::SubApp::TryGetSchedule ( const T & label = {})
inlinenodiscard

Tries to get the schedule for a label.

Note
Not thread-safe.
Template Parameters
TSchedule label type
Parameters
labelTarget schedule label
Returns
Pointer to the schedule, or nullptr if missing

Definition at line 491 of file sub_app.hpp.

◆ TryGetSchedule() [2/2]

template<ecs::ScheduleTrait T>
const ecs::Schedule * helios::app::SubApp::TryGetSchedule ( const T & label = {}) const
inlinenodiscard

Tries to get the schedule for a label.

Note
Not thread-safe.
Template Parameters
TSchedule label type
Parameters
labelTarget schedule label
Returns
Pointer to the schedule, or nullptr if missing

Definition at line 503 of file sub_app.hpp.

◆ TryInsertResources()

template<ecs::ResourceTrait... Ts>
auto helios::app::SubApp::TryInsertResources ( this auto && self,
Ts &&... resources ) -> decltype(std::forward< decltype(self)>(self))
inline

Inserts resources only when no instance exists yet.

Note
Not thread-safe.
Warning
Triggers assertion if an update is in progress.
Template Parameters
TsResource types
Parameters
resourcesResource values
Returns
Reference to this sub-app for chaining

Definition at line 754 of file sub_app.hpp.

◆ Update()

void helios::app::SubApp::Update ( async::Executor & executor)
inline

Runs the configured update stage.

Note
Only valid within an active update pass (IsUpdating() is true).
Warning
Triggers assertion if not called from within an active update pass.
Parameters
executorAsync executor used to build and run schedules

Definition at line 680 of file sub_app.hpp.

◆ WaitUntilFullyIdle()

void helios::app::SubApp::WaitUntilFullyIdle ( ) const
noexcept

Blocks until no update is in flight.

Note
Thread-safe.

Definition at line 47 of file sub_app.cpp.

◆ App

friend class App
friend

Definition at line 634 of file sub_app.hpp.

◆ Scheduler

friend class Scheduler
friend

Definition at line 635 of file sub_app.hpp.