helios::ecs::details::SystemLocalStorage Class Reference

Local storage for system-specific data (commands, events, and temporary allocations). More...

#include <system_local_storage.hpp>

Public Types
using	FrameAllocatorType = memory::GrowableAllocator< memory::FrameAllocator >
using	FrameCommandAllocator = memory::STLGrowableAllocator< std::unique_ptr< Command >, memory::FrameAllocator >
using	FrameCommandVector = std::vector< std::unique_ptr< Command >, FrameCommandAllocator >

Public Member Functions
	SystemLocalStorage ()
	Constructs system local storage with default frame allocator capacity.
	SystemLocalStorage (size_t frame_allocator_capacity)
	Constructs system local storage with specified frame allocator capacity.
	SystemLocalStorage (const SystemLocalStorage &)=delete
	SystemLocalStorage (SystemLocalStorage &&) noexcept=default
	~SystemLocalStorage ()=default
SystemLocalStorage &	operator= (const SystemLocalStorage &)=delete
SystemLocalStorage &	operator= (SystemLocalStorage &&) noexcept=default
void	Clear ()
	Clears all stored commands and events.
void	ClearAll ()
	Clears commands, events, and resets the frame allocator.
template<CommandTrait T, typename... Args> requires std::constructible_from<T, Args...>
void	EmplaceCommand (Args &&... args)
	Adds a command to the local command buffer.
void	AddCommand (std::unique_ptr< Command > command)
	Adds a pre-constructed command to the local buffer.
void	ReserveCommands (size_t capacity)
	Reserves space for commands.
template<EventTrait T>
void	WriteEvent (const T &event)
	Writes an event to the local event queue.
template<std::ranges::sized_range R> requires EventTrait<std::ranges::range_value_t<R>>
void	WriteEventBulk (const R &events)
	Writes multiple events to the local event queue in bulk.
void	ResetFrameAllocator () noexcept
	Resets the frame allocator, freeing all temporary allocations.
FrameCommandAllocator	CreateFrameCommandAllocator () noexcept
	Creates a frame-allocated command allocator.
bool	Empty () const noexcept
	Checks if both commands and events are empty.
size_t	CommandCount () const noexcept
	Gets the number of commands in the buffer.
memory::AllocatorStats	FrameAllocatorStats () const noexcept
	Gets frame allocator statistics.
size_t	FrameAllocatorCapacity () const noexcept
	Gets total capacity of the frame allocator across all internal allocators.
auto	GetCommands () noexcept -> std::vector< std::unique_ptr< Command > > &
	Gets reference to the command buffer.
auto	GetCommands () const noexcept -> const std::vector< std::unique_ptr< Command > > &
	Gets const reference to the command buffer.
EventQueue &	GetEventQueue () noexcept
	Gets reference to the event queue.
const EventQueue &	GetEventQueue () const noexcept
	Gets const reference to the event queue.
FrameAllocatorType &	FrameAllocator () noexcept
	Gets reference to the frame allocator.
const FrameAllocatorType &	FrameAllocator () const noexcept
	Gets const reference to the frame allocator.

Detailed Description

Local storage for system-specific data (commands, events, and temporary allocations).

Each system gets its own local storage during execution to avoid contention. After system execution, the local storage is flushed to the appropriate global queues.

The frame allocator is designed for temporary per-frame allocations within a system. It uses a growable allocator internally to automatically expand if the initial capacity is exceeded. The allocator should be reset at frame boundaries or after each system execution.

Command metadata uses a standard heap-allocated vector to ensure safe cross-frame and cross-thread transfer. For systems that need maximum performance and don't transfer commands across frames, use CreateFrameAllocatedCommandBuffer() which uses the frame allocator.

Note

Not thread-safe - each system has its own instance.

Definition at line 44 of file system_local_storage.hpp.

Member Typedef Documentation

FrameAllocatorType

using helios::ecs::details::SystemLocalStorage::FrameAllocatorType = memory::GrowableAllocator<memory::FrameAllocator>

Examples

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

Definition at line 46 of file system_local_storage.hpp.

FrameCommandAllocator

using helios::ecs::details::SystemLocalStorage::FrameCommandAllocator = memory::STLGrowableAllocator<std::unique_ptr<Command>, memory::FrameAllocator>

Definition at line 47 of file system_local_storage.hpp.

FrameCommandVector

