standard-procedure-plumbing 0.3.3 → 0.4.1

data/lib/plumbing/actor.rb

@@ -0,0 +1,93 @@
+require_relative "actor/kernel"
+require_relative "actor/inline"
+
+module Plumbing
+  module Actor
+    def safely(&)
+      proxy.safely(&)
+      nil
+    end
+
+    def within_actor? = proxy.within_actor?
+
+    def stop = proxy.stop
+
+    def self.included base
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      # Create a new actor instance and build a proxy for it using the current mode
+      # @return [Object] the proxy for the actor instance
+      def start(...)
+        instance = new(...)
+        build_proxy_for(instance).tap do |proxy|
+          instance.send :"proxy=", proxy
+        end
+      end
+
+      # Define the async messages that this actor can respond to
+      # @param names [Array<Symbol>] the names of the async messages
+      def async(*names) = async_messages.concat(names.map(&:to_sym))
+
+      # List the async messages that this actor can respond to
+      def async_messages = @async_messages ||= []
+
+      def inherited subclass
+        subclass.async_messages.concat async_messages
+      end
+
+      private
+
+      def build_proxy_for(target)
+        proxy_class_for(target.class).new(target)
+      end
+
+      def proxy_class_for target_class
+        Plumbing.config.actor_proxy_class_for(target_class) || register_actor_proxy_class_for(target_class)
+      end
+
+      def proxy_base_class = const_get PROXY_BASE_CLASSES[Plumbing.config.mode]
+
+      PROXY_BASE_CLASSES = {
+        inline: "Plumbing::Actor::Inline",
+        async: "Plumbing::Actor::Async",
+        threaded: "Plumbing::Actor::Threaded",
+        threaded_rails: "Plumbing::Actor::Rails"
+      }.freeze
+      private_constant :PROXY_BASE_CLASSES
+
+      def register_actor_proxy_class_for target_class
+        Plumbing.config.register_actor_proxy_class_for(target_class, build_proxy_class)
+      end
+
+      def build_proxy_class
+        Class.new(proxy_base_class).tap do |proxy_class|
+          async_messages.each do |message|
+            proxy_class.define_method message do |*args, &block|
+              send_message(message, *args, &block)
+            end
+          end
+        end
+      end
+    end
+
+    private
+
+    def proxy= proxy
+      @proxy = proxy
+    end
+
+    def proxy = @proxy
+    alias_method :as_actor, :proxy
+    alias_method :async, :proxy
+
+    def perform_safely(&)
+      instance_eval(&)
+      nil
+    rescue => ex
+      puts ex
+      nil
+    end
+  end
+end

data/lib/plumbing/config.rb

@@ -1,12 +1,12 @@
-# Pipes, pipelines, valves and rubber ducks
+# Pipes, pipelines, actors and rubber ducks
 module Plumbing
-  Config = Data.define :mode, :valve_proxy_classes, :timeout do
-    def valve_proxy_class_for target_class
-      valve_proxy_classes[target_class]
+  Config = Data.define :mode, :actor_proxy_classes, :timeout do
+    def actor_proxy_class_for target_class
+      actor_proxy_classes[target_class]
     end
 
-    def register_valve_proxy_class_for target_class, proxy_class
-      valve_proxy_classes[target_class] = proxy_class
+    def register_actor_proxy_class_for target_class, proxy_class
+      actor_proxy_classes[target_class] = proxy_class
     end
   end
   private_constant :Config
@@ -23,7 +23,7 @@ module Plumbing
   # @option timeout [Integer] the timeout (in seconds) to use (30s is the default)
   # @yield optional block - after the block has completed its execution, the configuration is restored to its previous state (useful for test suites)
   def self.configure(**params, &block)
-    new_config = Config.new(**config.to_h.merge(params).merge(valve_proxy_classes: {}))
+    new_config = Config.new(**config.to_h.merge(params).merge(actor_proxy_classes: {}))
     if block.nil?
       set_configuration_to new_config
     else
@@ -45,7 +45,7 @@ module Plumbing
   private_class_method :set_configuration_and_yield
 
   def self.configs
-    @configs ||= [Config.new(mode: :inline, timeout: 30, valve_proxy_classes: {})]
+    @configs ||= [Config.new(mode: :inline, timeout: 30, actor_proxy_classes: {})]
   end
   private_class_method :configs
 end

