helios::app::App Class Reference

Application class. More...

#include <app.hpp>

Public Types
using	RunnerFn = std::function< AppExitCode(App &)>
using	ExtractFn = std::function< void(const ecs::World &, ecs::World &)>

Public Member Functions
	App ()
	App (size_t worker_thread_count)
	Constructs an App with a specific number of worker threads.
	App (const App &)=delete
	App (App &&)=delete
	~App ()
	Destructor that ensures all async work is completed before destruction.
App &	operator= (const App &)=delete
App &	operator= (App &&)=delete
void	Clear ()
	Clears the application state, removing all data.
void	Initialize ()
	Initializes the application and its subsystems.
void	Update ()
	Updates the application and its subsystems.
AppExitCode	Run ()
	Runs the application with the given arguments.
void	WaitForOverlappingUpdates ()
	Waits for all overlapping sub-app updates to complete.
template<SubAppTrait T>
void	WaitForOverlappingUpdates (T sub_app={})
	Waits for overlapping updates of a specific sub-app type to complete.
void	WaitForOverlappingUpdates (const SubApp &sub_app)
	Waits for overlapping updates of a specific sub-app instance to complete.
void	TickTime () noexcept
	Updates the Time resource for the current frame.
template<SubAppTrait T>
auto	AddSubApp (this auto &&self, T sub_app={}) -> decltype(std::forward< decltype(self)>(self))
	Adds a new sub-application of type T.
template<SubAppTrait T>
auto	AddSubApp (this auto &&self, SubApp sub_app, T sub_app_tag={}) -> decltype(std::forward< decltype(self)>(self))
	Adds an existing sub-application instance.
template<DefaultConstructibleModuleTrait T>
auto	AddModule (this auto &&self) -> decltype(std::forward< decltype(self)>(self))
	Adds a default-constructed module to the main sub-app.
template<ModuleTrait T>
auto	AddModule (this auto &&self, T module) -> decltype(std::forward< decltype(self)>(self))
	Adds a pre-constructed module instance to the main sub-app.
template<DefaultConstructibleModuleTrait... Modules> requires (sizeof...(Modules) > 1 && utils::UniqueTypes<Modules...>)
auto	AddModules (this auto &&self) -> decltype(std::forward< decltype(self)>(self))
	Adds multiple default-constructed modules to the main sub-app.
template<ModuleTrait... Modules> requires (sizeof...(Modules) > 1 && utils::UniqueTypes<Modules...>)
auto	AddModules (this auto &&self, Modules &&... modules) -> decltype(std::forward< decltype(self)>(self))
	Adds multiple pre-constructed module instances to the main sub-app.
auto	AddDynamicModule (this auto &&self, DynamicModule module) -> decltype(std::forward< decltype(self)>(self))
	Adds a dynamic module to the main sub-app, taking ownership.
template<ecs::SystemTrait T, ScheduleTrait Schedule>
auto	AddSystem (this auto &&self, Schedule schedule={}) -> decltype(std::forward< decltype(self)>(self))
	Adds a system to the specified schedule in the main sub-app.
template<ecs::SystemTrait... Systems, ScheduleTrait Schedule> requires (sizeof...(Systems) > 1 && utils::UniqueTypes<Systems...>)
auto	AddSystems (this auto &&self, Schedule schedule={}) -> decltype(std::forward< decltype(self)>(self))
	Adds multiple systems to the specified schedule in the main sub-app.
template<ecs::SystemTrait... Systems, ScheduleTrait Schedule> requires (sizeof...(Systems) > 0 && utils::UniqueTypes<Systems...>)
auto	AddSystemsBuilder (this auto &&self, Schedule schedule={}) -> SystemConfig< Schedule, Systems... >
template<ecs::SystemTrait T, ScheduleTrait Schedule>
auto	AddSystemBuilder (this auto &&self, Schedule schedule={}) -> SystemConfig< Schedule, T >
	Adds a single system with fluent configuration builder.
template<SystemSetTrait Set, ScheduleTrait Schedule>
auto	ConfigureSet (this auto &&self, Schedule schedule={}) -> SystemSetConfig< Schedule, Set >
template<ecs::ResourceTrait T>
auto	InsertResource (this auto &&self, T &&resource) -> decltype(std::forward< decltype(self)>(self))
	Inserts a resource into the main sub-app.
template<ecs::ResourceTrait T, typename... Args> requires std::constructible_from<T, Args...>
auto	EmplaceResource (this auto &&self, Args &&... args) -> decltype(std::forward< decltype(self)>(self))
	Emplaces a resource into the main sub-app's world.
template<ecs::EventTrait T>
auto	AddEvent (this auto &&self) -> decltype(std::forward< decltype(self)>(self))
	Registers an event type for use in the main sub-app.
template<ecs::EventTrait... Events> requires (sizeof...(Events) > 1)
auto	AddEvents (this auto &&self) -> decltype(std::forward< decltype(self)>(self))
	Registers multiple event types for use in the main sub-app.
auto	SetRunner (this auto &&self, RunnerFn runner) noexcept -> decltype(std::forward< decltype(self)>(self))
	Sets runner function for the application.
template<SubAppTrait T>
auto	SetSubAppExtraction (this auto &&self, ExtractFn extract_fn) -> decltype(std::forward< decltype(self)>(self))
	Sets extraction function for a sub-app.
template<SubAppTrait T>
bool	ContainsSubApp () const noexcept
	Checks if a sub app of type T exists in main sub-app.
template<ModuleTrait T>
bool	ContainsModule () const noexcept
	Checks if a module of type T exists in main sub-app.
bool	ContainsDynamicModule (ModuleTypeId module_id) const noexcept
	Checks if a dynamic module with the given ID exists.
template<ecs::SystemTrait T>
bool	ContainsSystem () const noexcept
	Checks if a system of type T exists in any schedule of main sub-app.
