Ship::Events Class Reference

Tickable event bus that dispatches listeners through Tick(EventID). More...

#include <Events.h>

Inheritance diagram for Ship::Events:

Collaboration diagram for Ship::Events:

Classes
struct	DispatchContext
	Active payload and call-site data for a single in-flight dispatch. More...

Public Member Functions
	Events ()
	Constructs and self-initializes the global event bus component.
EventID	RegisterEvent (const char *name=nullptr)
	Allocates a new internally managed EventID.
ListenerID	RegisterListener (EventID id, EventCallback callback, EventPriority priority=EVENT_PRIORITY_NORMAL, const char *file=nullptr, int line=0)
	Registers a callback listener for an event.
void	UnregisterListener (EventID id, ListenerID listenerId)
	Removes a previously registered listener from an event.
void	RemoveEvent (EventID id)
	Removes an event and all listeners currently registered to it.
void	CallEvent (EventID id, IEvent *event, const char *file=nullptr, int line=0, const char *key=nullptr)
	Dispatches an event by pushing dispatch state and ticking its EventID.
EventRegistration *	GetEventRegistration (EventID id)
	Returns the registration record for an EventID, if present.
std::unordered_map< EventID, EventRegistration > &	GetEventRegistrations ()
	Returns the complete event registry map.
const DispatchContext *	GetActiveDispatchContext () const
	Returns the current top-of-stack dispatch context.
Public Member Functions inherited from Ship::TickableComponent
	TickableComponent (const std::string &name, std::shared_ptr< Context > context, const TickGroup tickGroup=TickGroup::TickGroupDefault, const TickPriority tickPriority=TickPriority::TickPriorityDefault, const std::vector< EventID > &eventIds={})
	Constructs a TickableComponent with EventID subscriptions.
	TickableComponent (const std::string &name, std::shared_ptr< Context > context, const TickGroup tickGroup, const TickPriority tickPriority, const std::vector< std::shared_ptr< Action > > &actions)
	Constructs a TickableComponent with an explicit list of Actions.
virtual	~TickableComponent ()
bool	RegisterWithContext ()
	Registers this component with its Context.
void	UnregisterFromContext ()
	Unregisters this component from its Context.
std::shared_ptr< Context >	GetContext () const
	Returns the Context this component is registered with.
TickGroup	GetTickGroup () const
	Returns the TickGroup this component belongs to.
TickPriority	GetTickPriority () const
	Returns the tick priority within the TickGroup.
uint64_t	GetOrder () const
	Returns a composite order value derived from TickGroup and TickPriority.
TickableComponent &	SetTickGroup (const TickGroup tickGroup)
	Sets the TickGroup for this component.
TickableComponent &	SetTickPriority (const TickPriority tickPriority)
	Sets the tick priority for this component.
TickableComponent &	SetContext (std::shared_ptr< Context > context)
	Changes the Context this component is associated with.
virtual bool	ActionRan (EventID eventId)
	Virtual hook invoked when an EventAction runs on this component.
Public Member Functions inherited from Ship::Tickable
	Tickable (const bool isTicking=true)
	Constructs a Tickable.
	Tickable (const bool isTicking, const std::vector< std::shared_ptr< Action > > &actions)
	Constructs a Tickable with an initial set of Actions.
virtual	~Tickable ()
bool	IsTicking () const
	Returns true if this Tickable is currently ticking.
bool	Start (const bool force=false)
	Starts ticking, enabling EventID-targeted Tick() calls on Actions.
bool	Stop (const bool force=false)
	Stops ticking; subsequent Tick() calls become no-ops.
bool	Tick (EventID eventId)
	Ticks only indexed EventActions whose EventID matches the given ID.
bool	Tick (const std::vector< EventID > &eventIds)
	Ticks only indexed EventActions whose EventID matches one of the given IDs.
template<typename T >
bool	Tick (const std::vector< EventID > &eventIds)
	Ticks Actions matching both type T and one of the given EventIDs.
template<typename T >
bool	Tick (EventID eventId)
	Ticks Actions matching both type T and the given EventID.
EventActionList &	GetActionList ()
	Returns a mutable reference to the internal EventActionList.
