Skip to content

Latest commit

 

History

History
154 lines (122 loc) · 6.21 KB

hetereventdispatcher.md

File metadata and controls

154 lines (122 loc) · 6.21 KB
Raw

Class HeterEventDispatcher reference

Table Of Contents

Description

HeterEventDispatcher is something like std::map<EventType, HeterCallbackList>.

HeterEventDispatcher holds a map of <EventType, HeterCallbackList> pairs. On dispatching, HeterEventDispatcher finds the HeterCallbackList of the event type, then invoke the callback list. The invocation is always synchronous. The listeners are triggered when HeterEventDispatcher::dispatch is called.

API reference

Header

eventpp/hetereventdispatcher.h

Template parameters

template <
    typename Event,
    typename PrototypeList,
    typename Policies = DefaultPolicies
>
class HeterEventDispatcher;

Event: the event type. The type used to identify the event. Events with same type are the same event. The event type must be able to be used as the key in std::map or std::unordered_map, so it must be either comparable with operator < or has specialization of std::hash.
Prototype: a list of function types in eventpp::HeterTuple, such as eventpp::HeterTuple<void (), void (std::string), void (int, int)>.
Policies: the policies to configure and extend the dispatcher. The default value is DefaultPolicies. See document of policies for details.

Public types

Handle: the handle type returned by appendListener, prependListener and insertListener. A handle can be used to insert a listener or remove a listener. To check if a Handle is empty, convert it to boolean, false is empty. Handle is copyable.
Event: the event type.

Member functions

constructors

HeterEventDispatcher();
HeterEventDispatcher(const HeterEventDispatcher & other);
HeterEventDispatcher(HeterEventDispatcher && other) noexcept;
HeterEventDispatcher & operator = (const HeterEventDispatcher & other);
HeterEventDispatcher & operator = (HeterEventDispatcher && other) noexcept;

HeterEventDispatcher can be copied, moved, assigned, and move assigned.

appendListener

template <typename C>
Handle appendListener(const Event & event, const C & callback);

Add the callback to the dispatcher to listen to event.
The listener is added to the end of the listener list.
The callback type C must be specified in PrototypeList.
Return a handle which represents the listener. The handle can be used to remove this listener or insert other listener before this listener.
If appendListener is called in another listener during a dispatching, the new listener is guaranteed not triggered during the same dispatching.
If the same callback is added twice, it results duplicated listeners.
The time complexity is O(1).

prependListener

template <typename C>
Handle prependListener(const Event & event, const C & callback);

Add the callback to the dispatcher to listen to event.
The listener is added to the beginning of the listener list.
The callback type C must be specified in PrototypeList.
Return a handle which represents the listener. The handle can be used to remove this listener or insert other listener before this listener.
If prependListener is called in another listener during a dispatching, the new listener is guaranteed not triggered during the same dispatching.
The time complexity is O(1).

insertListener

template <typename C>
Handle insertListener(const Event & event, const C & callback, const Handle & before);

Insert the callback to the dispatcher to listen to event before the listener handle before. If before is not found, callback is added at the end of the listener list.
The callback type C must be specified in PrototypeList.
Return a handle which represents the listener. The handle can be used to remove this listener or insert other listener before this listener.
If insertListener is called in another listener during a dispatching, the new listener is guaranteed not triggered during the same dispatching.
The time complexity is O(1).

removeListener

bool removeListener(const Event & event, const Handle handle);

Remove the listener handle which listens to event from the dispatcher.
Return true if the listener is removed successfully, false if the listener is not found.
The time complexity is O(1).

hasAnyListener

bool hasAnyListener(const Event & event) const;

Return true if there is any listener for event, false if there is no listener.
Note: in multi threading, this function returning true doesn't guarantee there is any listener. The list may immediately become empty after the function returns true, and vice versa. The time complexity is O(1) plus time to look up the event in internal map.

forEach

template <typename Prototype, typename Func>
void forEach(const Event & event, Func && func) const;

Apply func to all callbacks which has the Prototype.
The func can be one of the two prototypes:

AnyReturnType func(const HeterEventDispatcher::Handle & handle, const std::function<Prototype> & callback);
AnyReturnType func(const std::function<Prototype> & callback);

Note: the func can remove any listeners, or add other listeners, safely.

forEachIf

template <typename Prototype, typename Func>
bool forEachIf(const Event & event, Func && func) const;

Apply func to all listeners of event. func must return a boolean value, and if the return value is false, forEachIf stops the looping immediately.
Return true if all listeners are invoked, or event is not found, false if func returns false.

dispatch

template <typename T, typename ...Args>
void dispatch(T && first, Args && ...args) const

Dispatch an event. The event type is deducted from the arguments of dispatch.
Invoke each callbacks that can be called with Args in the callback list.
The listeners are called with arguments args.
The function is synchronous. The listeners are called in the thread same as the caller of dispatch.