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

Central coordinator for message lifecycle with double buffering and consumed message removal. More...

#include <manager.hpp>

Public Types

using size_type = size_t

Public Member Functions

 MessageManager ()=default
 MessageManager (const MessageManager &)=delete
 MessageManager (MessageManager &&) noexcept=default
 ~MessageManager ()=default
MessageManager & operator= (const MessageManager &)=delete
MessageManager & operator= (MessageManager &&) noexcept=default
void Clear () noexcept
 Clears all messages, consumed flags, and registration data.
void ClearAllQueues () noexcept
 Clears all message data without removing registrations.
template<typename Alloc>
void Update (const ConsumedMessagesRegistry< Alloc > &consumed_registry)
 Updates message lifecycle — applies consumed messages, swaps buffers, clears old messages.
void Update ()
 Updates message lifecycle without any consumed message processing.
template<typename Alloc>
void ApplyConsumed (const ConsumedMessagesRegistry< Alloc > &merged_consumed)
 Applies consumed indices to both queues, removing consumed messages in-place.
template<AnyMessageTrait... Messages>
requires (sizeof...(Messages) > 0)
void Register ()
 Registers multiple message types.
template<MessageTrait T>
void Write (T &&message)
 Writes a single regular message to the current queue.
template<AsyncMessageTrait T>
void WriteAsync (T &&message)
 Writes a single async message to the async queue.
template<std::ranges::input_range R>
requires MessageTrait<std::ranges::range_value_t<R>>
void WriteBulk (R &&messages)
 Writes multiple regular messages to the current queue in bulk.
template<std::ranges::input_range R>
requires AsyncMessageTrait<std::ranges::range_value_t<R>>
void WriteAsyncBulk (R &&messages)
 Writes multiple async messages to the async queue in bulk.
template<MessageTrait T>
void ManualClear ()
 Manually clears regular messages of a specific type from both queues.
template<AsyncMessageTrait T>
void ManualAsyncClear ()
 Manually clears async messages of a specific type from the queue.
template<typename OtherAllocator>
void MergeLocalMessages (const MessageQueue< OtherAllocator > &local)
 Merges messages from a local MessageQueue into the current queue.
template<typename OtherAllocator>
void MergeLocalMessages (MessageQueue< OtherAllocator > &&local)
 Merges messages from a local MessageQueue into the current queue.
template<AnyMessageTrait T>
bool IsRegistered () const noexcept
 Checks if an message type (regular or async) is registered.
bool HasMessages () const noexcept
 Checks if any messages exist across regular and async queues.
template<MessageTrait T>
bool HasMessages () const noexcept
 Checks if regular messages of a specific type exist in either queue.
template<AsyncMessageTrait T>
bool HasAsyncMessages () const noexcept
 Checks if async messages of a specific type exist.
template<MessageTrait T>
auto PreviousMessages () const noexcept -> std::span< const T >
 Gets a const span of messages of a specific type from the previous queue.
template<MessageTrait T>
auto CurrentMessages () const noexcept -> std::span< const T >
 Gets a const span of messages of a specific type from the current queue.
template<AnyMessageTrait T>
const MessageMetadata * Metadata () const noexcept
 Gets metadata for a registered message type.
size_type RegisteredMessageCount () const noexcept
 Gets the number of registered message types (regular + async).
const MessageQueue & CurrentQueue () const noexcept
 Gets const reference to current message queue.
MessageQueue & CurrentQueue () noexcept
 Gets mutable reference to current message queue.
const MessageQueue & PreviousQueue () const noexcept
 Gets const reference to previous message queue.
MessageQueue & PreviousQueue () noexcept
 Gets mutable reference to previous message queue.
AsyncMessageQueue & AsyncQueue () noexcept
 Gets the async message queue (for creating tokens, etc.).
const AsyncMessageQueue & AsyncQueue () const noexcept
 Gets the async message queue (const).

Detailed Description

Central coordinator for message lifecycle with double buffering and consumed message removal.