template<ecs::SystemTrait T, ScheduleTrait Schedule>
bool	ContainsSystem (Schedule schedule={}) const noexcept
	Checks if a system of type T exists in the specified schedule of main sub-app.
bool	IsInitialized () const noexcept
	Checks if the app has been initialized.
bool	IsRunning () const noexcept
	Checks if the app is currently running.
template<ecs::ResourceTrait T>
bool	HasResource () const noexcept
	Checks if a resource exists in main sub_app.
template<ecs::EventTrait T>
bool	HasEvent () const noexcept
	Checks if a event is registered in main sub_app.
size_t	ModuleCount () const noexcept
	Gets the number of modules in main sub-app.
size_t	SystemCount () const noexcept
	Gets the total number of systems across all schedules in main sub-app.
template<ScheduleTrait Schedule>
size_t	SystemCount (Schedule schedule={}) const noexcept
	Gets the number of systems in the specified schedule of main sub-app.
template<SubAppTrait T>
SubApp &	GetSubApp () noexcept
	Gets a sub-application by type.
template<SubAppTrait T>
const SubApp &	GetSubApp () const noexcept
	Gets a sub-application by type (const version).
SubApp &	GetMainSubApp () noexcept
	Gets the main sub-application.
const SubApp &	GetMainSubApp () const noexcept
	Gets the main sub-application (const version).
const ecs::World &	GetMainWorld () const noexcept
	Gets the main world.
async::Executor &	GetExecutor () noexcept
	Gets the async executor.
const async::Executor &	GetExecutor () const noexcept
	Gets the async executor (const version).

Detailed Description

Application class.

Manages the application lifecycle, including initialization, updating, and shutdown.

Note

Not thread-safe.

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/modules/example/include/helios/example/example.hpp.

Definition at line 97 of file app.hpp.

Member Typedef Documentation

ExtractFn

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

Examples

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

Definition at line 104 of file app.hpp.

RunnerFn

using helios::app::App::RunnerFn = std::function<AppExitCode(App&)>

Examples

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

Definition at line 103 of file app.hpp.

Constructor & Destructor Documentation

App() [1/4]

helios::app::App::App

(

)

Examples

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

Definition at line 22 of file app.cpp.

: runner_(DefaultRunnerWrapper) {}

App() [2/4]

helios::app::App::App ( size_t  worker_thread_count )

explicit

Constructs an App with a specific number of worker threads.

Parameters

worker_thread_count

Number of worker threads for the executor

Definition at line 24 of file app.cpp.

: executor_(worker_thread_count), runner_(DefaultRunnerWrapper) {}

App() [3/4]

helios::app::App::App ( const App &  )

delete

App() [4/4]

helios::app::App::App ( App &&  )

delete

~App()

helios::app::App::~App

(

)

Destructor that ensures all async work is completed before destruction.

Waits for all overlapping updates and pending executor tasks to complete.

Examples

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

Definition at line 26 of file app.cpp.

          {
  // Ensure we're not running (should already be false if properly shut down)
  is_running_.store(false, std::memory_order_release);
 
  // Wait for any pending overlapping sub-app updates
  WaitForOverlappingUpdates();
 
  // Wait for all pending executor tasks to complete
  executor_.WaitForAll();
}

Member Function Documentation

AddDynamicModule()

auto helios::app::App::AddDynamicModule ( this auto &&  self, DynamicModule  module  ) -> decltype(std::forward<decltype(self)>(self))

inline

Adds a dynamic module to the main sub-app, taking ownership.

Modules can add their own systems, resources, and sub-apps. The App takes ownership of the module via move semantics.

Warning

Triggers an assertion if app is initialized or running.

Parameters

module

Dynamic module to add (moved)

Returns

Reference to app for method chaining

Examples

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

Definition at line 722 of file app.hpp.

                                                  {
  const std::string_view name = module.GetModuleName();
  const ModuleTypeId id = module.GetModuleId();
 
  HELIOS_ASSERT(!self.IsInitialized(), "Failed to add module '{}': Cannot add modules after app initialization!", name);
  HELIOS_ASSERT(!self.IsRunning(), "Failed to add module '{}': Cannot add modules while app is running!", name);
  HELIOS_ASSERT(module.Loaded(), "Failed to add module '{}': Module is not loaded!", name);
 
  // Check both static and dynamic module maps for duplicates
  if (self.module_index_map_.contains(id) || self.dynamic_module_index_map_.contains(id)) [[unlikely]] {
    HELIOS_WARN("Module '{}' already exists in app!", name);
    return std::forward<decltype(self)>(self);
  }
 
  self.dynamic_module_index_map_[id] = self.dynamic_modules_.size();
  self.dynamic_modules_.push_back(std::move(module));
  return std::forward<decltype(self)>(self);
}

AddEvent()

template<ecs::EventTrait T>

auto helios::app::App::AddEvent ( this auto &&  self ) -> decltype(std::forward<decltype(self)>(self))

inline

Registers an event type for use in the main sub-app.

Events must be registered before they can be written or read.

Warning

Triggers assertion if app is initialized or running.

Template Parameters

T	Event type

Returns

Reference to app for method chaining

Examples

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

Definition at line 794 of file app.hpp.

                                                                                        {
  HELIOS_ASSERT(!self.IsInitialized(), "Failed to add event '{}': Cannot add events after app initialization!",
                ecs::EventNameOf<T>());
 
  HELIOS_ASSERT(!self.IsRunning(), "Failed to add event '{}': Cannot add events while app is running!",
                ecs::EventNameOf<T>());
 
  if (self.template HasEvent<T>()) [[unlikely]] {
    HELIOS_WARN("Event '{}' is already exist in app!", ecs::EventNameOf<T>());
    return std::forward<decltype(self)>(self);
  }
 
  self.GetMainSubApp().template AddEvent<T>();
  return std::forward<decltype(self)>(self);
}

