helios::ecs::details::EventManager Class Reference

Manages event lifecycle with double buffering and registration tracking. More...

#include <event_manager.hpp>

Public Member Functions
	EventManager ()=default
	EventManager (const EventManager &)=delete
	EventManager (EventManager &&) noexcept=default
	~EventManager ()=default
EventManager &	operator= (const EventManager &)=delete
EventManager &	operator= (EventManager &&) noexcept=default
void	Clear () noexcept
	Clears all events and registration data.
void	ClearAllQueues () noexcept
	Clears all event queues without removing registration data.
template<EventTrait T>
void	ManualClear ()
	Manually clears events of a specific type from current and previous queues.
void	Update ()
	Updates event lifecycle - swaps buffers and clears old events.
template<EventTrait T>
void	RegisterEvent ()
	Registers an event type for use.
template<EventTrait... Events> requires (sizeof...(Events) > 1)
void	RegisterEvents ()
	Registers multiple event types for use.
template<EventTrait T>
void	Write (const T &event)
	Writes a single event to the current queue.
template<std::ranges::sized_range R> requires EventTrait<std::ranges::range_value_t<R>>
void	WriteBulk (const R &events)
	Writes multiple events to the queue in bulk.
template<EventTrait T>
auto	Read () const -> std::vector< T >
	Reads all events of a specific type from current and previous queues.
template<EventTrait T, typename OutIt > requires std::output_iterator<std::remove_reference_t<OutIt>, T>
void	ReadInto (OutIt out) const
	Reads events of a specific type into a provided output iterator.
void	Merge (EventQueue &other)
	Merges events from another EventQueue into the current queue.
template<EventTrait T>
bool	IsRegistered () const noexcept
	Checks if an event type is registered.
bool	Empty () const noexcept
	Checks if both queues are empty.
template<EventTrait T>
bool	HasEvents () const
	Checks if events of a specific type exist in either queue.
template<EventTrait T>
const EventMetadata *	GetMetadata () const noexcept
	Gets metadata for a registered event.
size_t	GetCurrentFrame () const noexcept
	Gets the current frame number.
size_t	RegisteredEventCount () const noexcept
	Gets the number of registered event types.
const EventQueue &	GetCurrentQueue () const noexcept
	Gets reference to current event queue (for testing/debugging).
const EventQueue &	GetPreviousQueue () const noexcept
	Gets reference to previous event queue (for testing/debugging).

Detailed Description

Manages event lifecycle with double buffering and registration tracking.

Implements Bevy-style event management with:

• Double buffering: events persist for one full update cycle
• Explicit registration: events must be registered before use
• Automatic clearing: events are cleared after their lifecycle expires
• Manual control: users can opt-out of auto-clearing for custom events

Event Lifecycle:

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

Note

Not thread-safe.

Definition at line 47 of file event_manager.hpp.

Constructor & Destructor Documentation

EventManager() [1/3]

helios::ecs::details::EventManager::EventManager ( )

default

EventManager() [2/3]

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

delete

EventManager() [3/3]

helios::ecs::details::EventManager::EventManager ( EventManager &&  )

defaultnoexcept

~EventManager()

helios::ecs::details::EventManager::~EventManager ( )

default

Member Function Documentation

Clear()

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

inlinenoexcept

Clears all events and registration data.

Definition at line 221 of file event_manager.hpp.

                                         {
  registered_events_.clear();
  current_queue_.Clear();
  previous_queue_.Clear();
  current_frame_ = 0;
}

ClearAllQueues()

void helios::ecs::details::EventManager::ClearAllQueues ( )

inlinenoexcept

Clears all event queues without removing registration data.

Useful for manually clearing events while preserving event types. Events can still be written/read after calling this method. Registration metadata and frame counter are preserved.

Definition at line 228 of file event_manager.hpp.

                                                  {
  current_queue_.Clear();
  previous_queue_.Clear();
}

Empty()

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

inlinenoexcept

Checks if both queues are empty.

Returns

True if no events exist in either queue, false otherwise

Definition at line 168 of file event_manager.hpp.

{ return current_queue_.Empty() && previous_queue_.Empty(); }

GetCurrentFrame()

size_t helios::ecs::details::EventManager::GetCurrentFrame ( ) const

inlinenoexcept

Gets the current frame number.

Returns

Current frame counter value

Definition at line 192 of file event_manager.hpp.

{ return current_frame_; }

GetCurrentQueue()

const EventQueue & helios::ecs::details::EventManager::GetCurrentQueue ( ) const

inlinenoexcept

Gets reference to current event queue (for testing/debugging).

Returns

Const reference to current queue

Definition at line 204 of file event_manager.hpp.

{ return current_queue_; }

GetMetadata()

template<EventTrait T>