data/lib/plumbing/junction.rb

@@ -5,16 +5,17 @@ module Plumbing
     # @param sources [Array<Plumbing::Observable>] the sources which will be joined and relayed
     def initialize *sources
       super()
-      @sources = sources.collect { |source| add(source) }
+      sources.each { |source| add(source) }
     end
 
     private
 
     def add source
       source.as(Observable).add_observer do |event|
-        dispatch event
+        safely do
+          dispatch event
+        end
       end
-      source
     end
   end
 end

data/lib/plumbing/pipe.rb

@@ -1,10 +1,9 @@
 module Plumbing
   # A basic pipe
   class Pipe
-    include Plumbing::Valve
+    include Plumbing::Actor
 
-    command :notify, :<<, :remove_observer, :shutdown
-    query :add_observer, :is_observer?
+    async :notify, :<<, :remove_observer, :add_observer, :is_observer?, :shutdown
 
     # Push an event into the pipe
     # @param event [Plumbing::Event] the event to push into the pipe
@@ -50,6 +49,7 @@ module Plumbing
     # Subclasses should override this to perform their own shutdown routines and call `super` to ensure everything is tidied up
     def shutdown
       observers.clear
+      stop
     end
 
     protected

data/lib/plumbing/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Plumbing
-  VERSION = "0.3.3"
+  VERSION = "0.4.1"
 end

data/lib/plumbing.rb

@@ -2,7 +2,7 @@
 
 module Plumbing
   require_relative "plumbing/config"
-  require_relative "plumbing/valve"
+  require_relative "plumbing/actor"
   require_relative "plumbing/rubber_duck"
   require_relative "plumbing/types"
   require_relative "plumbing/error"

data/spec/become_equal_to_matcher.rb

@@ -9,12 +9,13 @@ require "rspec/expectations"
 #
 RSpec::Matchers.define :become_equal_to do
   match do |expected|
+    max = Plumbing.config.timeout * 10
     counter = 0
     matched = false
-    while (counter < 50) && (matched == false)
-      matched = true if (@result = block_arg.call) == expected
+    while (counter < max) && (matched == false)
       sleep 0.1
       counter += 1
+      matched = true if (@result = block_arg.call) == expected
     end
     matched
   end

data/spec/examples/{valve_spec.rb → actor_spec.rb}

@@ -1,38 +1,12 @@
 require "spec_helper"
+require "plumbing/actor/async"
+require "plumbing/actor/threaded"
 
-RSpec.shared_examples "an example valve" do |runs_in_background|
-  it "queries an object" do
-    @person = Employee.start "Alice"
-
-    expect(@person.name).to eq "Alice"
-    expect(@person.job_title).to eq "Sales assistant"
-
-    @time = Time.now
-    # `greet_slowly` is a query so will block until a response is received
-    expect(@person.greet_slowly).to eq "H E L L O"
-    expect(Time.now - @time).to be > 0.1
-
-    @time = Time.now
-    # we're ignoring the result so this will not block (except :inline mode which does not run in the background)
-    expect(@person.greet_slowly(ignore_result: true)).to be_nil
-    expect(Time.now - @time).to be < 0.1 if runs_in_background
-    expect(Time.now - @time).to be > 0.1 if !runs_in_background
-  end
-
-  it "commands an object" do
-    @person = Employee.start "Alice"
-    @person.promote
-    @job_title = @person.job_title
-    expect(@job_title).to eq "Sales manager"
-  end
-end
-
-RSpec.describe "Valve example: " do
+RSpec.shared_examples "an example actor" do |runs_in_background|
   # standard:disable Lint/ConstantDefinitionInBlock
   class Employee
-    include Plumbing::Valve
-    query :name, :job_title, :greet_slowly
-    command :promote
+    include Plumbing::Actor
+    async :name, :job_title, :greet_slowly, :promote
 
     def initialize(name)
       @name = name
@@ -53,12 +27,43 @@ RSpec.describe "Valve example: " do
   end
   # standard:enable Lint/ConstantDefinitionInBlock
 
