Athena::EventDispatcher::EventDispatcherInterface

An event dispatcher is the primary type of Athena::EventDispatcher. Extends ACTR::EventDispatcher::Interface to add additional functionality. It maintains a registry of listeners, with events also being dispatched via this type. When dispatched, the dispatcher notifies all listeners registered with that event.

Usage

Listeners can be added in a few ways, with the simplest being registering a block directly on the dispatcher instance.

class MyEvent < ACTR::EventDispatcher::Event; end

dispatcher.listener MyEvent do |event, dispatcher|
  # Do something with the event, and/or dispatcher
end

Another way involves passing an AED::Callable instance, created manually or via the AED::Event.callable method. Lastly, a type that has one or more AEDA::AsEventListener annotated methods may also be passed.

Once all listeners are registered, you can begin to dispatch events. Dispatching an event is simply calling the #dispatch method with an ACTR::EventDispatcher::Event subclass instance as an argument.

Listener Priority

As you may have noticed, each way of registering a listener has an optional priority parameter. This value can be a positive or negative integer, with a default of 0 that controls the order in which each listener is executed. The higher the value, the sooner that listener would be executed. If two listeners have the same priority, they are executed in the order in which they were registered with the dispatcher.

class MyEvent < ACTR::EventDispatcher::Event; end

dispatcher = AED::EventDispatcher.new
dispatcher.listener(MyEvent, priority: -10) { pp "callback1" }
dispatcher.listener(MyEvent, priority: 10) { pp "callback2" }
dispatcher.listener(MyEvent) { pp "callback3" }
dispatcher.listener(MyEvent, priority: 20) { pp "callback4" }
dispatcher.listener(MyEvent) { pp "callback5" }

dispatcher.dispatch MyEvent.new
# =>
#   "callback4"
#   "callback2"
#   "callback3"
#   "callback5"
#   "callback1"

NOTE: While the priority can be any Int32, best practices suggest keeping it in the -255..255 range.