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(int 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.

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() (on the current thread only) will also call the new observer. The new observer will be available to all other threads once the dispatchEvent() call—in which it was added—returns.

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

Parameters

order – A value determining call order. Observers with lower order values are called earlier. Observers with the same order value and same filter argument values will be called in the order they are registered. Observers with the same order value with different filter argument values are called in an indeterminate order.
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(int 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.

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. However, a recursive call to dispatchEvent() (on the current thread only) will also call the new observer. The new observer will be available to all other threads once the dispatchEvent() call—in which it was added—returns.

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

Parameters

order – A value determining call order. Observers with lower order values are called earlier. Observers with the same order value and same filter argument values will be called in the order they are registered. Observers with the same order value with different filter argument values are called in an indeterminate order.
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 ...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 ...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.

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, calling the cleanup function or destroying variant::Variant objects. Instead, this cleanup will be performed when the dispatchEvent() call in the current thread finishes.

When stopObserving() returns, it is guaranteed that the observer function will no longer be called and all calls to it have completed (except if the calling thread is dispatching).

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

Warning

This function must be called exactly once per Observer created by observeEvent(). The ObserverGuard calls this function automatically.

Param ob: The Observer to stop.
Return: true if the Observer was found and stopped; false otherwise.

bool (*isDispatching)(bool currentThread)

Queries to see if the system is currently dispatching an event.

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

Param currentThread: If false, checks to see if any thread is currently dispatching. However, the return value should be used for debugging purposes only as it is a transient value and could be stale by the time it is read by the application. If true, checks to see if the current thread is dispatching (that is, the callstack includes a call to dispatchEvent()).
Return: true if any thread or the current thread is dispatching based on the value of currentThread; false otherwise.

Public Static Functions

static inline constexpr carb::InterfaceDesc getInterfaceDesc() noexcept

Returns information about this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns: The carb::InterfaceDesc struct with information about this interface.

static inline constexpr carb::InterfaceDesc getLatestInterfaceDesc() noexcept

Returns information about the latest version of this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns: The carb::InterfaceDesc struct with information about the latest version of this interface.