brainguy 0.0.1

data/lib/brainguy/single_event_subscription.rb

@@ -0,0 +1,31 @@
+require "brainguy/subscription"
+
+module Brainguy
+  # A subscription to a single type (name) of event. The `listener` will only
+  # be notified if the event name matches `subscribed_event_name`.
+  #
+  # See {Emitter#on} for where this class is used.
+  class SingleEventSubscription < Subscription
+    # @param owner [Emitter] the owning {Emitter}
+    # @param listener [:call] some callable that should be called when the
+    #   named event occurs
+    # @param subscribed_event_name [Symbol] the event to subscribe to
+    def initialize(owner, listener, subscribed_event_name)
+      @subscribed_event_name = subscribed_event_name
+      super(owner, listener)
+    end
+
+    # Call listener if the event name is the one being subscribed to.
+    # @param event [Event] the event to (maybe) dispatch
+    def handle(event)
+      return unless event.name == @subscribed_event_name
+      @listener.call(*event.args)
+    end
+
+    protected
+
+    def equality_components
+      super + [@subscribed_event_name]
+    end
+  end
+end

data/lib/brainguy/subscription.rb

@@ -0,0 +1,59 @@
+module Brainguy
+  # A value object that represents a single subscription to an event source.
+  #
+  # It ties together an event `source` to a `listener`. A listener is simply
+  # some call-able object.
+  class Subscription
+    include Comparable
+
+    # @!attribute [r] owner
+    #   @return [Emitter] the owning {Emitter}
+    # @!attribute [r] listener
+    #   @return [:call] a callable listener object
+    attr_reader :owner, :listener
+
+    # @param owner [Emitter] the owning {Emitter}
+    # @param listener [:call] a callable listener object
+    def initialize(owner, listener)
+      @owner    = owner
+      @listener = listener
+      freeze
+    end
+
+    # Dispatch `event` to the listener.
+    # @param event [Event] the event to dispatch
+    # @return whatever the listener returns
+    def handle(event)
+      @listener.call(event)
+    end
+
+    # Cancel the subscription (remove it from the `owner`)
+    def cancel
+      @owner.delete(self)
+    end
+
+    # Compare this to another subscription
+    def <=>(other)
+      return nil unless other.is_a?(Subscription)
+      equality_components <=> other.equality_components
+    end
+
+    # The hash value is based on the identity (but not the state) of `owner`
+    # and `listener`. Two `Subscription` objects with the same `owner` and
+    # `listener` are considered to be equivalent.
+    def hash
+      [self.class, *equality_components].hash
+    end
+
+    # @!method eql?(other)
+    # @param other [Subscription] the other subscription to compare to
+    # @return [Boolean]
+    alias_method :eql?, :==
+
+    protected
+
+    def equality_components
+      [owner.object_id, listener.object_id]
+    end
+  end
+end

data/lib/brainguy/subscription_scope.rb

@@ -0,0 +1,62 @@
+require "brainguy/emitter"
+require "delegate"
+
+module Brainguy
+  # A scope for subscriptions with a limited lifetime.
+  #
+  # Sometimes it's useful to have a set of subscriptions with a limited
+  # lifetime. For instance, a set of observers which are only valid over the
+  # course of a single method call. This class wraps an existing
+  # {Emitter}, and exposes the same API. But when a client sends the
+  # `#close` message, all listeners subscribed through this object will be
+  # immediately unsubscribed.
+  class SubscriptionScope < DelegateClass(Emitter)
+
+    # Create a new scope and yield it to the block. Closes the scope
+    # (unsubscribing any listeners attached using the scope) at the end of
+    # block execution
+    # @param (see #initialize)
+    # @yield [SubscriptionScope] the subscription scope
+    def self.open(subscription_set)
+      scope = self.new(subscription_set)
+      yield scope
+    ensure
+      scope.close
+    end
+
+    # @param subscription_set [Emitter] the subscription set to wrap
+    def initialize(subscription_set)
+      super(subscription_set)
+      @subscriptions = []
+    end
+
+    # (see Emitter#on)
+    def on(*)
+      super.tap do |subscription|
+        @subscriptions << subscription
+      end
+    end
+
+    # (see Emitter#attach)
+    def attach(*)
+      super.tap do |subscription|
+        @subscriptions << subscription
+      end
+    end
+
+    # Detach every listener that was attached via this scope.
+    # @return [void]
+    def close
+      @subscriptions.each(&:cancel)
+      @subscriptions.clear
+    end
+  end
+
+  class Emitter
+    # @yield [SubscriptionScope] a temporary subscription scope layered on top
+    #   of this {Emitter}
+    def with_subscription_scope(&block)
+      SubscriptionScope.open(self, &block)
+    end
+  end
+end

data/lib/brainguy/version.rb

@@ -0,0 +1,4 @@
+module Brainguy
+  # The library version
+  VERSION = "0.0.1"
+end