const EventActionList &	GetActionList () const
	Returns a const reference to the internal EventActionList.
double	GetTime (const ClockType clockType) const
	Returns the wall-clock time for a profiling checkpoint.
Public Member Functions inherited from Ship::Component
	Component (const std::string &name, std::shared_ptr< Context > context=nullptr)
	Constructs a Component with the given name.
virtual	~Component ()
void	Init (const nlohmann::json &initArgs=nlohmann::json::object())
	Performs one-time initialization of this component.
bool	IsInitialized () const
	Returns true once Init() (or MarkInitialized()) has completed successfully.
const std::string &	GetName () const
	Returns the name of this Component.
std::string	ToString () const
	Returns a human-readable string representation (e.g. "Name (id)").
std::string	ToTreeString (int depth=0) const
	Returns a human-readable tree representation of this component and its children.
	operator std::string () const
	Conversion operator to std::string; equivalent to ToString().
ParentComponentList &	GetParents ()
	Returns a mutable reference to the parent list.
const ParentComponentList &	GetParents () const
	Returns a const reference to the parent list.
ComponentList &	GetChildren ()
	Returns a mutable reference to the child list.
const ComponentList &	GetChildren () const
	Returns a const reference to the child list.
virtual std::shared_ptr< Component >	TryGetSharedComponent () noexcept
	Returns a shared_ptr to this Component when available, otherwise nullptr.
virtual std::shared_ptr< Component >	GetSharedComponent ()
	Returns a shared_ptr to this Component via the correct enable_shared_from_this base.
template<typename T >
bool	HasInChildren () const
	Checks whether any descendant Component matches type T via BFS.
template<typename T >
std::shared_ptr< T >	GetFirstInChildren () const
	Returns the first descendant that matches type T via BFS.
template<typename T >
std::shared_ptr< std::vector< std::shared_ptr< T > > >	GetInChildren () const
	Returns all descendants that match type T via BFS.
template<typename T >
bool	HasInParents () const
	Checks whether any ancestor Component matches type T via BFS.
template<typename T >
std::shared_ptr< T >	GetFirstInParents () const
	Returns the first ancestor that matches type T via BFS.
template<typename T >
std::shared_ptr< std::vector< std::shared_ptr< T > > >	GetInParents () const
	Returns all ancestors that match type T via BFS.
Public Member Functions inherited from Ship::Part
	Part ()
	Constructs a Part and assigns it a unique ID.
	Part (std::shared_ptr< Context > context)
	Constructs a Part with an explicit Context reference and unique ID.
virtual	~Part ()=default
uint64_t	GetId () const
	Returns the unique identifier for this Part.
bool	operator== (const Part &other) const
	Compares two Parts for equality by their unique IDs.
std::shared_ptr< Context >	GetContext () const
	Returns the Context this Part belongs to, or nullptr if unset.
void	SetContext (std::shared_ptr< Context > ctx)
	Sets the Context this Part belongs to.

Additional Inherited Members
Protected Member Functions inherited from Ship::Tickable
virtual bool	CanStart ()
	Permission hook; override to prevent starting. Defaults to true.
virtual bool	CanStop ()
	Permission hook; override to prevent stopping. Defaults to true.
virtual void	Started (const bool forced)
	Notification hook called after the Tickable has been started.
virtual void	Stopped (const bool forced)
	Notification hook called after the Tickable has been stopped.
std::mutex &	GetMutex ()
	Returns a reference to the internal mutex for synchronization. Only available when COMPONENT_THREAD_SAFE is defined.
Protected Member Functions inherited from Ship::Component
virtual void	OnInit (const nlohmann::json &initArgs=nlohmann::json::object())
	Override this to implement component-specific initialization logic.
void	MarkInitialized ()
	Marks this component as initialized without going through Init().
template<typename T >
std::shared_ptr< T >	RequireDependency (const std::shared_ptr< T > &dependency, const std::string &dependencyName) const
	Returns a cached dependency after validating it exists and is initialized.
Protected Member Functions inherited from Ship::Part
virtual void	OnAdded (bool forced)
	Called after this Part has been added to a PartList.
virtual void	OnRemoved (bool forced)
	Called after this Part has been removed from a PartList.

Detailed Description