AddEvents()

template<ecs::EventTrait... Events>
requires (sizeof...(Events) > 1)

auto helios::app::App::AddEvents ( this auto &&  self ) -> decltype(std::forward<decltype(self)>(self))

inline

Registers multiple event types for use in the main sub-app.

Warning

Triggers assertion if app is initialized or running.

Template Parameters

Events

Event types to register

Returns

Reference to app for method chaining

Examples

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

Definition at line 812 of file app.hpp.

                                                                                         {
  HELIOS_ASSERT(!self.IsInitialized(), "Failed to add events: Cannot add events after app initialization!");
  HELIOS_ASSERT(!self.IsRunning(), "Failed to add events: Cannot add events while app is running!");
 
  self.GetMainSubApp().template AddEvents<Events...>();
  return std::forward<decltype(self)>(self);
}

AddModule() [1/2]

template<DefaultConstructibleModuleTrait T>

auto helios::app::App::AddModule ( this auto &&  self ) -> decltype(std::forward<decltype(self)>(self))

inline

Adds a default-constructed module to the main sub-app.

Modules can add their own systems, resources, and sub-apps.

Warning

Triggers an assertion if app is initialized or running.

Template Parameters

T	Module type (must be default constructible)

Returns

Reference to app for method chaining

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/app/app.hpp, and /home/runner/work/HeliosEngine/HeliosEngine/src/modules/example/include/helios/example/example.hpp.

Definition at line 663 of file app.hpp.

                                                                                         {
  HELIOS_ASSERT(!self.IsInitialized(), "Failed to add module '{}': Cannot add modules after app initialization!",
                ModuleNameOf<T>());
 
  HELIOS_ASSERT(!self.IsRunning(), "Failed to add module '{}': Cannot add modules while app is running!",
                ModuleNameOf<T>());
 
  // module->Build(self);  // Will be called after all modules are added
  constexpr ModuleTypeId id = ModuleTypeIdOf<T>();
  if (self.module_index_map_.contains(id)) [[unlikely]] {
    HELIOS_WARN("Module '{}' is already exist in app!", ModuleNameOf<T>());
    return std::forward<decltype(self)>(self);
  }
 
  self.module_index_map_[id] = self.modules_.size();
  auto module = std::make_unique<T>();
  self.modules_.push_back(std::move(module));
  return std::forward<decltype(self)>(self);
}

AddModule() [2/2]

template<ModuleTrait T>

auto helios::app::App::AddModule ( this auto &&  self, T  module  ) -> decltype(std::forward<decltype(self)>(self))

inline

Adds a pre-constructed module instance to the main sub-app.

Allows adding modules with non-default constructors or pre-configured state.

Warning

Triggers an assertion if app is initialized or running.

Template Parameters

T	Module type

Parameters

module

Module instance to add (will be moved)

Returns

Reference to app for method chaining

Definition at line 684 of file app.hpp.

                                                                                                   {
  HELIOS_ASSERT(!self.IsInitialized(), "Failed to add module '{}': Cannot add modules after app initialization!",
                ModuleNameOf<T>());
 
  HELIOS_ASSERT(!self.IsRunning(), "Failed to add module '{}': Cannot add modules while app is running!",
                ModuleNameOf<T>());
 
  constexpr ModuleTypeId id = ModuleTypeIdOf<T>();
  if (self.module_index_map_.contains(id)) [[unlikely]] {
    HELIOS_WARN("Module '{}' is already exist in app!", ModuleNameOf<T>());
    return std::forward<decltype(self)>(self);
  }
 
  self.module_index_map_[id] = self.modules_.size();
  self.modules_.push_back(std::make_unique<T>(std::move(module)));
  return std::forward<decltype(self)>(self);
}

AddModules() [1/2]

template<DefaultConstructibleModuleTrait... Modules>
requires (sizeof...(Modules) > 1 && utils::UniqueTypes<Modules...>)

auto helios::app::App::AddModules ( this auto &&  self ) -> decltype(std::forward<decltype(self)>(self))

inline

Adds multiple default-constructed modules to the main sub-app.

Warning

Triggers an assertion if app is initialized or running.

Template Parameters

Modules

Module types (must be default constructible)

Returns

Reference to app for method chaining

Examples

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

Definition at line 704 of file app.hpp.

                                                                                          {
  HELIOS_ASSERT(!self.IsInitialized(), "Failed to add modules: Cannot add modules after app initialization!");
  HELIOS_ASSERT(!self.IsRunning(), "Failed to add modules: Cannot add modules while app is running!");
 
  (self.template AddModule<Modules>(), ...);
  return std::forward<decltype(self)>(self);
}

AddModules() [2/2]

template<ModuleTrait... Modules>
requires (sizeof...(Modules) > 1 && utils::UniqueTypes<Modules...>)

auto helios::app::App::AddModules ( this auto &&  self, Modules &&...  modules  ) -> decltype(std::forward<decltype(self)>(self))

inline

Adds multiple pre-constructed module instances to the main sub-app.

Allows adding modules with non-default constructors or pre-configured state.

Warning

Triggers an assertion if app is initialized or running.

Template Parameters

Modules

Module types

Parameters

modules

Module instances to add (will be moved)

Returns

Reference to app for method chaining

Definition at line 714 of file app.hpp.

                                                                                                                {
  HELIOS_ASSERT(!self.IsInitialized(), "Failed to add modules: Cannot add modules after app initialization!");
  HELIOS_ASSERT(!self.IsRunning(), "Failed to add modules: Cannot add modules while app is running!");
 
  (self.AddModule(std::forward<Modules>(modules)), ...);
  return std::forward<decltype(self)>(self);
}

