Class: Octiron::Events::Bus

Inherits:
Object
  • Object
show all
Includes:
Support::Identifiers
Defined in:
lib/octiron/events/bus.rb

Overview

Implements and in-process pub-sub events broadcaster allowing multiple observers to subscribe to different events.

Constant Summary collapse

DEFAULT_CLASS =

The default handler class

'octiron-default'.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Support::Identifiers

#identify

Methods included from Support::Constantize

#constantize

Methods included from Support::CamelCase

#camel_case

Constructor Details

#initialize(default_namespace = ::Octiron::Events) ⇒ Bus

Returns a new instance of Bus.

Parameters:

  • default_namespace (Symbol) (defaults to: ::Octiron::Events) —

    The default namespace to look in for Event classes.



30
31
32
33
 
# File 'lib/octiron/events/bus.rb', line 30

def initialize(default_namespace = ::Octiron::Events)
  @default_namespace = default_namespace.to_s
  clear
end

Instance Attribute Details

#default_namespace ⇒ String (readonly)

Returns the default namespace to search for events.

Returns:

  • (String) —

    the default namespace to search for events



22
23
24
 
# File 'lib/octiron/events/bus.rb', line 22

def default_namespace
  @default_namespace
end

Instance Method Details

#clear ⇒ Object

Clears all event handlers



37
38
39
 
# File 'lib/octiron/events/bus.rb', line 37

def clear
  @handlers = {}
end

#publish(event) ⇒ Object Also known as: broadcast, notify

Broadcast an event. This is an instance of a class provided to #subscribe previously.

Parameters:

  • event (Object) —

    the event to publish



90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/octiron/events/bus.rb', line 90

def publish(event)
  event_name = event
  if not event.is_a?(Hash)
    event_name = event.class.to_s
  end
  @handlers.keys.sort.each do |handler_class|
    handlers_for(event_name, handler_class, false).each do |handler|
      handler.call(event)
    end
  end
end

#subscribe(event_id, handler_object = nil, handler_class = DEFAULT_CLASS, &handler_proc) ⇒ Object Also known as: register

Subscribe an event handler to an event.

Parameters:

  • event_id (Class, String, other) —

    A class or String naming an event class.

  • handler_object (Object) (defaults to: nil) —

    Handler object that must implement a ‘#call` method accepting an instance of the event class provided in the first parameter. If nil, a block needs to be provided.

  • handler_class (Object) (defaults to: DEFAULT_CLASS) —

    An object describing the handler class; the default is DEFAULT_CLASS. Handlers are executed sorted by handler class, so the class provided here must be sortable.

  • handler_proc (Proc) —

    Handler block that accepts an instance of the event class provided in the first parameter. If nil, a handler object must be provided.

Returns:

  • The class represented by the event_id, as a String name.



55
56
57
58
59
60
61
 
# File 'lib/octiron/events/bus.rb', line 55

def subscribe(event_id, handler_object = nil, handler_class = DEFAULT_CLASS,
              &handler_proc)
  return with_handlers(event_id, handler_class, handler_object,
                       handler_proc) do |hlist, h|
           hlist << h
         end
end

#unsubscribe(event_id, handler_object = nil, handler_class = DEFAULT_CLASS, &handler_proc) ⇒ Object

Unsubscribe an event handler from an event.

Parameters:

  • event_id (Class, String, other) —

    A class or String naming an event class.

  • handler_object (Object) (defaults to: nil) —

    Handler object that must implement a ‘#call` method accepting an instance of the event class provided in the first parameter. If nil, a block needs to be provided.

  • handler_class (Object) (defaults to: DEFAULT_CLASS) —

    An object describing the handler class; the default is DEFAULT_CLASS. Handlers are executed sorted by handler class, so the class provided here must be sortable.

  • handler_proc (Proc) —

    Handler block that accepts an instance of the event class provided in the first parameter. If nil, a handler object must be provided.

Returns:

  • The class represented by the event_id, as a String name.



78
79
80
81
82
83
84
 
# File 'lib/octiron/events/bus.rb', line 78

def unsubscribe(event_id, handler_object = nil, handler_class = DEFAULT_CLASS,
                &handler_proc)
  return with_handlers(event_id, handler_class, handler_object,
                       handler_proc) do |hlist, h|
           hlist.delete(h)
         end
end