+  it "queries an object" do
+    @person = Employee.start "Alice"
+
+    expect(await { @person.name }).to eq "Alice"
+    expect(await { @person.job_title }).to eq "Sales assistant"
+
+    @time = Time.now
+    # `greet_slowly` is a query so will block until a response is received
+    expect(await { @person.greet_slowly }).to eq "H E L L O"
+    expect(Time.now - @time).to be > 0.1
+
+    @time = Time.now
+    # we're not awaiting the result, so this should run in the background (unless we're using inline mode)
+    @person.greet_slowly
+
+    expect(Time.now - @time).to be < 0.1 if runs_in_background
+    expect(Time.now - @time).to be > 0.1 if !runs_in_background
+  ensure
+    @person.stop
+  end
+
+  it "commands an object" do
+    @person = Employee.start "Alice"
+    @person.promote
+    expect(@person.job_title.value).to eq "Sales manager"
+  ensure
+    @person.stop
+  end
+end
+
+RSpec.describe "Actor example: " do
   context "inline mode" do
     around :example do |example|
       Plumbing.configure mode: :inline, &example
     end
 
-    it_behaves_like "an example valve", false
+    it_behaves_like "an example actor", false
   end
 
   context "async mode" do
@@ -68,7 +73,7 @@ RSpec.describe "Valve example: " do
       end
     end
 
-    it_behaves_like "an example valve", true
+    it_behaves_like "an example actor", true
   end
 
   context "threaded mode" do
@@ -76,6 +81,6 @@ RSpec.describe "Valve example: " do
       Plumbing.configure mode: :threaded, &example
     end
 
-    it_behaves_like "an example valve", true
+    it_behaves_like "an example actor", true
   end
 end

data/spec/examples/await_spec.rb

@@ -0,0 +1,43 @@
+require "spec_helper"
+require "plumbing/actor/async"
+require "plumbing/actor/threaded"
+
+RSpec.describe "await" do
+  # standard:disable Lint/ConstantDefinitionInBlock
+  class Person
+    include Plumbing::Actor
+    async :name
+    def initialize name
+      @name = name
+    end
+    attr_reader :name
+  end
+  # standard:enable Lint/ConstantDefinitionInBlock
+
+  [:inline, :async, :threaded].each do |mode|
+    context "#{mode} mode" do
+      around :example do |example|
+        Sync do
+          Plumbing.configure mode: mode, &example
+        end
+      end
+
+      it "awaits a result from the actor directly" do
+        @person = Person.start "Alice"
+
+        expect(@person.name.value).to eq "Alice"
+      end
+
+      it "uses a block to await the result from the actor" do
+        @person = Person.start "Alice"
+
+        expect(await { @person.name }).to eq "Alice"
+      end
+
+      it "uses a block to immediately access non-actor objects" do
+        @person = "Bob"
+        expect(await { @person }).to eq "Bob"
+      end
+    end
+  end
+end

data/spec/examples/pipe_spec.rb

@@ -1,12 +1,14 @@
 require "spec_helper"
 require "async"
+require "plumbing/actor/async"
+require "plumbing/actor/threaded"
 
 RSpec.describe "Pipe examples" do
   it "observes events" do
     @source = Plumbing::Pipe.start
 
     @result = []
-    @observer = @source.add_observer do |event|
+    @source.add_observer do |event|
       @result << event.type
     end
 
@@ -22,7 +24,7 @@ RSpec.describe "Pipe examples" do
     end
 
     @result = []
-    @observer = @filter.add_observer do |event|
+    @filter.add_observer do |event|
       @result << event.type
     end
 
@@ -42,20 +44,22 @@ RSpec.describe "Pipe examples" do
       end
 
       def received event
-        @events << event
-        if @events.count >= 3
-          @events.clear
-          self << event
+        safely do
+          @events << event
+          if @events.count >= 3
+            @events.clear
+            self << event
+          end
         end
       end
     end
     # standard:enable Lint/ConstantDefinitionInBlock
 
     @source = Plumbing::Pipe.start
-    @filter = EveryThirdEvent.new(source: @source)
+    @filter = EveryThirdEvent.start(source: @source)
 
     @result = []
-    @observer = @filter.add_observer do |event|
+    @filter.add_observer do |event|
       @result << event.type
     end
 
@@ -73,7 +77,7 @@ RSpec.describe "Pipe examples" do
     @junction = Plumbing::Junction.start @first_source, @second_source
 
     @result = []
-    @observer = @junction.add_observer do |event|
+    @junction.add_observer do |event|
       @result << event.type
     end
 
