eventpp

Overview

CallbackList is the fundamental building block of eventpp. It is a container that holds a list of callbacks (functions, lambdas, member function pointers, etc.) and invokes them sequentially when requested.

Key Characteristics

• Callback Targets: Supports functions, function pointers, member function pointers, lambda expressions, and function objects.
• Invocation: When the list is invoked, it calls each callback one by one in the same thread as the caller.
• Nested Safety: If a callback adds or removes other callbacks during an invocation, eventpp ensures that the newly added or removed callbacks are not triggered within that same invocation cycle (preventing infinite loops or iterator invalidation).
• Thread Safety Note: While nested safety is guaranteed in a single-threaded context, it is not guaranteed in multi-threaded environments. If one thread invokes the list while another adds/removes callbacks, the behavior is undefined/unpredictable.

HeterCallbackList

HeterCallbackList is a heterogeneous callback list that allows you to store multiple callbacks with different function signatures (prototypes) in a single container. It is the foundation for HeterEventDispatcher and HeterEventQueue.

When you invoke the list using operator(), it automatically identifies and executes every callback whose signature matches the provided arguments.

Key Characteristics:

• Heterogeneous Prototypes: Unlike a standard CallbackList, you can mix different function types (e.g., void(int) and void(std::string)) in one list.
• Flexible Targets: Supports functions, function pointers, member function pointers, lambda expressions, and function objects.
• Safe Modification: If you append, prepend, or insert a new callback while the list is currently being invoked (inside a callback), the new callback is guaranteed not to be triggered during that same invocation cycle.
• Complexity: append, prepend, insert, and remove all operate with $O(1)$ time complexity.

Overview

AnyData is a high-performance data structure designed to hold various data types without dynamic heap allocation (unlike std::shared_ptr). It is intended for extreme performance optimization scenarios, such as the core event system of a game engine, where reducing heap allocation overhead is critical.

Key Characteristics

• Performance: Can improve performance by 30%~50% compared to std::shared_ptr by avoiding heap allocations.
• Memory Usage: It uses at least maxSize bytes (the template parameter) even for smaller types. It may use slightly more memory than a shared pointer solution due to this fixed buffer, but it avoids the overhead of control blocks.
• Type Safety: AnyData is not type-safe. Misusing it (e.g., casting to the wrong type) can lead to program crashes.
• Intended Use: It should only be used within an EventQueue. It is not a general-purpose container.

How it works

AnyData takes a maxSize template parameter. If the data being stored is smaller than or equal to maxSize, it is stored internally. If the data is larger, it falls back to dynamic heap allocation.

The Threading policy controls how data is protected in multi-threaded environments.

Available Options:

• eventpp::MultipleThreading (Default): Protects core data with a mutex (defaults to std::mutex).
• eventpp::SingleThreading: No protection; data cannot be accessed from multiple threads.

Customizing Threading: You can use eventpp::GeneralThreading to provide a custom mutex, atomic type, or condition variable.

Using SpinLock for performance: When the number of threads is close to the number of CPU cores, eventpp::SpinLock may perform better than std::mutex. Use eventpp::GeneralThreading<eventpp::SpinLock> to implement this.

// Using SpinLock via GeneralThreading shortcut
struct MyEventPolicies {
    using Threading = eventpp::GeneralThreading<eventpp::SpinLock>;
};
eventpp::EventDispatcher<int, void (), MyEventPolicies> dispatcher;
eventpp::CallbackList<void (), MyEventPolicies> callbackList;

An EventDispatcher acts like a map of <EventType, CallbackList> pairs. It is ideal for systems with many or dynamic event types (like GUI or game engines) because you can distinguish events by a type rather than creating separate CallbackList instances for every single event.

Key Characteristics:

• Synchronous: Listeners are triggered immediately when EventDispatcher::dispatch is called.
• Uniform Prototype: All events handled by a single dispatcher must share the same callback signature. To handle different data types, use a base event class and have all specific events derive from it.
• Policy-based: Requires a policy class to map an event object to its type.

enum class MyEventType
{
    redraw,
    mouseDown,
    mouseUp,
    //... maybe 200 other events here
};

struct MyEvent {
    MyEventType type;
    // data that all events may need
};

struct MyEventPolicies
{
    static MyEventType getEvent(const MyEvent & e) {
        return e.type;
    }
};

eventpp::EventDispatcher<MyEventType, void(const MyEvent &), MyEventPolicies> dispatcher;
dispatcher.dispatch(MyEvent { MyEventType::redraw });