AddSubApp() [1/2]

template<SubAppTrait T>

auto helios::app::App::AddSubApp ( this auto &&  self, SubApp  sub_app, T  sub_app_tag = {}  ) -> decltype(std::forward<decltype(self)>(self))

inline

Adds an existing sub-application instance.

Warning

Triggers an assertion if app is initialized or running.

Template Parameters

T	Sub-application type

Parameters

sub_app	Sub-application instance to add
sub_app_tag	Sub-app type tag

Returns

Reference to app for method chaining

Definition at line 634 of file app.hpp.

                                                  {
  HELIOS_ASSERT(!self.IsInitialized(), "Failed to add sub app '{}': Cannot add sub apps after app initialization!",
                SubAppNameOf<T>());
 
  HELIOS_ASSERT(!self.IsRunning(), "Failed to add sub app '{}': Cannot add sub apps while app is running!",
                SubAppNameOf<T>());
 
  constexpr SubAppTypeId id = SubAppTypeIdOf<T>();
  if (self.sub_app_index_map_.contains(id)) [[unlikely]] {
    HELIOS_WARN("Sub app '{}' is already exist in app!", SubAppNameOf<T>());
    return std::forward<decltype(self)>(self);
  }
 
  // Set overlapping updates flag based on trait before adding
  constexpr bool allow_overlapping = SubAppAllowsOverlappingUpdates<T>();
  sub_app.SetAllowOverlappingUpdates(allow_overlapping);
 
  // Set max overlapping updates based on trait
  constexpr size_t max_overlapping = SubAppMaxOverlappingUpdates<T>();
  sub_app.SetMaxOverlappingUpdates(max_overlapping);
 
  self.sub_app_index_map_[id] = self.sub_apps_.size();
  self.sub_apps_.push_back(std::move(sub_app));
 
  return std::forward<decltype(self)>(self);
}

AddSubApp() [2/2]

template<SubAppTrait T>

auto helios::app::App::AddSubApp ( this auto &&  self, T  sub_app = {}  ) -> decltype(std::forward<decltype(self)>(self))

inline

Adds a new sub-application of type T.

Warning

Triggers an assertion if app is initialized or running.

Template Parameters

T	Sub-application type

Parameters

sub_app

Sub-app type tag

Returns

Reference to app for method chaining

Examples

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

Definition at line 606 of file app.hpp.

                                                                                              {
  HELIOS_ASSERT(!self.IsInitialized(), "Failed to add sub app '{}': Cannot add sub apps after app initialization!",
                SubAppNameOf<T>());
 
  HELIOS_ASSERT(!self.IsRunning(), "Failed to add sub app '{}': Cannot add sub apps while app is running!",
                SubAppNameOf<T>());
 
  constexpr SubAppTypeId id = SubAppTypeIdOf<T>();
  if (self.sub_app_index_map_.contains(id)) [[unlikely]] {
    HELIOS_WARN("Sub app '{}' is already exist in app!", SubAppNameOf<T>());
    return std::forward<decltype(self)>(self);
  }
 
  self.sub_app_index_map_[id] = self.sub_apps_.size();
  self.sub_apps_.emplace_back();
 
  // Set overlapping updates flag based on trait
  constexpr bool allow_overlapping = SubAppAllowsOverlappingUpdates<T>();
  self.sub_apps_.back().SetAllowOverlappingUpdates(allow_overlapping);
 
  // Set max overlapping updates based on trait
  constexpr size_t max_overlapping = SubAppMaxOverlappingUpdates<T>();
  self.sub_apps_.back().SetMaxOverlappingUpdates(max_overlapping);
 
  return std::forward<decltype(self)>(self);
}

AddSystem()

template<ecs::SystemTrait T, ScheduleTrait Schedule>

auto helios::app::App::AddSystem ( this auto &&  self, Schedule  schedule = {}  ) -> decltype(std::forward<decltype(self)>(self))

inline

Adds a system to the specified schedule in the main sub-app.

Warning

Triggers an assertion if app is initialized or running.

Template Parameters

T	System type
Schedule	Schedule type

Parameters

schedule

Schedule to add system to

Returns

Reference to app for method chaining

Examples

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

Definition at line 743 of file app.hpp.

                                                                                                            {
  HELIOS_ASSERT(!self.IsInitialized(), "Failed to add system '{}': Cannot add systems after app initialization!",
                ecs::SystemNameOf<T>());
 
  HELIOS_ASSERT(!self.IsRunning(), "Failed to add system '{}': Cannot add systems while app is running!",
                ecs::SystemNameOf<T>());
 
  if (self.template ContainsSystem<T>(schedule)) [[unlikely]] {
    HELIOS_WARN("System '{}' is already exist in app schedule '{}'!", ecs::SystemNameOf<T>(),
                ScheduleNameOf<Schedule>());
    return std::forward<decltype(self)>(self);
  }
 
  self.GetMainSubApp().template AddSystem<T>(schedule);
  return std::forward<decltype(self)>(self);
}

AddSystemBuilder()

template<ecs::SystemTrait T, ScheduleTrait Schedule>

auto helios::app::App::AddSystemBuilder ( this auto &&  self, Schedule  schedule = {}  ) -> SystemConfig<Schedule, T>

inline

Adds a single system with fluent configuration builder.

Returns a builder that allows chaining configuration methods.

Warning

Triggers an assertion if app is initialized or running.

Template Parameters

T	System type to add
Schedule	Schedule type

Parameters

schedule

Schedule to add system to

Returns

SystemConfig builder for fluent configuration

Examples

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