Tickable event bus that dispatches listeners through Tick(EventID).

Events now owns all registered listeners as ListenerActions in its ActionList. Calling CallEvent() pushes a transient DispatchContext, ticks the matching EventID, and each ListenerAction pulls the active payload from that context during execution.

EventID contract:

• -1 = uninitialized / invalid
• < -1 = internally registered events returned by RegisterEvent()
• >= 0 = user-defined events created on demand when listeners/calls occur

Listeners are invoked synchronously in priority order whenever CallEvent() is called. Any listener may set IEvent::Cancelled to true; CallEvent() does not enforce cancellation itself � the caller is responsible for checking it via the CALL_CANCELLABLE_EVENT macro.

Required Context children: None � Events has no dependencies on other components.

Obtain the instance from Context::GetChildren().GetFirst<Events>().

Typical usage (C++ side):

// Registration (once at startup)
REGISTER_EVENT(MyEvent);
 
// Listening
REGISTER_LISTENER(MyEvent, EVENT_PRIORITY_NORMAL, [](IEvent* e) {
    auto* event = static_cast<MyEvent*>(e);
    // handle...
});
 
// Dispatching
CALL_EVENT(MyEvent, payload);

Constructor & Destructor Documentation

Events()

Ship::Events::Events ( )

inline

Constructs and self-initializes the global event bus component.

The component starts ticking immediately so listener actions can be run as soon as the Events instance is reachable through the active Context.

Member Function Documentation

CallEvent()

void Ship::Events::CallEvent	(	EventID	id,
		IEvent *	event,
		const char *	file = nullptr,
		int	line = 0,
		const char *	key = nullptr
	)

Dispatches an event by pushing dispatch state and ticking its EventID.

ListenerActions matching id are executed through Tick(id) and read the active payload from GetActiveDispatchContext().

Parameters

id	EventID to dispatch.
event	Event payload.
file	Optional source file of the call site.
line	Optional source line of the call site.
key	Optional caller-diagnostic key.

GetActiveDispatchContext()

const DispatchContext * Ship::Events::GetActiveDispatchContext

(

)

const

Returns the current top-of-stack dispatch context.

Returns

Active dispatch context, or nullptr when no event is being dispatched.

GetEventRegistration()

EventRegistration * Ship::Events::GetEventRegistration ( EventID  id )

inline

Returns the registration record for an EventID, if present.

Parameters

id	EventID to look up.

Returns

Pointer to the registration, or nullptr if not found.

GetEventRegistrations()

std::unordered_map< EventID, EventRegistration > & Ship::Events::GetEventRegistrations ( )

inline

Returns the complete event registry map.

Intended for inspection and tooling such as the event debugger.

RegisterEvent()

EventID Ship::Events::RegisterEvent

(

const char *

name = nullptr

)

Allocates a new internally managed EventID.

Parameters

name	Optional human-readable event name for diagnostics.

Returns

A negative EventID less than -1.

RegisterListener()

ListenerID Ship::Events::RegisterListener	(	EventID	id,
		EventCallback	callback,
		EventPriority	priority = EVENT_PRIORITY_NORMAL,
		const char *	file = nullptr,
		int	line = 0
	)

Registers a callback listener for an event.

For internally managed events (id < -1), the event must already have been registered with RegisterEvent(). User-defined event IDs (id >= 0) are created lazily when first referenced.

Parameters

id	EventID to subscribe to.
callback	Listener callback invoked with the active IEvent*.
priority	Dispatch priority; lower values run first.
file	Optional source file of the registration site.
line	Optional source line of the registration site.

Returns

ListenerID scoped to the target event.

RemoveEvent()

void Ship::Events::RemoveEvent

(

EventID

id

)

Removes an event and all listeners currently registered to it.

Parameters

id	EventID to remove.

UnregisterListener()

void Ship::Events::UnregisterListener	(	EventID	id,
		ListenerID	listenerId
	)

Removes a previously registered listener from an event.

Removing a listener also removes its backing ListenerAction from the Events action list.

Parameters

id	EventID the listener belongs to.
listenerId	ListenerID returned by RegisterListener().

---

The documentation for this class was generated from the following file:

• include/ship/events/Events.h