IEventDispatcher#

Fully qualified name: carb::eventdispatcher::IEventDispatcher

Defined in carb/eventdispatcher/IEventDispatcher.h

struct IEventDispatcher#

Interface for carb.eventdispatcher.plugin.

Public Functions

template<class Invocable, class ...Args> ObserverGuard observeEvent( RStringKey observerName, Order order, RString eventName, Invocable &&invocable, Args&&... filterArgs, )#

Registers an observer with the Event Dispatcher system.

An observer is an invocable object (function, functor, lambda, etc.) that is called whenever dispatchEvent() is called. The observers are invoked in the thread that calls dispatchEvent(), and multiple threads could be calling dispatchEvent() simultaneously, so observers must be thread-safe unless the application can ensure synchronization around dispatchEvent() calls.

The invocable callback will always see the eventName that matches the eventName that observeEvent was called with, even if the event was dispatched as an alias. The same invocable callback can observe multiple events; different calls may be differentiated with the Event::eventName property.

Observers can pass zero or any number of filterArgs parameters. These filterArgs cause an observer to only be invoked for a dispatchEvent() call that contains at least the same values. For instance, having a filter pair for key “WindowID” with a specific value will only cause the observer to be called if dispatchEvent() is given the same value as a “WindowID” parameter.

Observers can be added inside of an observer notification (i.e. during a call to dispatchEvent()), however these new observers will not be called for the currently dispatching event. A subsequent recursive call to dispatchEvent() will also call the new observer. The new observer will be available to all other threads potentially before observeEvent() returns. WARNING: this means that the return value may not be available before the observer’s invocable is called. If this is an issue, it is recommended to acquire a mutex before the call to observeEvent() and release it after the ObserverGuard is returned. Any access to the ObserverGuard should acquire the same mutex.

Thread Safety: Safe to perform while any thread is performing any operation against IEventDispatcher. NOTE: the invocable callback can be invoked simultaneously by multiple threads if the event is dispatched simultaneously from multiple threads.

Parameters:

observerName – A name for this observer, used in profiling and debugging.
order – A value determining call order. Observers with lower order values are called earlier. Observers with the same order value will be called in the order they are registered, regardless of filter arguments.
eventName – The name of the event to observe.
invocable – An object that is invoked when an event matching the eventName and filterArgs is dispatched. The object must be callable as void(const Event&).
filterArgs – Zero or more arguments that filter observer invocations. Each argument must be of type std::pair<RStringKey, T> where the first parameter is the key and the second is the value. The value must be of a type understood by a variant::Translator specialization.

Returns:

An ObserverGuard representing the lifetime of the observer. When the ObserverGuard is reset or destroyed, the observer is unregistered as with stopObserving().

template<class Invocable, class InIter> ObserverGuard observeEventIter( RStringKey observerName, Order order, RString eventName, Invocable &&invocable, InIter begin, InIter end, )#

Registers an observer with the Event Dispatcher system.

An observer is an invocable object (function, functor, lambda, etc.) that is called whenever dispatchEvent() is called. The observers are invoked in the thread that calls dispatchEvent(), and multiple threads could be calling dispatchEvent() simultaneously, so observers must be thread-safe unless the application can ensure synchronization around dispatchEvent() calls.

The invocable callback will always see the eventName that matches the eventName that observeEventIter was called with, even if the event was dispatched as an alias. The same invocable callback can observe multiple events; different calls may be differentiated with the Event::eventName property.

Observers can pass zero or any number of filterArgs parameters. These filterArgs cause an observer to only be invoked for a dispatchEvent() call that contains at least the same values. For instance, having a filter pair for key “WindowID” with a specific value will only cause the observer to be called if dispatchEvent() is given the same value as a “WindowID” parameter.

Observers can be added inside of an observer notification (i.e. during a call to dispatchEvent()), however these new observers will not be called for the currently dispatching event. A subsequent recursive call to dispatchEvent() will also call the new observer. The new observer will be available to all other threads potentially before observeEventIter() returns. WARNING: this means that the return value may not be available before the observer’s invocable is called. If this is an issue, it is recommended to acquire a mutex before the call to observeEventIter() and release it after the ObserverGuard is returned. Any access to the ObserverGuard should acquire the same mutex.

Thread Safety: Safe to perform while any thread is performing any operation against IEventDispatcher. NOTE: the invocable callback can be invoked simultaneously by multiple threads if the event is dispatched simultaneously from multiple threads.

Parameters:

observerName – A name for this observer, used in profiling and debugging.
order – A value determining call order. Observers with lower order values are called earlier. Observers with the same order value will be called in the order they are registered, regardless of filter arguments.
eventName – The name of the event to observe.
invocable – An object that is invoked when an event matching the eventName and filterArgs is dispatched. The object must be callable as void(const Event&).
begin – An InputIterator representing the start of the filter parameters.
end – A past-the-end InputIterator representing the end of the filter parameters.

Template Parameters:

InIter – An InputIterator that is forward-iterable and resolves to a NamedVariant when dereferenced.