Definition at line 919 of file app.hpp.

                                                                                                  {
  HELIOS_ASSERT(!self.IsInitialized(), "Failed to add system '{}': Cannot add system after app initialization!",
                ecs::SystemNameOf<T>());
  HELIOS_ASSERT(!self.IsRunning(), "Failed to add system '{}': Cannot add system while app is running!",
                ecs::SystemNameOf<T>());
 
  return self.GetMainSubApp().template AddSystemBuilder<T>(schedule);
}

AddSystems()

template<ecs::SystemTrait... Systems, ScheduleTrait Schedule>
requires (sizeof...(Systems) > 1 && utils::UniqueTypes<Systems...>)

auto helios::app::App::AddSystems ( this auto &&  self, Schedule  schedule = {}  ) -> decltype(std::forward<decltype(self)>(self))

inline

Adds multiple systems to the specified schedule in the main sub-app.

Warning

Triggers an assertion if app is initialized or running.

Template Parameters

Systems	System types
Schedule	Schedule type

Parameters

schedule

Schedule to add systems to

Returns

Reference to app for method chaining

Examples

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

Definition at line 762 of file app.hpp.

                                                                                                             {
  HELIOS_ASSERT(!self.IsInitialized(), "Failed to add systems: Cannot add systems after app initialization!");
  HELIOS_ASSERT(!self.IsRunning(), "Failed to add systems: Cannot add systems while app is running!");
 
  self.GetMainSubApp().template AddSystems<Systems...>(schedule);
  return std::forward<decltype(self)>(self);
}

AddSystemsBuilder()

template<ecs::SystemTrait... Systems, ScheduleTrait Schedule>
requires (sizeof...(Systems) > 0 && utils::UniqueTypes<Systems...>)

auto helios::app::App::AddSystemsBuilder ( this auto &&  self, Schedule  schedule = {}  ) -> SystemConfig<Schedule, Systems...>

inline

Examples

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

Definition at line 911 of file app.hpp.

                                                                                                            {
  HELIOS_ASSERT(!self.IsInitialized(), "Failed to add systems: Cannot add systems after app initialization!");
  HELIOS_ASSERT(!self.IsRunning(), "Failed to add systems: Cannot add systems while app is running!");
 
  return self.GetMainSubApp().template AddSystemsBuilder<Systems...>(schedule);
}

Clear()

void helios::app::App::Clear

(

)

Clears the application state, removing all data.

Warning

Triggers assertion if app is running.

Examples

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

Definition at line 37 of file app.cpp.

                {
  HELIOS_ASSERT(!IsRunning(), "Failed to clear app: Cannot clear app while it is running!");
 
  WaitForOverlappingUpdates();  // Ensure all async work is done
  sub_app_overlapping_futures_.clear();
  main_sub_app_.Clear();
  sub_apps_.clear();
  sub_app_index_map_.clear();
 
  is_initialized_ = false;
}

ConfigureSet()

template<SystemSetTrait Set, ScheduleTrait Schedule>

auto helios::app::App::ConfigureSet ( this auto &&  self, Schedule  schedule = {}  ) -> SystemSetConfig<Schedule, Set>

inline

Examples

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

Definition at line 929 of file app.hpp.

                                                                                                   {
  HELIOS_ASSERT(!self.IsInitialized(), "Failed to configure set '{}': Cannot configure set after app initialization!",
                SystemSetNameOf<Set>());
  HELIOS_ASSERT(!self.IsRunning(), "Failed to configure set '{}': Cannot configure set while app is running!",
                SystemSetNameOf<Set>());
 
  return self.GetMainSubApp().template ConfigureSet<Set>(schedule);
}

ContainsDynamicModule()

bool helios::app::App::ContainsDynamicModule ( ModuleTypeId  module_id ) const

inlinenoexcept

Checks if a dynamic module with the given ID exists.

Parameters

module_id

Module type ID

Returns

True if module exists, false otherwise

Examples

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

Definition at line 867 of file app.hpp.

                                                                            {
  return dynamic_module_index_map_.contains(module_id);
}

ContainsModule()

template<ModuleTrait T>

bool helios::app::App::ContainsModule ( ) const

inlinenoexcept

Checks if a module of type T exists in main sub-app.

Template Parameters

T	Module type

Returns

True if module exists, false otherwise

Examples

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

Definition at line 862 of file app.hpp.

                                               {
  constexpr ModuleTypeId id = ModuleTypeIdOf<T>();
  return module_index_map_.contains(id) || dynamic_module_index_map_.contains(id);
}

ContainsSubApp()

template<SubAppTrait T>

bool helios::app::App::ContainsSubApp ( ) const

inlinenoexcept

Checks if a sub app of type T exists in main sub-app.

Template Parameters

T	SubApp type

Returns

True if sub app exists, false otherwise

Examples

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

Definition at line 856 of file app.hpp.

                                               {
  constexpr SubAppTypeId id = SubAppTypeIdOf<T>();
  return sub_app_index_map_.contains(id);
}

ContainsSystem() [1/2]

template<ecs::SystemTrait T>

bool helios::app::App::ContainsSystem ( ) const

inlinenoexcept

Checks if a system of type T exists in any schedule of main sub-app.

Template Parameters

T	System type

Returns

True if system exists, false otherwise

Examples

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

Definition at line 427 of file app.hpp.

                                                     {
    return main_sub_app_.ContainsSystem<T>();
  }

ContainsSystem() [2/2]

template<ecs::SystemTrait T, ScheduleTrait Schedule>

bool helios::app::App::ContainsSystem ( Schedule  schedule = {} ) const

inlinenoexcept

Checks if a system of type T exists in the specified schedule of main sub-app.

Template Parameters

T	System type
Schedule	Schedule type

Parameters

schedule

Schedule to check

Returns

True if system exists, false otherwise

Definition at line 439 of file app.hpp.

                                                        {}) const noexcept {
    return main_sub_app_.ContainsSystem<T>(schedule);
  }

EmplaceResource()