const EventMetadata * helios::ecs::details::EventManager::GetMetadata ( ) const

inlinenoexcept

Gets metadata for a registered event.

Template Parameters

T	Event type

Returns

Pointer to metadata, or nullptr if not registered

Definition at line 350 of file event_manager.hpp.

                                                                     {
  constexpr EventTypeId type_id = EventTypeIdOf<T>();
  const auto it = registered_events_.find(type_id);
  return it != registered_events_.end() ? &it->second : nullptr;
}

GetPreviousQueue()

const EventQueue & helios::ecs::details::EventManager::GetPreviousQueue ( ) const

inlinenoexcept

Gets reference to previous event queue (for testing/debugging).

Returns

Const reference to previous queue

Definition at line 210 of file event_manager.hpp.

{ return previous_queue_; }

HasEvents()

template<EventTrait T>

bool helios::ecs::details::EventManager::HasEvents ( ) const

inline

Checks if events of a specific type exist in either queue.

Template Parameters

T	Event type

Returns

True if events of type T exist, false otherwise

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/ecs/event_reader.hpp.

Definition at line 176 of file event_manager.hpp.

                                       {
    return current_queue_.HasEvents<T>() || previous_queue_.HasEvents<T>();
  }

IsRegistered()

template<EventTrait T>

bool helios::ecs::details::EventManager::IsRegistered ( ) const

inlinenoexcept

Checks if an event type is registered.

Template Parameters

T	Event type

Returns

True if event is registered, false otherwise

Definition at line 357 of file event_manager.hpp.

                                                      {
  constexpr EventTypeId type_id = EventTypeIdOf<T>();
  return registered_events_.contains(type_id);
}

ManualClear()

template<EventTrait T>

void helios::ecs::details::EventManager::ManualClear ( )

inline

Manually clears events of a specific type from current and previous queues.

Should be used for manually-managed events (clear_policy = kManual). Can also be used as an override for automatic events if needed.

Warning

Triggers assertion if event is not registered.

Template Parameters

T	Event type

Definition at line 338 of file event_manager.hpp.

                                      {
  HELIOS_ASSERT(registered_events_.contains(EventTypeIdOf<T>()),
                "Failed to manual clear events '{}': Event is not registered!", EventNameOf<T>());
 
  // Note: We allow manual clearing for all events (automatic or manual) as an override
  // This can be useful for debugging or special cases
 
  current_queue_.Clear<T>();
  previous_queue_.Clear<T>();
}

Merge()

void helios::ecs::details::EventManager::Merge ( EventQueue &  other )

inline

Merges events from another EventQueue into the current queue.

Parameters

other

Event queue to merge from (typically from SystemLocalStorage)

Definition at line 332 of file event_manager.hpp.

                                                 {
  current_queue_.Merge(other);
  other.Clear();
}

operator=() [1/2]

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

delete

operator=() [2/2]

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

defaultnoexcept

Read()

template<EventTrait T>

auto helios::ecs::details::EventManager::Read ( ) const -> std::vector<T>

inline

Reads all events of a specific type from current and previous queues.

Events from the current frame and previous frame are returned, implementing double buffering for reliable event delivery.

Warning

Triggers assertion if event is not registered.

Template Parameters

T	Event type

Returns

Vector containing all events of type T from both buffers

Definition at line 306 of file event_manager.hpp.

                                                     {
  HELIOS_ASSERT(registered_events_.contains(EventTypeIdOf<T>()), "Failed to read events '{}': Event is not registered!",
                EventNameOf<T>());
 
  std::vector<T> result;
  result.reserve(previous_queue_.TypeCount() + current_queue_.TypeCount());
 
  // Read from previous queue (events from last frame)
  previous_queue_.ReadInto<T>(std::back_inserter(result));
 
  // Read from current queue (events from this frame)
  current_queue_.ReadInto<T>(std::back_inserter(result));
 
  return result;
}

ReadInto()

template<EventTrait T, typename OutIt >
requires std::output_iterator<std::remove_reference_t<OutIt>, T>

void helios::ecs::details::EventManager::ReadInto ( OutIt  out ) const

inline

Reads events of a specific type into a provided output iterator.

Reads from current and previous queues without intermediate allocations.

Warning

Triggers assertion if event is not registered.

Template Parameters

T	Event type
OutIt	Output iterator type

Parameters

out	Output iterator to write events into

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/ecs/event_reader.hpp.

Definition at line 324 of file event_manager.hpp.

                                                  {
  HELIOS_ASSERT(registered_events_.contains(EventTypeIdOf<T>()),
                "Failed to read events '{}' into: Event is not registered!", EventNameOf<T>());
 
  previous_queue_.ReadInto<T>(out);
  current_queue_.ReadInto<T>(std::move(out));
}