Returns:

An ObserverGuard representing the lifetime of the observer. When the ObserverGuard is reset or destroyed, the observer is unregistered as with stopObserving().

template<class R, class Invocable> inline ObserverGuard observeEventRange( RStringKey observerName, Order order, RString eventName, Invocable &&invocable, R &&range, )#

Registers an observer with the Event Dispatcher system.

An observer is an invocable object (function, functor, lambda, etc.) that is called whenever dispatchEvent() is called. The observers are invoked in the thread that calls dispatchEvent(), and multiple threads could be calling dispatchEvent() simultaneously, so observers must be thread-safe unless the application can ensure synchronization around dispatchEvent() calls.

The invocable callback will always see the eventName that matches the eventName that observeEventRange was called with, even if the event was dispatched as an alias. The same invocable callback can observe multiple events; different calls may be differentiated with the Event::eventName property.

Observers can pass zero or any number of filterArgs parameters. These filterArgs cause an observer to only be invoked for a dispatchEvent() call that contains at least the same values. For instance, having a filter pair for key “WindowID” with a specific value will only cause the observer to be called if dispatchEvent() is given the same value as a “WindowID” parameter.

Observers can be added inside of an observer notification (i.e. during a call to dispatchEvent()), however these new observers will not be called for the currently dispatching event. A subsequent recursive call to dispatchEvent() will also call the new observer. The new observer will be available to all other threads potentially before observeEventRange() returns. WARNING: this means that the return value may not be available before the observer’s invocable is called. If this is an issue, it is recommended to acquire a mutex before the call to observeEventRange() and release it after the ObserverGuard is returned. Any access to the ObserverGuard should acquire the same mutex.

Thread Safety: Safe to perform while any thread is performing any operation against IEventDispatcher. NOTE: the invocable callback can be invoked simultaneously by multiple threads if the event is dispatched simultaneously from multiple threads.

Parameters:

observerName – A name for this observer, used in profiling and debugging.
order – A value determining call order. Observers with lower order values are called earlier. Observers with the same order value will be called in the order they are registered, regardless of filter arguments.
eventName – The name of the event to observe.
invocable – An object that is invoked when an event matching the eventName and filterArgs is dispatched. The object must be callable as void(const Event&).
range – The range to use as message parameters. See explanation of the R type above.

Template Parameters:

R – A range type. Since this implementation is for pre-C++20 and C++20 ranges are not available, this is an approximation: this type must work with std::begin() and std::end() to produce an iterator type that conforms to InputIterator. The iterator must resolve to a std::pair<RStringKey, T> when dereferenced, where the first parameter is the key and the second parameter is the value and must be a type understood by a variant::Translator specialization. Each key must be unique, otherwise it is not defined which non-unique value is obtained when the key is queried.

Returns:

An ObserverGuard representing the lifetime of the observer. When the ObserverGuard is reset or destroyed, the observer is unregistered as with stopObserving().

template<class ...Args> bool hasObservers( RString eventName, Args&&... filterArgs, )#

Queries the Event Dispatcher whether any observers are listening to a specific event signature.

Emulates a call to dispatchEvent() (without actually calling any observers) and returns true if any observers would be called.

Thread Safety: Safe to perform while any thread is performing any operation against IEventDispatcher.

Parameters:

eventName – The name of the event to query.
filterArgs – Zero or more key/value pairs that would be used for observer filtering as in a call to dispatchEvent(). Each argument must be of type std::pair<RStringKey, T> where the first parameter is the key and the second is the value. The value must be of a type understood by a variant::Translator specialization.

Returns:

true if at least one observer would be called if the same arguments were passed to dispatchEvent(); false otherwise.

template<class InIter> bool hasObserversIter( RString eventName, InIter begin, InIter end, )#

Queries the Event Dispatcher whether any observers are listening to a specific event signature.

Emulates a call to dispatchEvent() (without actually calling any observers) and returns true if any observers would be called.

Thread Safety: Safe to perform while any thread is performing any operation against IEventDispatcher.

Template Parameters:

InIter – An InputIterator that is forward-iterable and resolves to a NamedVariant when dereferenced. The entries are used for observer filtering.

Parameters:

eventName – The name of the event to query.
begin – An InputIterator representing the start of the event key/value pairs.
end – A past-the-end InputIterator representing the end of the event key/value pairs.

Returns:

true if at least one observer would be called if the same arguments were passed to dispatchEvent(); false otherwise.

template<class R> inline bool hasObserversRange( RString eventName, R &&range, )#

Queries the Event Dispatcher whether any observers are listening to a specific event signature.

Emulates a call to dispatchEvent() (without actually calling any observers) and returns true if any observers would be called.

Thread Safety: Safe to perform while any thread is performing any operation against IEventDispatcher.

Template Parameters:

R – A range type. Since this implementation is for pre-C++20 and C++20 ranges are not available, this is an approximation: this type must work with std::begin() and std::end() to produce an iterator type that conforms to InputIterator. The iterator must resolve to a std::pair<RStringKey, T> when dereferenced, where the first parameter is the key and the second parameter is the value and must be a type understood by a variant::Translator specialization. Each key must be unique, otherwise it is not defined which non-unique value is obtained when the key is queried.