Implements message management with:

  • Double buffering: messages persist for one full update cycle (two frames)
  • Explicit registration: messages must be registered before use
  • Automatic clearing: messages are cleared after their lifecycle expires
  • Manual control: users can opt-out of auto-clearing
  • Consumed message removal: at Update time, consumed messages are physically removed from queues without additional heap allocation

Message Lifecycle:

  • Frame N: Messages written to current queue
  • Frame N+1: Messages readable from previous queue (after swap)
  • Frame N+2: Messages cleared from previous queue (automatic policy)

Consumed messages are removed at Update time based on merged per-system ConsumedMessagesRegistry instances. Each system writes to its own registry during parallel execution, and all registries are merged and applied here.

Note
Partially thread-safe.

Definition at line 54 of file manager.hpp.

Member Typedef Documentation

◆ size_type

using helios::ecs::MessageManager::size_type = size_t

Definition at line 56 of file manager.hpp.

Constructor & Destructor Documentation

◆ MessageManager() [1/3]

helios::ecs::MessageManager::MessageManager ( )
default

◆ MessageManager() [2/3]

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

◆ MessageManager() [3/3]

helios::ecs::MessageManager::MessageManager ( MessageManager && )
defaultnoexcept

◆ ~MessageManager()

helios::ecs::MessageManager::~MessageManager ( )
default

Member Function Documentation

◆ ApplyConsumed()

template<typename Alloc>
void helios::ecs::MessageManager::ApplyConsumed ( const ConsumedMessagesRegistry< Alloc > & merged_consumed)
inline

Applies consumed indices to both queues, removing consumed messages in-place.

For each type with consumed entries, indices [0, prev_count) target previous messages and indices [prev_count, prev_count + curr_count) target current messages (offset by prev_count). No buffer swap occurs.

Note
Not thread-safe.
Template Parameters
AllocAllocator type of the consumed registry
Parameters
merged_consumedThe combined consumed registry from all systems

Definition at line 422 of file manager.hpp.

◆ AsyncQueue() [1/2]

const AsyncMessageQueue & helios::ecs::MessageManager::AsyncQueue ( ) const
inlinenodiscardnoexcept

Gets the async message queue (const).

Note
Thread-safe.
Returns
Const reference to the async message queue

Definition at line 345 of file manager.hpp.

◆ AsyncQueue() [2/2]

AsyncMessageQueue & helios::ecs::MessageManager::AsyncQueue ( )
inlinenodiscardnoexcept

Gets the async message queue (for creating tokens, etc.).

Note
Thread-safe.
Returns
Reference to the async message queue

Definition at line 336 of file manager.hpp.

◆ Clear()

void helios::ecs::MessageManager::Clear ( )
inlinenoexcept

Clears all messages, consumed flags, and registration data.

Note
Not thread-safe.

Definition at line 363 of file manager.hpp.

◆ ClearAllQueues()

void helios::ecs::MessageManager::ClearAllQueues ( )
inlinenoexcept

Clears all message data without removing registrations.

Note
Not thread-safe.

Definition at line 370 of file manager.hpp.

◆ CurrentMessages()

template<MessageTrait T>
auto helios::ecs::MessageManager::CurrentMessages ( ) const -> std::span< const T >
inlinenodiscardnoexcept

Gets a const span of messages of a specific type from the current queue.

Note
Thread safe for concurrent reads.
Template Parameters
TMessage type satisfying MessageTrait
Returns
Span of const messages

Definition at line 271 of file manager.hpp.

◆ CurrentQueue() [1/2]

const MessageQueue & helios::ecs::MessageManager::CurrentQueue ( ) const
inlinenodiscardnoexcept

Gets const reference to current message queue.

Note
Thread-safe.
Returns
Const reference to current queue

Definition at line 300 of file manager.hpp.

◆ CurrentQueue() [2/2]

MessageQueue & helios::ecs::MessageManager::CurrentQueue ( )
inlinenodiscardnoexcept

Gets mutable reference to current message queue.

Note
Not thread-safe.
Returns
Mutable reference to current queue

Definition at line 309 of file manager.hpp.

◆ HasAsyncMessages()

template<AsyncMessageTrait T>
bool helios::ecs::MessageManager::HasAsyncMessages ( ) const
inlinenodiscardnoexcept