template<ecs::ResourceTrait T, typename... Args>
requires std::constructible_from<T, Args...>

auto helios::app::App::EmplaceResource ( this auto &&  self, Args &&...  args  ) -> decltype(std::forward<decltype(self)>(self))

inline

Emplaces a resource into the main sub-app's world.

Warning

Triggers assertion if app is initialized or running.

Template Parameters

T	Resource type
Args	Constructor argument types

Parameters

args	Arguments to forward to resource constructor

Returns

Reference to app for method chaining

Examples

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

Definition at line 781 of file app.hpp.

                                                                                                               {
  HELIOS_ASSERT(!self.IsInitialized(),
                "Failed to emplace resource '{}': Cannot add resources after app initialization!",
                ecs::ResourceNameOf<T>());
 
  HELIOS_ASSERT(!self.IsRunning(), "Failed to emplace resource '{}': Cannot add resources while app is running!",
                ecs::ResourceNameOf<T>());
 
  self.GetMainSubApp().template EmplaceResource<T>(std::forward<Args>(args)...);
  return std::forward<decltype(self)>(self);
}

GetExecutor() [1/2]

const async::Executor & helios::app::App::GetExecutor ( ) const

inlinenoexcept

Gets the async executor (const version).

Returns

Const reference to the async executor

Definition at line 545 of file app.hpp.

{ return executor_; }

GetExecutor() [2/2]

async::Executor & helios::app::App::GetExecutor ( )

inlinenoexcept

Gets the async executor.

Returns

Reference to the async executor

Examples

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

Definition at line 539 of file app.hpp.

{ return executor_; }

GetMainSubApp() [1/2]

const SubApp & helios::app::App::GetMainSubApp ( ) const

inlinenoexcept

Gets the main sub-application (const version).

Returns

Const reference to the main sub-application

Definition at line 527 of file app.hpp.

{ return main_sub_app_; }

GetMainSubApp() [2/2]

SubApp & helios::app::App::GetMainSubApp ( )

inlinenoexcept

Gets the main sub-application.

Returns

Reference to the main sub-application

Examples

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

Definition at line 521 of file app.hpp.

{ return main_sub_app_; }

GetMainWorld()

const ecs::World & helios::app::App::GetMainWorld ( ) const

inlinenoexcept

Gets the main world.

Returns

Reference to the main world

Examples

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

Definition at line 533 of file app.hpp.

{ return main_sub_app_.GetWorld(); }

GetSubApp() [1/2]

template<SubAppTrait T>

const SubApp & helios::app::App::GetSubApp ( ) const

inlinenoexcept

Gets a sub-application by type (const version).

Warning

Triggers an assertion if the sub-app does not exist.

Template Parameters

T	Sub-application type

Returns

Const reference to the sub-application

Definition at line 881 of file app.hpp.

                                                   {
  constexpr SubAppTypeId id = SubAppTypeIdOf<T>();
  const auto it = sub_app_index_map_.find(id);
  HELIOS_ASSERT(it != sub_app_index_map_.end(), "Failed to get sub app '{}': Sub app does not exist!",
                SubAppNameOf<T>());
  return sub_apps_.at(it->second);
}

GetSubApp() [2/2]

template<SubAppTrait T>

SubApp & helios::app::App::GetSubApp ( )

inlinenoexcept

Gets a sub-application by type.

Warning

Triggers an assertion if the sub-app does not exist. Reference might be invalidated due to reallocation of storage after addition of new sub apps.

Template Parameters

T	Sub-application type

Returns

Reference to the sub-application

Examples

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

Definition at line 872 of file app.hpp.

                                       {
  constexpr SubAppTypeId id = SubAppTypeIdOf<T>();
  const auto it = sub_app_index_map_.find(id);
  HELIOS_ASSERT(it != sub_app_index_map_.end(), "Failed to get sub app '{}': Sub app does not exist!",
                SubAppNameOf<T>());
  return sub_apps_.at(it->second);
}

HasEvent()

template<ecs::EventTrait T>

bool helios::app::App::HasEvent ( ) const

inlinenoexcept

Checks if a event is registered in main sub_app.

Template Parameters

T	Event type

Returns

True if event exists, false otherwise

Examples

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

Definition at line 471 of file app.hpp.

                                               {
    return main_sub_app_.HasEvent<T>();
  }

HasResource()

template<ecs::ResourceTrait T>

bool helios::app::App::HasResource ( ) const

inlinenoexcept

Checks if a resource exists in main sub_app.

Template Parameters

T	Resource type

Returns

True if resource exists, false otherwise

Examples

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

Definition at line 461 of file app.hpp.

                                                  {
    return main_sub_app_.HasResource<T>();
  }

Initialize()

void helios::app::App::Initialize

(

)

Initializes the application and its subsystems.

Called before the main loop starts. Spawns tasks on the executor for parallel initialization.

Note

Automaticly called in Run().

Warning

Triggers assertion if app is already initialized or running.

Examples

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

Definition at line 116 of file app.cpp.

                     {
  HELIOS_ASSERT(!IsInitialized(), "Failed to initialize: App is already initialized!");
  HELIOS_ASSERT(!IsRunning(), "Failed to initialize: Cannot initialize while app is running!");
 
  async::TaskGraph initialization_graph;
  initialization_graph.EmplaceTask([this]() {
    main_sub_app_.BuildScheduler();
    main_sub_app_.ExecuteStage<helios::app::StartUpStage>(executor_);
    main_sub_app_.GetWorld().Update();
  });
 
  initialization_graph.ForEach(sub_apps_, [this](const SubApp& sub_app_ref) mutable {
    // Need non-const access to modify sub_app
    auto& sub_app = const_cast<SubApp&>(sub_app_ref);
 
    sub_app.BuildScheduler();
    sub_app.ExecuteStage<helios::app::StartUpStage>(executor_);
    sub_app.GetWorld().Update();
  });
 
  auto future = executor_.Run(initialization_graph);
 
  update_graph_.ForEach(sub_apps_, [this](const SubApp& sub_app_ref) mutable {
    if (sub_app_ref.AllowsOverlappingUpdates()) {
      return;
    }
 
    // Need non-const access to modify sub_app
    auto& sub_app = const_cast<SubApp&>(sub_app_ref);
    sub_app.Extract(main_sub_app_.GetWorld());
    sub_app.Update(executor_);
  });
 
  future.Wait();
 
  is_initialized_ = true;
}