using helios::ecs::details::SystemLocalStorage::FrameCommandVector = std::vector<std::unique_ptr<Command>, FrameCommandAllocator>

Definition at line 48 of file system_local_storage.hpp.

Constructor & Destructor Documentation

SystemLocalStorage() [1/4]

helios::ecs::details::SystemLocalStorage::SystemLocalStorage ( )

inline

Constructs system local storage with default frame allocator capacity.

Definition at line 53 of file system_local_storage.hpp.

: frame_allocator_(kDefaultFrameAllocatorCapacity) {}

SystemLocalStorage() [2/4]

helios::ecs::details::SystemLocalStorage::SystemLocalStorage ( size_t  frame_allocator_capacity )

inlineexplicit

Constructs system local storage with specified frame allocator capacity.

Parameters

frame_allocator_capacity

Initial capacity for the frame allocator in bytes

Definition at line 59 of file system_local_storage.hpp.

: frame_allocator_(frame_allocator_capacity) {}

SystemLocalStorage() [3/4]

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

delete

SystemLocalStorage() [4/4]

helios::ecs::details::SystemLocalStorage::SystemLocalStorage ( SystemLocalStorage &&  )

defaultnoexcept

~SystemLocalStorage()

helios::ecs::details::SystemLocalStorage::~SystemLocalStorage ( )

default

Member Function Documentation

AddCommand()

void helios::ecs::details::SystemLocalStorage::AddCommand ( std::unique_ptr< Command >  command )

inline

Adds a pre-constructed command to the local buffer.

Parameters

command

Unique pointer to command

Definition at line 207 of file system_local_storage.hpp.

                                                                         {
  HELIOS_ASSERT(command != nullptr, "Failed to add command: command is null!");
  commands_.push_back(std::move(command));
}

Clear()

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

inline

Clears all stored commands and events.

Note

Does not reset the frame allocator. Call ResetFrameAllocator() separately.

Definition at line 212 of file system_local_storage.hpp.

                                      {
  commands_.clear();
  events_.Clear();
}

ClearAll()

void helios::ecs::details::SystemLocalStorage::ClearAll ( )

inline

Clears commands, events, and resets the frame allocator.

Call this at frame boundaries to reclaim all temporary memory.

Definition at line 217 of file system_local_storage.hpp.

                                         {
  Clear();
  ResetFrameAllocator();
}

CommandCount()

size_t helios::ecs::details::SystemLocalStorage::CommandCount ( ) const

inlinenoexcept

Gets the number of commands in the buffer.

Returns

Count of commands

Definition at line 148 of file system_local_storage.hpp.

{ return commands_.size(); }

CreateFrameCommandAllocator()

FrameCommandAllocator helios::ecs::details::SystemLocalStorage::CreateFrameCommandAllocator ( )

inlinenoexcept

Creates a frame-allocated command allocator.

Use this for temporary command buffers that don't outlive the current frame. More efficient than heap allocation for short-lived command storage.

Returns

Frame command allocator instance

Definition at line 134 of file system_local_storage.hpp.

                                                                             {
    return FrameCommandAllocator(frame_allocator_);
  }

EmplaceCommand()

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

void helios::ecs::details::SystemLocalStorage::EmplaceCommand ( Args &&...  args )

inline

Adds a command to the local command buffer.

Template Parameters

T	Command type
Args	Constructor argument types

Parameters

args	Arguments to forward to command constructor

Definition at line 87 of file system_local_storage.hpp.

                                      {
    commands_.push_back(std::make_unique<T>(std::forward<Args>(args)...));
  }

Empty()

bool helios::ecs::details::SystemLocalStorage::Empty ( ) const

inlinenoexcept

Checks if both commands and events are empty.

Returns

True if no commands or events are stored, false otherwise

Definition at line 142 of file system_local_storage.hpp.

{ return commands_.empty() && events_.Empty(); }

FrameAllocator() [1/2]

const FrameAllocatorType & helios::ecs::details::SystemLocalStorage::FrameAllocator ( ) const

inlinenoexcept

Gets const reference to the frame allocator.

Warning

Data allocated with the frame allocator is only valid for the current frame.

Returns

Const reference to the growable frame allocator

Definition at line 199 of file system_local_storage.hpp.

{ return frame_allocator_; }

FrameAllocator() [2/2]

FrameAllocatorType & helios::ecs::details::SystemLocalStorage::FrameAllocator ( )

