Suggested Rewrite for Event Dispatcher Section

[MrDrElliot]

Hello,

https://github.com/skypjack/entt/wiki/Events,-signals-and-everything-in-between#event-dispatcher
The documentation states that listeners must be types "that offer one or more member functions," which is misleading since the dispatcher actually accepts both free functions and member functions.

They also accept lambdas under certain conditions,so it might also be beneficial to add some examples of those as well.

Proposed Revision:

---

Event dispatcher

The event dispatcher class allows users to trigger immediate events or to queue and publish them all together later.

This class lazily instantiates its queues. Therefore, it is not necessary to announce the event types in advance:

// define a general purpose dispatcher
entt::dispatcher dispatcher{};

Connecting Listeners

Listeners can be connected to a dispatcher in two ways:

1. Free functions - Functions that accept an event reference as their parameter
2. Member functions - Methods of class instances that accept an event reference

These listeners are connected via the connect member function on a sink:

struct an_event { int value; };
struct another_event {};

// Free function listener
void on_event(const an_event &event) { /* ... */ }

// Class-based listener
struct listener {
    void receive(const an_event &) { /* ... */ }
    void method(const another_event &) { /* ... */ }
};

// Connecting free functions
dispatcher.sink<an_event>().connect<&on_event>();

// Connecting lambdas
dispatcher.sink<an_event>().connect<[](an_event& e) {}>();

// Connecting member functions
listener instance;
dispatcher.sink<an_event>().connect<&listener::receive>(instance);
dispatcher.sink<another_event>().connect<&listener::method>(instance);

Listeners must be callable with an argument of type Event & (or const Event &) for the specific event type, regardless of the return value.

Note: Connecting listeners within event handlers can result in undefined behavior.

Disconnecting Listeners

The disconnect member function is used to remove one listener at a time or all of them at once:

// Disconnect a specific free function
dispatcher.sink<an_event>().disconnect<&on_event>();

// Disconnect a specific member function
dispatcher.sink<an_event>().disconnect<&listener::receive>(instance);

// Disconnecting lambdas
dispatcher.sink<an_event>().disconnect<[](an_event& e) {}>();

// Disconnect all listeners from a specific instance
dispatcher.sink<another_event>().disconnect(&instance);

[MrDrElliot]

I'd actually be curious about disconnecting lambdas as well, that might be a bit of an odd issue.

[linkdd]

If we're updating the doc regarding listeners, I'd add a section about method overloading:

struct listener {
  void on_message(const event_foo&);
  void on_message(const event_bar&);
};

entt::dispatcher dispatcher;
listener l;

using listener_foo_type = void (listener::*)(const event_foo&);
constexpr auto listener_foo = static_cast<listener_foo_type>(&listener::on_message);
dispatcher.sink<event_foo>().connect<listener_foo>(&l);

using listener_bar_type = void (listener::*)(const event_bar&);
constexpr auto listener_bar = static_cast<listener_bar_type>(&listener::on_message);
dispatcher.sink<event_bar>().connect<listener_bar>(&l);

Since this is a bit annoying, to facilitate this I usually inherit from entt::dispatcher :

template <typename Listener, typename Message>
concept listener_trait = requires(Listener l, const Message& m) {
  { l.on_message(m) } -> std::same_as<void>;
};


class message_bus : public entt::dispatcher {
  public:
    template <typename Message, listener_trait<Message> Listener>
    auto connect(Listener* listener) -> void {
      using handler_type     = void (Listener::*)(const Message&);
      constexpr auto handler = static_cast<handler_type>(&Listener::on_message);

      sink<Message>().template connect<handler>(listener);
    }


    template <typename Message, listener_trait<Message> Listener>
    auto disconnect(Listener* listener) -> void {
      using handler_type     = void (Listener::*)(const Message&);
      constexpr auto handler = static_cast<handler_type>(&Listener::on_message);

      sink<Message>().template disconnect<handler>(listener);
    }
};

Which is then used like this:

struct listener {
  void on_message(const event_foo&);
  void on_message(const event_bar&);
};

message_bus dispatcher;
listener l;

dispatcher.connect<event_foo>(&l);
dispatcher.connect<event_bar>(&l);