InsertResource()

template<ecs::ResourceTrait T>

auto helios::app::App::InsertResource ( this auto &&  self, T &&  resource  ) -> decltype(std::forward<decltype(self)>(self))

inline

Inserts a resource into the main sub-app.

Warning

Triggers assertion if app is initialized or running.

Template Parameters

T	Resource type

Parameters

resource

Resource to insert

Returns

Reference to app for method chaining

Examples

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

Definition at line 771 of file app.hpp.

                                                                                                            {
  HELIOS_ASSERT(!self.IsInitialized(), "Failed to insert resource '{}': Cannot add resources after app initialization!",
                ecs::ResourceNameOf<T>());
 
  self.GetMainSubApp().InsertResource(std::forward<T>(resource));
  return std::forward<decltype(self)>(self);
}

IsInitialized()

bool helios::app::App::IsInitialized ( ) const

inlinenoexcept

Checks if the app has been initialized.

Returns

True if initialized, false otherwise

Examples

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

Definition at line 447 of file app.hpp.

{ return is_initialized_; }

IsRunning()

bool helios::app::App::IsRunning ( ) const

inlinenoexcept

Checks if the app is currently running.

Returns

True if running, false otherwise

Examples

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

Definition at line 453 of file app.hpp.

{ return is_running_.load(std::memory_order_acquire); }

ModuleCount()

size_t helios::app::App::ModuleCount ( ) const

inlinenoexcept

Gets the number of modules in main sub-app.

Returns

Number of modules

Examples

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

Definition at line 479 of file app.hpp.

{ return modules_.size() + dynamic_modules_.size(); }

operator=() [1/2]

App & helios::app::App::operator= ( App &&  )

delete

operator=() [2/2]

App & helios::app::App::operator= ( const App &  )

delete

Examples

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

Run()

AppExitCode helios::app::App::Run

(

)

Runs the application with the given arguments.

Warning

Triggers assertion if app is initialized or running.

Returns

Exit code of the application.

Examples

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

Definition at line 49 of file app.cpp.

                     {
  HELIOS_ASSERT(!IsRunning(), "Failed to run: App is already running!");
 
  HELIOS_INFO("Starting application...");
 
  // Register built-in resources and events if not already registered
  RegisterBuiltins();
 
  BuildModules();
  FinishModules();
  Initialize();
 
  // Run the application using the provided runner function
  is_running_.store(true, std::memory_order_release);
  const AppExitCode exit_code = runner_(*this);
  is_running_.store(false, std::memory_order_release);
 
  HELIOS_INFO("Cleaning up application...");
  CleanUp();
 
  executor_.WaitForAll();
 
  DestroyModules();
 
  // Reset state
  is_initialized_ = false;
  sub_app_overlapping_futures_.clear();
  main_sub_app_.Clear();
  sub_apps_.clear();
  sub_app_index_map_.clear();
 
  HELIOS_INFO("Application exiting with code: {}", std::to_underlying(exit_code));
  return exit_code;
}

SetRunner()

auto helios::app::App::SetRunner ( this auto &&  self, RunnerFn  runner  ) -> decltype(std::forward<decltype(self)>(self))

inlinenoexcept

Sets runner function for the application.

Warning

Triggers assertion if app is initialized, running, or runner is null.

Parameters

runner

A move-only function that takes an App reference and returns an AppExitCode.

Returns

Reference to app for method chaining

Examples

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

Definition at line 820 of file app.hpp.

                                                                                                                   {
  HELIOS_ASSERT(!self.IsInitialized(), "Failed to set runner: Cannot set runner after app initialization!");
  HELIOS_ASSERT(!self.IsRunning(), "Failed to set runner: Cannot set runner while app is running!");
 
  HELIOS_ASSERT(runner, "Failed to set runner: Runner function cannot be null!");
 
  self.runner_ = std::move(runner);
  return std::forward<decltype(self)>(self);
}

SetSubAppExtraction()

template<SubAppTrait T>

auto helios::app::App::SetSubAppExtraction ( this auto &&  self, ExtractFn  extract_fn  ) -> decltype(std::forward<decltype(self)>(self))

inline

Sets extraction function for a sub-app.

The extraction function is called before the sub-app's Update to copy data from the main world.

Warning

Triggers assertion if app is initialized, running, extraction function is null, or sub-app doesn't exist.

Template Parameters

T	Sub-application type

Parameters

extract_fn

Function that takes main world and sub-app world references

Returns

Reference to app for method chaining

Examples

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

Definition at line 831 of file app.hpp.

                                                  {
  HELIOS_ASSERT(
      !self.IsInitialized(),
      "Failed to set extraction function for sub app '{}': Cannot set extraction function after app initialization!",
      SubAppNameOf<T>());
 
  HELIOS_ASSERT(
      !self.IsRunning(),
      "Failed to set extraction function for sub app '{}': Cannot set extraction function while app is running!",
      SubAppNameOf<T>());
 
  HELIOS_ASSERT(extract_fn, "Failed to set extraction function for sub app '{}': Extraction function cannot be null!",
                SubAppNameOf<T>());
 
  constexpr SubAppTypeId id = SubAppTypeIdOf<T>();
  const auto it = self.sub_app_index_map_.find(id);
  HELIOS_ASSERT(it != self.sub_app_index_map_.end(),
                "Failed to set extraction function for sub app '{}': Sub app does not exist!", SubAppNameOf<T>());
 
  self.sub_apps_.at(it->second).SetExtractFunction(std::move(extract_fn));
  return std::forward<decltype(self)>(self);
}