Checks if async messages of a specific type exist.

Note
Thread safe.
Template Parameters
TAsync message type satisfying AsyncMessageTrait
Returns
True if async messages exist, false otherwise

Definition at line 604 of file manager.hpp.

◆ HasMessages() [1/2]

template<MessageTrait T>
bool helios::ecs::MessageManager::HasMessages ( ) const
inlinenodiscardnoexcept

Checks if regular messages of a specific type exist in either queue.

Note
Thread safe for concurrent reads.
Template Parameters
TMessage type satisfying MessageTrait
Returns
True if messages exist, false otherwise

Definition at line 594 of file manager.hpp.

◆ HasMessages() [2/2]

bool helios::ecs::MessageManager::HasMessages ( ) const
inlinenodiscardnoexcept

Checks if any messages exist across regular and async queues.

Note
Thread safe for concurrent reads.
Returns
True if at least one message exists, false otherwise

Definition at line 228 of file manager.hpp.

◆ IsRegistered()

template<AnyMessageTrait T>
bool helios::ecs::MessageManager::IsRegistered ( ) const
inlinenodiscardnoexcept

Checks if an message type (regular or async) is registered.

Note
Thread safe for concurrent reads.
Template Parameters
TMessage type satisfying AnyMessageTrait
Returns
True if the message type is registered, false otherwise

Definition at line 219 of file manager.hpp.

◆ ManualAsyncClear()

template<AsyncMessageTrait T>
void helios::ecs::MessageManager::ManualAsyncClear ( )
inline

Manually clears async messages of a specific type from the queue.

Note
Thread-safe.
Warning
Triggers assertion if the message type is not registered.
Template Parameters
TAsync message type satisfying AsyncMessageTrait

Definition at line 586 of file manager.hpp.

◆ ManualClear()

template<MessageTrait T>
void helios::ecs::MessageManager::ManualClear ( )
inline

Manually clears regular messages of a specific type from both queues.

Note
Not thread-safe.
Warning
Triggers assertion if the message type is not registered.
Template Parameters
TMessage type satisfying MessageTrait

Definition at line 577 of file manager.hpp.

◆ MergeLocalMessages() [1/2]

template<typename OtherAllocator>
void helios::ecs::MessageManager::MergeLocalMessages ( const MessageQueue< OtherAllocator > & local)
inline

Merges messages from a local MessageQueue into the current queue.

Note
Not thread-safe.

Used to flush a per-system write buffer into the global message state. Typically called after a system finishes execution.

Template Parameters
OtherAllocatorAllocator type used by the local MessageQueue
Parameters
localLocal message queue to merge from (will be left in a valid but empty state)

Definition at line 195 of file manager.hpp.

◆ MergeLocalMessages() [2/2]

template<typename OtherAllocator>
void helios::ecs::MessageManager::MergeLocalMessages ( MessageQueue< OtherAllocator > && local)
inline

Merges messages from a local MessageQueue into the current queue.

Note
Not thread-safe.

Rvalue overload that consumes the local queue.

Template Parameters
OtherAllocatorAllocator type used by the local MessageQueue
Parameters
localLocal message queue to merge from (will be left in a valid but empty state)

Definition at line 208 of file manager.hpp.

◆ Metadata()

template<AnyMessageTrait T>
const MessageMetadata * helios::ecs::MessageManager::Metadata ( ) const
inlinenodiscardnoexcept

Gets metadata for a registered message type.

Note
Thread safe for concurrent reads.
Template Parameters
TMessage type satisfying AnyMessageTrait
Returns
Pointer to metadata, or nullptr if not registered

Definition at line 282 of file manager.hpp.

◆ operator=() [1/2]

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

◆ operator=() [2/2]

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

◆ PreviousMessages()

template<MessageTrait T>
auto helios::ecs::MessageManager::PreviousMessages ( ) const -> std::span< const T >
inlinenodiscardnoexcept

Gets a const span of messages of a specific type from the previous queue.

Note
Thread safe for concurrent reads.
Template Parameters
TMessage type satisfying MessageTrait
Returns
Span of const messages

Definition at line 259 of file manager.hpp.