@@ -83,7 +87,7 @@ RSpec.describe "Pipe examples" do
     expect(@result).to eq ["one", "two"]
   end
 
-  it "dispatches events asynchronously using fibers" do
+  it "dispatches events asynchronously using async" do
     Plumbing.configure mode: :async do
       Sync do
         @first_source = Plumbing::Pipe.start
@@ -106,4 +110,36 @@ RSpec.describe "Pipe examples" do
       end
     end
   end
+
+  it "dispatches events asynchronously using threads" do
+    Plumbing.configure mode: :threaded do
+      @result = []
+
+      @first_source = Plumbing::Pipe.start
+      @second_source = Plumbing::Pipe.start
+      @junction = Plumbing::Junction.start @first_source, @second_source
+
+      @filter = Plumbing::Filter.start source: @junction do |event|
+        %w[one-one two-two].include? event.type
+      end
+      await do
+        @filter.add_observer do |event|
+          puts "observing #{event.type}"
+          @result << event.type
+        end
+      end
+
+      @first_source.notify "one-one"
+      @first_source.notify "one-two"
+      @second_source.notify "two-one"
+      @second_source.notify "two-two"
+
+      expect(["one-one", "two-two"]).to become_equal_to { @result.sort }
+    ensure
+      @first_source.shutdown
+      @second_source.shutdown
+      @junction.shutdown
+      @filter.shutdown
+    end
+  end
 end

data/spec/plumbing/a_pipe.rb

@@ -1,10 +1,12 @@
 RSpec.shared_examples "a pipe" do
   it "adds a block observer" do
     @pipe = described_class.start
-    @observer = @pipe.add_observer do |event|
-      puts event.type
+    @observer = await do
+      @pipe.add_observer do |event|
+        puts event.type
+      end
     end
-    expect(@pipe.is_observer?(@observer)).to eq true
+    expect(await { @pipe.is_observer?(@observer) }).to eq true
   end
 
   it "adds a callable observer" do
@@ -13,13 +15,13 @@ RSpec.shared_examples "a pipe" do
 
     @pipe.add_observer @proc
 
-    expect(@pipe.is_observer?(@proc)).to eq true
+    expect(await { @pipe.is_observer?(@proc) }).to eq true
   end
 
   it "does not allow an observer without a #call method" do
     @pipe = described_class.start
 
-    expect { @pipe.add_observer(Object.new) }.to raise_error(TypeError)
+    expect { await { @pipe.add_observer(Object.new) } }.to raise_error(TypeError)
   end
 
   it "removes an observer" do
@@ -28,10 +30,10 @@ RSpec.shared_examples "a pipe" do
 
     @pipe.remove_observer @proc
 
-    expect(@pipe.is_observer?(@proc)).to eq false
+    expect(await { @pipe.is_observer?(@proc) }).to eq false
   end
 
-  it "does not send notifications for objects  which are not events" do
+  it "does not send notifications for objects which are not events" do
     @pipe = described_class.start
     @results = []
     @observer = @pipe.add_observer do |event|
@@ -40,7 +42,7 @@ RSpec.shared_examples "a pipe" do
 
     @pipe << Object.new
 
-    sleep 0.5
+    sleep 0.1
     expect(@results).to eq []
   end
 
@@ -96,11 +98,13 @@ RSpec.shared_examples "a pipe" do
 
   it "shuts down the pipe" do
     @pipe = described_class.start
+    @results = []
     @observer = ->(event) { @results << event }
     @pipe.add_observer @observer
 
     @pipe.shutdown
-
-    expect(@pipe.is_observer?(@observer)).to eq false
+    @pipe.notify "ignore_me"
+    sleep 0.2
+    expect(@results).to be_empty
   end
 end

data/spec/plumbing/actor/transporter_spec.rb