SystemCount() [1/2]

size_t helios::app::App::SystemCount ( ) const

inlinenoexcept

Gets the total number of systems across all schedules in main sub-app.

Returns

Total number of systems

Examples

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

Definition at line 485 of file app.hpp.

{ return main_sub_app_.SystemCount(); }

SystemCount() [2/2]

template<ScheduleTrait Schedule>

size_t helios::app::App::SystemCount ( Schedule  schedule = {} ) const

inlinenoexcept

Gets the number of systems in the specified schedule of main sub-app.

Template Parameters

Schedule

Schedule type

Parameters

schedule

Schedule to query

Returns

Number of systems in the schedule

Definition at line 494 of file app.hpp.

                                                       {}) const noexcept {
    return main_sub_app_.SystemCount(schedule);
  }

TickTime()

void helios::app::App::TickTime ( )

noexcept

Updates the Time resource for the current frame.

Should be called at the beginning of each frame by the runner. Does nothing if Time resource is not registered.

Examples

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

Definition at line 206 of file app.cpp.

                            {
  if (main_sub_app_.GetWorld().HasResource<Time>()) [[likely]] {
    main_sub_app_.GetWorld().WriteResource<Time>().Tick();
  }
}

Update()

void helios::app::App::Update

(

)

Updates the application and its subsystems.

Calls Update on the main sub-app and all registered sub-apps. Spawns async tasks as needed.

Note

Should not be called directly - use the runner function instead.

Warning

Triggers assertion if app is not initialized.

Examples

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

Definition at line 84 of file app.cpp.

                 {
  // Clean up completed per-sub-app overlapping futures using cached ready flags
  for (auto& [index, futures] : sub_app_overlapping_futures_) {
    std::erase_if(futures, [](details::TrackedFuture& tracked) { return tracked.IsReady(); });
  }
 
  // Update main sub-app (synchronous)
  main_sub_app_.Update(executor_);
 
  // Process non-overlapping sub-apps
  auto non_overlapping_future = executor_.Run(update_graph_);
 
  // Launch overlapping sub-apps asynchronously (non-blocking)
  for (size_t i = 0; i < sub_apps_.size(); ++i) {
    auto& sub_app = sub_apps_[i];
    if (!sub_app.AllowsOverlappingUpdates()) {
      continue;
    }
 
    // Capture by reference is safe: App lifetime exceeds sub-app updates
    auto future = executor_.Async([this, &sub_app]() {
      sub_app.Extract(main_sub_app_.GetWorld());
      sub_app.Update(executor_);
    });
 
    // Store as TrackedFuture for optimized ready-state tracking
    sub_app_overlapping_futures_[i].push_back(details::TrackedFuture{.future = future.share(), .ready = false});
  }
 
  non_overlapping_future.Wait();
}

WaitForOverlappingUpdates() [1/3]

void helios::app::App::WaitForOverlappingUpdates

(

)

Waits for all overlapping sub-app updates to complete.

Can be called explicitly when synchronization is needed. Automatically called during CleanUp().

Examples

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

Definition at line 172 of file app.cpp.

                                    {
  for (auto& [index, futures] : sub_app_overlapping_futures_) {
    for (auto& tracked : futures) {
      tracked.Wait();
    }
    futures.clear();
  }
}

WaitForOverlappingUpdates() [2/3]

void helios::app::App::WaitForOverlappingUpdates

(

const SubApp &

sub_app

)

Waits for overlapping updates of a specific sub-app instance to complete.

Can be called explicitly when synchronization is needed for a specific sub-app.

Parameters

sub_app

Reference to the sub-app to wait for

Definition at line 181 of file app.cpp.

                                                         {
  // Find the sub-app index by comparing addresses
  auto sub_app_index = static_cast<size_t>(-1);
  for (size_t i = 0; i < sub_apps_.size(); ++i) {
    if (&sub_apps_[i] == &sub_app) {
      sub_app_index = i;
      break;
    }
  }
 
  if (sub_app_index == static_cast<size_t>(-1)) [[unlikely]] {
    return;  // Sub-app not found
  }
 
  const auto futures_it = sub_app_overlapping_futures_.find(sub_app_index);
  if (futures_it == sub_app_overlapping_futures_.end()) {
    return;  // No overlapping futures for this sub-app
  }
 
  for (auto& tracked : futures_it->second) {
    tracked.Wait();
  }
  futures_it->second.clear();
}

WaitForOverlappingUpdates() [3/3]

template<SubAppTrait T>

void helios::app::App::WaitForOverlappingUpdates ( T  sub_app = {} )

inline

Waits for overlapping updates of a specific sub-app type to complete.

Can be called explicitly when synchronization is needed for a specific sub-app.

Template Parameters

T	Sub-app type

Parameters

sub_app

Sub-app type tag

Definition at line 890 of file app.hpp.

                                              {
  constexpr SubAppTypeId id = SubAppTypeIdOf<T>();
  const auto it = sub_app_index_map_.find(id);
  if (it == sub_app_index_map_.end()) [[unlikely]] {
    return;  // Sub-app doesn't exist
  }
 
  const size_t index = it->second;
  const auto futures_it = sub_app_overlapping_futures_.find(index);
  if (futures_it == sub_app_overlapping_futures_.end()) {
    return;  // No overlapping futures for this sub-app
  }
 
  for (auto& tracked : futures_it->second) {
    tracked.Wait();
  }
  futures_it->second.clear();
}