Parameters:

eventName – The name of the event to query.
range – The range to use as observer parameters. See explanation of the R type above.

Returns:

true if at least one observer would be called if the same arguments were passed to dispatchEvent(); false otherwise.

size_t dispatchEvent( const Event &event, RString *newEventName = nullptr, )#

Re-dispatch an Event potentially as a different eventName.

This can also be combined with a IMessageQueue to dispatch queued events.

Thread Safety: Safe to perform while any thread is performing any operation against IEventDispatcher.

Warning

While it is safe to recursively dispatch events, this call can lead to endless recursion if the event name is unchanged.

Parameters:

event – The event to re-dispatch.
newEventName – The event name to override Event::eventName from event. Only used if not nullptr.

Returns:

The count of observers that were called. Recursive dispatch calls are not included.

template<class ...Args> size_t dispatchEvent( RString eventName, Args&&... payload, )#

Dispatches an event and immediately calls all observers that would observe this particular event.

Finds and calls all observers (in the current thread) that observe the given event signature.

It is safe to recursively dispatch events (i.e. call dispatchEvent() from a called observer), but care must be taken to avoid endless recursion. See the rules in observeEvent() for observers added during a dispatchEvent() call.

Thread Safety: Safe to perform while any thread is performing any operation against IEventDispatcher.

Parameters:

eventName – The name of the event to dispatch.
payload – Zero or more key/value pairs that are used as the event payload and may be queried by observers or used to filter observers. Each argument must be of type std::pair<RStringKey, T> where the first parameter is the key and the second is the value. The value must be of a type understood by a variant::Translator specialization.

Returns:

The count of observers that were called. Recursive dispatch calls are not included.

template<class InIter> size_t dispatchEventIter( RString eventName, InIter begin, InIter end, )#

Dispatches an event and immediately calls all observers that would observe this particular event.

Finds and calls all observers (in the current thread) that observe the given event signature.

It is safe to recursively dispatch events (i.e. call dispatchEvent() from a called observer), but care must be taken to avoid endless recursion. See the rules in observeEvent() for observers added during a dispatchEvent() call.

Thread Safety: Safe to perform while any thread is performing any operation against IEventDispatcher.

Template Parameters:

InIter – An InputIterator that is forward-iterable and resolves to a NamedVariant when dereferenced. The entries are used as the event payload and may be queried by observers or used to filter observers.

Parameters:

eventName – The name of the event to dispatch.
begin – An InputIterator representing the start of the event key/value pairs.
end – A past-the-end InputIterator representing the end of the event key/value pairs.

Returns:

The count of observers that were called. Recursive dispatch calls are not included.

template<class R> inline size_t dispatchEventRange( RString eventName, R &&range, )#

Dispatches an event and immediately calls all observers that would observe this particular event.

Finds and calls all observers (in the current thread) that observe the given event signature.

It is safe to recursively dispatch events (i.e. call dispatchEvent() from a called observer), but care must be taken to avoid endless recursion. See the rules in observeEvent() for observers added during a dispatchEvent() call.

Thread Safety: Safe to perform while any thread is performing any operation against IEventDispatcher.

Template Parameters:

R – A range type. Since this implementation is for pre-C++20 and C++20 ranges are not available, this is an approximation: this type must work with std::begin() and std::end() to produce an iterator type that conforms to InputIterator. The iterator must resolve to a std::pair<RStringKey, T> when dereferenced, where the first parameter is the key and the second parameter is the value and must be a type understood by a variant::Translator specialization. Each key must be unique, otherwise it is not defined which non-unique value is obtained when the key is queried.

Parameters:

eventName – The name of the event to dispatch.
range – The range to use for key/value pairs. See explanation of the R type above.

Returns:

The count of observers that were called. Recursive dispatch calls are not included.

Public Members

bool (*stopObserving)(Observer ob)#

Stops the given observer.

Safe to perform while dispatching.

Since observers can be in use by this thread or any thread, this function is carefully synchronized with all other IEventDispatcher operations.

During stopObserving(), further calls to the observer are prevented, even if other threads are currently dispatching an event that would be observed by the observer in question.
If any other thread is currently calling the observer in question, stopObserving() will wait until all other threads have left the observer function.
If the observer function is not in the callstack of the current thread, the cleanup function provided to internalObserveEvent() is called and any variant::Variant objects captured to filter events are destroyed.
If the observer function is in the callstack of the current thread, stopObserving() will return without waiting, without calling the cleanup function and without destroying variant::Variant objects. Instead, this cleanup will be performed when the dispatchEvent() call in the current thread finishes.

Except when the observer function is in the callstack of the current thread, the following guarantee is made: when stopObserving() returns, the observer function will no longer be called, all calls to it have completed, and the Invocable and any filter arguments passed to observeEvent() (or similar) have been destroyed.