@@ -0,0 +1,159 @@
+require "spec_helper"
+require_relative "../../../lib/plumbing/actor/transporter"
+
+RSpec.describe Plumbing::Actor::Transporter do
+  # standard:disable Lint/ConstantDefinitionInBlock
+  class Record
+    include GlobalID::Identification
+    attr_reader :id
+    def initialize id
+      @id = id
+    end
+
+    def == other
+      other.id == @id
+    end
+  end
+  # standard:enable Lint/ConstantDefinitionInBlock
+
+  before do
+    GlobalID.app = "rspec"
+    GlobalID::Locator.use :rspec do |gid, options|
+      Record.new gid.model_id
+    end
+  end
+
+  context "marshalling" do
+    it "passes simple arguments" do
+      @transporter = described_class.new
+
+      @transport = @transporter.marshal "Hello"
+      expect(@transport).to eq ["Hello"]
+
+      @transport = @transporter.marshal 1, 2, 3
+      expect(@transport).to eq [1, 2, 3]
+    end
+
+    it "copies arrays" do
+      @transporter = described_class.new
+
+      @source = [[1, 2, 3], [:this, :that]]
+
+      @transport = @transporter.marshal(*@source)
+      expect(@transport).to eq @source
+      expect(@transport.first.object_id).to_not eq @source.first.object_id
+      expect(@transport.last.object_id).to_not eq @source.last.object_id
+    end
+
+    it "copies hashss" do
+      @transporter = described_class.new
+
+      @source = [{first: "1", second: 2}]
+
+      @transport = @transporter.marshal(*@source)
+      expect(@transport).to eq @source
+      expect(@transport.first.object_id).to_not eq @source.first.object_id
+    end
+
+    it "converts objects to Global ID strings" do
+      @transporter = described_class.new
+
+      @record = Record.new 123
+      @global_id = @record.to_global_id.to_s
+
+      @transport = @transporter.marshal @record
+
+      expect(@transport).to eq [@global_id]
+    end
+
+    it "converts objects within arrays to Global ID strings" do
+      @transporter = described_class.new
+
+      @record = Record.new 123
+      @global_id = @record.to_global_id.to_s
+
+      @transport = @transporter.marshal [:this, @record]
+
+      expect(@transport).to eq [[:this, @global_id]]
+    end
+
+    it "converts objects within hashes to Global ID strings" do
+      @transporter = described_class.new
+
+      @record = Record.new 123
+      @global_id = @record.to_global_id.to_s
+
+      @transport = @transporter.marshal this: "that", the_other: {embedded: @record}
+
+      expect(@transport).to eq [{this: "that", the_other: {embedded: @global_id}}]
+    end
+  end
+
+  context "unmarshalling" do
+    it "passes simple arguments" do
+      @transporter = described_class.new
+
+      @transport = @transporter.unmarshal "Hello"
+      expect(@transport).to eq ["Hello"]
+
+      @transport = @transporter.unmarshal 1, 2, 3
+      expect(@transport).to eq [1, 2, 3]
+    end
+
+    it "passes arrays" do
+      @transporter = described_class.new
+
+      @transport = @transporter.unmarshal [1, 2, 3], [:this, :that]
+
+      expect(@transport.first.object_id).to_not eq [1, 2, 3]
+      expect(@transport.last.object_id).to_not eq [:this, :that]
+    end
+
+    it "passes hashss and keyword arguments" do
+      @transporter = described_class.new
+
+      @transport = @transporter.unmarshal first: "1", second: 2
+      expect(@transport).to eq [{first: "1", second: 2}]
+    end
+
+    it "passes mixtures of arrays and hashes" do
+      @transporter = described_class.new
+
+      @transport = @transporter.unmarshal :this, :that, first: "1", second: 2
+      expect(@transport).to eq [:this, :that, {first: "1", second: 2}]
+    end
+
+    it "converts Global ID strings to objects" do
+      @transporter = described_class.new
+
+      @record = Record.new "123"
+      @global_id = @record.to_global_id.to_s
+
+      @transport = @transporter.unmarshal @global_id
+
+      expect(@transport).to eq [@record]
+    end
+
+    it "converts Global ID strings within arrays to objects" do
+      @transporter = described_class.new
+
+      @record = Record.new "123"
+      @global_id = @record.to_global_id.to_s
+
+      @transport = @transporter.unmarshal :this, @global_id
+
+      expect(@transport).to eq [:this, @record]
+    end
+
+    it "converts Global ID strings within hashes to objects" do
+      @transporter = described_class.new
+
+      @record = Record.new "123"
+      @global_id = @record.to_global_id.to_s
+
+      @transport = @transporter.unmarshal this: "that", the_other: {embedded: @global_id}
+
+      expect(@transport).to eq [{this: "that", the_other: {embedded: @record}}]
+    end
+  end
+end