data/scripts/benchmark_listener_dispatch.rb

@@ -0,0 +1,222 @@
+require "benchmark/ips"
+
+Event = Struct.new(:name, :source, :args)
+
+class TestBed
+  attr_reader :event_log
+
+  def initialize
+    @event_log = []
+  end
+end
+
+class HardcodeTestbed < TestBed
+  def call(event)
+    case event.name
+    when :foo
+      handle_foo(event)
+    when :bar
+      handle_bar(event)
+    when :baz
+      handle_baz(event)
+    end
+  end
+
+  def handle_foo(event)
+    event_log << event
+  end
+
+  def handle_bar(event)
+    event_log << event
+  end
+
+  def handle_baz(event)
+    event_log << event
+  end
+end
+
+class SendTestbed < TestBed
+  def call(event)
+    handler_name = "handle_#{event.name}"
+    __send__(handler_name, event) if respond_to?(handler_name)
+  end
+
+  def handle_foo(event)
+    event_log << event
+  end
+
+  def handle_bar(event)
+    event_log << event
+  end
+
+  def handle_baz(event)
+    event_log << event
+  end
+end
+
+class SendTableTestbed < TestBed
+  def self.method_added(method_name)
+    if method_name.to_s =~ /\Ahandle_(.+)\z/
+      handler_methods[$1.to_sym] = method_name.to_sym
+    end
+    super
+  end
+
+  def self.handler_methods
+    @handler_methods ||= {}
+  end
+
+  def call(event)
+    if (handler_method = self.class.handler_methods[event.name])
+      __send__(handler_method, event)
+    end
+  end
+
+  def handle_foo(event)
+    event_log << event
+  end
+
+  def handle_bar(event)
+    event_log << event
+  end
+
+  def handle_baz(event)
+    event_log << event
+  end
+end
+
+class BindTableTestbed < TestBed
+  def self.method_added(method_name)
+    if method_name.to_s =~ /\Ahandle_(.+)\z/
+      handler_methods[$1.to_sym] = instance_method(method_name)
+    end
+    super
+  end
+
+  def self.handler_methods
+    @handler_methods ||= {}
+  end
+
+  def call(event)
+    if (handler_method = self.class.handler_methods[event.name])
+      handler_method.bind(self).call(event)
+    end
+  end
+
+  def handle_foo(event)
+    event_log << event
+  end
+
+  def handle_bar(event)
+    event_log << event
+  end
+
+  def handle_baz(event)
+    event_log << event
+  end
+end
+
+class CodeGenTestbed < TestBed
+  def self.method_added(method_name)
+    if method_name.to_s =~ /\Ahandle_(.+)\z/
+      handler_methods << $1
+      regenerate_dispatch_method
+    end
+    super
+  end
+
+  def self.handler_methods
+    @handler_methods ||= []
+  end
+
+  def self.regenerate_dispatch_method
+    dispatch_table = handler_methods.map { |event_name|
+      "when :#{event_name} then handle_#{event_name}(event)"
+    }.join("\n")
+    class_eval %{
+      def call(event)
+        case event.name
+        #{dispatch_table}
+        end
+      end
+    }
+  end
+
+  def handle_foo(event)
+    event_log << event
+  end
+
+  def handle_bar(event)
+    event_log << event
+  end
+
+  def handle_baz(event)
+    event_log << event
+  end
+end
+
+class IfCodeGenTestbed < TestBed
+  def self.method_added(method_name)
+    if method_name.to_s =~ /\Ahandle_(.+)\z/
+      handler_methods << $1
+      regenerate_dispatch_method
+    end
+    super
+  end
+
+  def self.handler_methods
+    @handler_methods ||= []
+  end
+
+  def self.regenerate_dispatch_method
+    dispatch_table = handler_methods.map { |event_name|
+      "event.name.equal?(:#{event_name}) then handle_#{event_name}(event)"
+    }.join("\nelsif ")
+    class_eval %{
+      def call(event)
+        if #{dispatch_table}
+        end
+      end
+    }
+  end
+
+  def handle_foo(event)
+    event_log << event
+  end
+
+  def handle_bar(event)
+    event_log << event
+  end
+
+  def handle_baz(event)
+    event_log << event
+  end
+end
+
+def do_test(klass)
+  testbed = klass.new
+  testbed.call(e1 = Event[:foo])
+  testbed.call(e2 = Event[:bar])
+  testbed.call(e3 = Event[:baz])
+  testbed.call(Event[:buz])
+  unless testbed.event_log == [e1, e2, e3]
+    fail "#{klass}: #{testbed.event_log.inspect}"
+  end
+end
+
+classes = [
+    HardcodeTestbed,
+    SendTestbed,
+    SendTableTestbed,
+    BindTableTestbed,
+    CodeGenTestbed,
+    IfCodeGenTestbed,
+]
+width   = classes.map(&:name).map(&:size).max
+
+Benchmark.ips do |x|
+  classes.each do |klass|
+    x.report(klass.name) { do_test(klass) }
+  end
+  x.compare!
+end