RegisteredEventCount()

size_t helios::ecs::details::EventManager::RegisteredEventCount ( ) const

inlinenoexcept

Gets the number of registered event types.

Returns

Count of registered events

Definition at line 198 of file event_manager.hpp.

{ return registered_events_.size(); }

RegisterEvent()

template<EventTrait T>

void helios::ecs::details::EventManager::RegisterEvent ( )

inline

Registers an event type for use.

Uses the event's GetClearPolicy() if available, otherwise defaults to kAutomatic.

Warning

Triggers assertion if event is already registered.

Template Parameters

T	Event type

Definition at line 268 of file event_manager.hpp.

                                        {
  constexpr EventTypeId type_id = EventTypeIdOf<T>();
  constexpr std::string_view name = EventNameOf<T>();
  constexpr EventClearPolicy clear_policy = EventClearPolicyOf<T>();
 
  HELIOS_ASSERT(!registered_events_.contains(type_id), "Failed to register event '{}': Event already registered!",
                name);
 
  registered_events_.emplace(
      type_id, EventMetadata{
                   .type_id = type_id, .name = name, .clear_policy = clear_policy, .frame_registered = current_frame_});
 
  current_queue_.Register<T>();
  previous_queue_.Register<T>();
 
  constexpr std::string_view policy_str = (clear_policy == EventClearPolicy::kAutomatic) ? "automatic" : "manual";
  HELIOS_DEBUG("Registered event '{}' (clear_policy: {})", name, policy_str);
}

RegisterEvents()

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

void helios::ecs::details::EventManager::RegisterEvents ( )

inline

Registers multiple event types for use.

Each event uses its own GetClearPolicy() if available.

Warning

Triggers assertion if any event is already registered.

Template Parameters

Events

Event types to register

Definition at line 104 of file event_manager.hpp.

                        {
    (RegisterEvent<Events>(), ...);
  }

Update()

void helios::ecs::details::EventManager::Update ( )

inline

Updates event lifecycle - swaps buffers and clears old events.

Should be called at the end of each update cycle. Clears previous queue, moves current to previous, creates new current queue.

Definition at line 233 of file event_manager.hpp.

                                 {
  // Double-queue double buffering implementation with selective clearing:
  // 1. Selectively clear auto_clear events from previous_queue_ (events that are now 2 frames old)
  // 2. Merge current queue into previous queue (preserving non-auto_clear events)
  // 3. Create new empty current queue for next frame
  //
  // This ensures:
  // - auto_clear=true events persist for exactly 1 full update cycle
  // - auto_clear=false events persist indefinitely until manually cleared
  //
  // Frame lifecycle:
  // - Frame N: Event written to current_queue_
  // - Frame N+1: Event readable from previous_queue_ (after merge)
  // - Frame N+2: auto_clear=true events cleared, auto_clear=false events remain
 
  // Step 1: Clear automatic events from previous queue (events that are 2+ frames old)
  for (const auto& [type_id, metadata] : registered_events_) {
    if (metadata.clear_policy == EventClearPolicy::kAutomatic) {
      previous_queue_.ClearByTypeId(type_id);
    }
  }
 
  // Step 2: Merge current queue into previous queue
  // This preserves non-auto_clear events from previous queue while adding current frame's events
  previous_queue_.Merge(current_queue_);
 
  // Step 3: Clear current queue for next frame (clear each registered type individually)
  for (const auto& [type_id, metadata] : registered_events_) {
    current_queue_.ClearByTypeId(type_id);
  }
 
  ++current_frame_;
}

Write()

template<EventTrait T>

void helios::ecs::details::EventManager::Write ( const T &  event )

inline

Writes a single event to the current queue.

Warning

Triggers assertion if event is not registered.

Template Parameters

T	Event type

Parameters

event

Event to write

Definition at line 288 of file event_manager.hpp.

                                              {
  HELIOS_ASSERT(registered_events_.contains(EventTypeIdOf<T>()), "Failed to write event '{}': Event is not registered!",
                EventNameOf<T>());
 
  current_queue_.Write(event);
}

WriteBulk()

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

void helios::ecs::details::EventManager::WriteBulk ( const R &  events )

inline

Writes multiple events to the queue in bulk.

Warning

Triggers assertion if event type does not exist.

Template Parameters

R	Range of events

Parameters

events

Range of events to store

Definition at line 297 of file event_manager.hpp.

                                                   {
  using EventType = std::ranges::range_value_t<R>;
  HELIOS_ASSERT(registered_events_.contains(EventTypeIdOf<EventType>()),
                "Failed to write bulk event '{}': Event is not registered!", EventNameOf<EventType>());
 
  current_queue_.WriteBulk(events);
}