inlinenoexcept

Gets reference to the frame allocator.

Use this allocator for temporary per-frame allocations that don't need individual deallocation. Memory is reclaimed when ResetFrameAllocator() is called.

Returns

Reference to the growable frame allocator

Examples

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

Definition at line 192 of file system_local_storage.hpp.

{ return frame_allocator_; }

FrameAllocatorCapacity()

size_t helios::ecs::details::SystemLocalStorage::FrameAllocatorCapacity ( ) const

inlinenoexcept

Gets total capacity of the frame allocator across all internal allocators.

Returns

Total capacity in bytes

Definition at line 160 of file system_local_storage.hpp.

{ return frame_allocator_.TotalCapacity(); }

FrameAllocatorStats()

memory::AllocatorStats helios::ecs::details::SystemLocalStorage::FrameAllocatorStats ( ) const

inlinenoexcept

Gets frame allocator statistics.

Returns

Allocator statistics with current usage information

Examples

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

Definition at line 154 of file system_local_storage.hpp.

{ return frame_allocator_.Stats(); }

GetCommands() [1/2]

auto helios::ecs::details::SystemLocalStorage::GetCommands ( ) const -> const std::vector<std::unique_ptr<Command>>&

inlinenoexcept

Gets const reference to the command buffer.

Returns

Const reference to command vector

Definition at line 172 of file system_local_storage.hpp.

{ return commands_; }

GetCommands() [2/2]

auto helios::ecs::details::SystemLocalStorage::GetCommands ( ) -> std::vector<std::unique_ptr<Command>>&

inlinenoexcept

Gets reference to the command buffer.

Returns

Reference to command vector

Definition at line 166 of file system_local_storage.hpp.

{ return commands_; }

GetEventQueue() [1/2]

const EventQueue & helios::ecs::details::SystemLocalStorage::GetEventQueue ( ) const

inlinenoexcept

Gets const reference to the event queue.

Returns

Const reference to event queue

Definition at line 184 of file system_local_storage.hpp.

{ return events_; }

GetEventQueue() [2/2]

EventQueue & helios::ecs::details::SystemLocalStorage::GetEventQueue ( )

inlinenoexcept

Gets reference to the event queue.

Returns

Reference to event queue

Definition at line 178 of file system_local_storage.hpp.

{ return events_; }

operator=() [1/2]

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

delete

operator=() [2/2]

SystemLocalStorage & helios::ecs::details::SystemLocalStorage::operator= ( SystemLocalStorage &&  )

defaultnoexcept

ReserveCommands()

void helios::ecs::details::SystemLocalStorage::ReserveCommands ( size_t  capacity )

inline

Reserves space for commands.

Parameters

capacity

Number of commands to reserve space for

Definition at line 101 of file system_local_storage.hpp.

{ commands_.reserve(capacity); }

ResetFrameAllocator()

void helios::ecs::details::SystemLocalStorage::ResetFrameAllocator ( )

inlinenoexcept

Resets the frame allocator, freeing all temporary allocations.

Call this at frame boundaries or after system execution to reclaim memory.

Warning

All pointers obtained from the frame allocator become invalid after this call. Do not store references or pointers to frame-allocated data beyond the current frame.

Definition at line 126 of file system_local_storage.hpp.

{ frame_allocator_.Reset(); }

WriteEvent()

template<EventTrait T>

void helios::ecs::details::SystemLocalStorage::WriteEvent ( const T &  event )

inline

Writes an event to the local event queue.

Template Parameters

T	Event type

Parameters

event

Event to store

Examples

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

Definition at line 223 of file system_local_storage.hpp.

                                                         {
  if (!events_.IsRegistered<T>()) {
    events_.Register<T>();
  }
  events_.Write(event);
}

WriteEventBulk()

template<std::ranges::sized_range R>
requires EventTrait<std::ranges::range_value_t<R>>

void helios::ecs::details::SystemLocalStorage::WriteEventBulk ( const R &  events )

inline

Writes multiple events to the local event queue in bulk.

Template Parameters

R	Range of events

Parameters

events

Range of events to store

Examples

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

Definition at line 232 of file system_local_storage.hpp.

                                                              {
  using EventType = std::ranges::range_value_t<R>;
  if (!events_.IsRegistered<EventType>()) {
    events_.Register<EventType>();
  }
  events_.WriteBulk(events);
}