data/spec/brainguy/emitter_spec.rb

@@ -0,0 +1,25 @@
+require "rspec"
+require "brainguy/emitter"
+
+module Brainguy
+  RSpec.describe Emitter do
+    it "uses notifier result for return value of #emit" do
+      notifier = instance_double(BasicNotifier, result: "THE RESULT")
+      ss       = Emitter.new(double("event source"),
+                                     notifier_maker: ->() { notifier })
+      expect(ss.emit(:foo)).to eq("THE RESULT")
+    end
+
+    it "can set up multiple handlers at once with a hash of lambdas" do
+      ss     = Emitter.new(double)
+      probe  = spy("probe")
+      result = ss.on(foo: proc { probe.handle_foo },
+                     bar: proc { probe.handle_bar })
+      expect(result.listener).to be_a(OpenObserver)
+      ss.emit(:foo)
+      ss.emit(:bar)
+      expect(probe).to have_received(:handle_foo)
+      expect(probe).to have_received(:handle_bar)
+    end
+  end
+end

data/spec/brainguy/error_collecting_notifier_spec.rb

@@ -0,0 +1,19 @@
+require "rspec"
+require "brainguy/error_collecting_notifier"
+
+module Brainguy
+  RSpec.describe ErrorCollectingNotifier do
+    it "collects errors into a list" do
+      inner  = instance_spy(BasicNotifier, "inner")
+      outer  = ErrorCollectingNotifier.new(inner)
+      error1 = StandardError.new("Whoopsie")
+      error2 = StandardError.new("O NOES")
+      allow(inner).to receive(:notify).and_raise(error1)
+      outer.notify(sub1 = double("subscription1"), double)
+      allow(inner).to receive(:notify).and_raise(error2)
+      outer.notify(sub2 = double("subscription2"), double)
+      expect(outer.result)
+          .to eq({sub1 => error1, sub2 => error2})
+    end
+  end
+end

data/spec/brainguy/error_handling_notifier_spec.rb

@@ -0,0 +1,63 @@
+require "rspec"
+require "brainguy/error_handling_notifier"
+
+module Brainguy
+  RSpec.describe ErrorHandlingNotifier do
+    it "passes notifications through" do
+      inner = instance_spy(BasicNotifier, "inner")
+      outer = ErrorHandlingNotifier.new(inner)
+      outer.notify(double, double)
+      expect(inner).to have_received(:notify)
+    end
+
+    it "enables exceptions to be handled by an arbitrary callable" do
+      handler = double("handler", :call => nil)
+      inner = instance_spy(BasicNotifier, "inner")
+      outer = ErrorHandlingNotifier.new(inner, handler)
+      error = StandardError.new("Whoopsie")
+      allow(inner).to receive(:notify).and_raise(error)
+      outer.notify(sub = double("subscription"), double)
+      expect(handler).to have_received(:call).with(sub, error)
+    end
+
+    it "re-raises errors if no handler is supplied" do
+      inner = instance_spy(BasicNotifier, "inner")
+      outer = ErrorHandlingNotifier.new(inner)
+      error = StandardError.new("Whoopsie")
+      allow(inner).to receive(:notify).and_raise(error)
+      expect{outer.notify(double, double)}.to raise_error(error)
+    end
+
+    it "provides a mnemonic for the default re-raise behavior" do
+      inner = instance_spy(BasicNotifier, "inner")
+      outer = ErrorHandlingNotifier.new(inner, :raise)
+      error = StandardError.new("Whoopsie")
+      allow(inner).to receive(:notify).and_raise(error)
+      expect{outer.notify(double, double)}.to raise_error(error)
+    end
+
+    it "provides a mnemonic for suppressing errors" do
+      inner = instance_spy(BasicNotifier, "inner")
+      outer = ErrorHandlingNotifier.new(inner, :suppress)
+      error = StandardError.new("Whoopsie")
+      allow(inner).to receive(:notify).and_raise(error)
+      expect{outer.notify(double, double)}.to_not raise_error
+    end
+
+    it "provides a mnemonic for converting errors to warnings" do
+      inner = instance_spy(BasicNotifier, "inner")
+      outer = ErrorHandlingNotifier.new(inner, :warn)
+      error = StandardError.new("Whoopsie")
+      allow(inner).to receive(:notify).and_raise(error)
+      expect{outer.notify(double, double)}
+          .to output(/StandardError: Whoopsie/).to_stderr
+    end
+
+    it "has a result of nil" do
+      inner = instance_spy(BasicNotifier, "inner")
+      outer = ErrorHandlingNotifier.new(inner)
+      outer.notify(double, double)
+      expect(outer.result).to be_nil
+    end
+  end
+end