◆ PreviousQueue() [1/2]

const MessageQueue & helios::ecs::MessageManager::PreviousQueue ( ) const
inlinenodiscardnoexcept

Gets const reference to previous message queue.

Note
Thread-safe.
Returns
Const reference to previous queue

Definition at line 318 of file manager.hpp.

◆ PreviousQueue() [2/2]

MessageQueue & helios::ecs::MessageManager::PreviousQueue ( )
inlinenodiscardnoexcept

Gets mutable reference to previous message queue.

Note
Not thread-safe.
Returns
Mutable reference to previous queue

Definition at line 327 of file manager.hpp.

◆ Register()

template<AnyMessageTrait... Ts>
requires (sizeof...(Messages) > 0)
void helios::ecs::MessageManager::Register ( )
inline

Registers multiple message types.

Note
Not thread-safe.
Warning
Triggers assertion if any message type is already registered.
Template Parameters
MessagesMessage types to register, satisfying AnyMessageTrait

Definition at line 500 of file manager.hpp.

◆ RegisteredMessageCount()

size_type helios::ecs::MessageManager::RegisteredMessageCount ( ) const
inlinenodiscardnoexcept

Gets the number of registered message types (regular + async).

Note
Thread safe for concurrent reads.
Returns
Count of registered messages

Definition at line 291 of file manager.hpp.

◆ Update() [1/2]

void helios::ecs::MessageManager::Update ( )
inline

Updates message lifecycle without any consumed message processing.

Convenience overload when no systems have consumed any messages.

Note
Not thread-safe.

Definition at line 400 of file manager.hpp.

◆ Update() [2/2]

template<typename Alloc>
void helios::ecs::MessageManager::Update ( const ConsumedMessagesRegistry< Alloc > & consumed_registry)
inline

Updates message lifecycle — applies consumed messages, swaps buffers, clears old messages.

Performs the following steps:

  1. Removes consumed messages from previous and current queues.
  2. Clears automatic messages from previous queue.
  3. Merges current queue into previous queue.
  4. Prepares a fresh current queue for the next frame.
    Note
    Not thread-safe.
    Template Parameters
    AllocAllocator type for the consumed registry
    Parameters
    consumed_registryConst References to per-system consumed registry. The caller is responsible for clearing it after this call.

Definition at line 377 of file manager.hpp.

◆ Write()

template<MessageTrait T>
void helios::ecs::MessageManager::Write ( T && message)
inline

Writes a single regular message to the current queue.

Note
Not thread-safe.
Warning
Triggers assertion if the message type is not registered.
Template Parameters
TMessage type satisfying MessageTrait
Parameters
messageMessage to write

Definition at line 541 of file manager.hpp.

◆ WriteAsync()

template<AsyncMessageTrait T>
void helios::ecs::MessageManager::WriteAsync ( T && message)
inline

Writes a single async message to the async queue.

Note
Thread-safe.
Warning
Triggers assertion if the message type is not registered.
Template Parameters
TAsync message type satisfying AsyncMessageTrait
Parameters
messageMessage to write

Definition at line 550 of file manager.hpp.

◆ WriteAsyncBulk()

template<std::ranges::input_range R>
requires AsyncMessageTrait<std::ranges::range_value_t<R>>
void helios::ecs::MessageManager::WriteAsyncBulk ( R && messages)
inline

Writes multiple async messages to the async queue in bulk.

Note
Thread-safe.
Warning
Triggers assertion if the message type is not registered.
Template Parameters
RRange whose value_type satisfies AsyncMessageTrait
Parameters
messagesRange of async messages to write

Definition at line 569 of file manager.hpp.

◆ WriteBulk()

template<std::ranges::input_range R>
requires MessageTrait<std::ranges::range_value_t<R>>
void helios::ecs::MessageManager::WriteBulk ( R && messages)
inline

Writes multiple regular messages to the current queue in bulk.

Note
Not thread-safe.
Warning
Triggers assertion if the message type is not registered.
Template Parameters
RRange whose value_type satisfies MessageTrait
Parameters
messagesRange of messages to write

Definition at line 560 of file manager.hpp.