standard-procedure-plumbing 0.3.3 → 0.4.0

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

@@ -1,20 +1,21 @@
 require "spec_helper"
 
-RSpec.shared_examples "an example valve" do |runs_in_background|
+RSpec.shared_examples "an example actor" 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"
+    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(@person.greet_slowly).to eq "H E L L O"
+    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 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
+    # 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
   end
@@ -22,17 +23,16 @@ RSpec.shared_examples "an example valve" do |runs_in_background|
   it "commands an object" do
     @person = Employee.start "Alice"
     @person.promote
-    @job_title = @person.job_title
+    @job_title = await { @person.job_title }
     expect(@job_title).to eq "Sales manager"
   end
 end
 
-RSpec.describe "Valve example: " do
+RSpec.describe "Actor example: " do
   # 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
@@ -58,7 +58,7 @@ RSpec.describe "Valve example: " do
       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 +68,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 +76,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/pipe_spec.rb

@@ -6,7 +6,7 @@ RSpec.describe "Pipe examples" do
     @source = Plumbing::Pipe.start
 
     @result = []
-    @observer = @source.add_observer do |event|
+    @source.add_observer do |event|
       @result << event.type
     end
 
@@ -22,7 +22,7 @@ RSpec.describe "Pipe examples" do
     end
 
     @result = []
-    @observer = @filter.add_observer do |event|
+    @filter.add_observer do |event|
       @result << event.type
     end
 
@@ -55,7 +55,7 @@ RSpec.describe "Pipe examples" do
     @filter = EveryThirdEvent.new(source: @source)
 
     @result = []
-    @observer = @filter.add_observer do |event|
+    @filter.add_observer do |event|
       @result << event.type
     end
 
@@ -73,7 +73,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
 

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
 
@@ -101,6 +103,6 @@ RSpec.shared_examples "a pipe" do
 
     @pipe.shutdown
 
-    expect(@pipe.is_observer?(@observer)).to eq false
+    expect(await { @pipe.is_observer?(@observer) }).to eq false
   end
 end

data/spec/plumbing/actor/transporter_spec.rb

@@ -0,0 +1,158 @@
+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

data/spec/plumbing/actor_spec.rb

@@ -0,0 +1,208 @@
+require "spec_helper"
+
+require_relative "../../lib/plumbing/actor/async"
+require_relative "../../lib/plumbing/actor/threaded"
+require_relative "../../lib/plumbing/actor/rails"
+
+RSpec.describe Plumbing::Actor do
+  # standard:disable Lint/ConstantDefinitionInBlock
+  class Counter
+    include Plumbing::Actor
+    async :name, :count, :slow_query, "slowly_increment", "raises_error"
+    attr_reader :name, :count
+
+    def initialize name, initial_value: 0
+      @name = name
+      @count = initial_value
+    end
+
+    protected
+
+    def slowly_increment
+      sleep 0.2
+      @count += 1
+    end
+
+    def slow_query
+      sleep 0.2
+      @count
+    end
+
+    def raises_error = raise "I'm an error"
+  end
+
+  class StepCounter < Counter
+    async :step_value
+    attr_reader :step_value
+
+    def initialize name, initial_value: 0, step_value: 5
+      super(name, initial_value: initial_value)
+      @step_value = step_value
+    end
+
+    protected
+
+    def slowly_increment
+      sleep 0.2
+      @count += @step_value
+    end
+
+    def failing_query
+      raise "I'm a failure"
+    end
+  end
+  # standard:enable Lint/ConstantDefinitionInBlock
+
+  it "knows which async messages are understood" do
+    expect(Counter.async_messages).to eq [:name, :count, :slow_query, :slowly_increment, :raises_error]
+  end
+
+  it "reuses existing proxy classes" do
+    @counter = Counter.start "inline counter", initial_value: 100
+    @proxy_class = @counter.class
+
+    @counter = Counter.start "another inline counter", initial_value: 200
+    expect(@counter.class).to eq @proxy_class
+  end
+
+  it "includes commands and queries from the superclass" do
+    expect(StepCounter.async_messages).to eq [:name, :count, :slow_query, :slowly_increment, :raises_error, :step_value]
+
+    @step_counter = StepCounter.start "step counter", initial_value: 100, step_value: 10
+
+    expect(@step_counter.count.await).to eq 100
+    expect(@step_counter.step_value.await).to eq 10
+    @step_counter.slowly_increment
+    expect(@step_counter.count.await).to eq 110
+  end
+
+  context "inline" do
+    around :example do |example|
+      Plumbing.configure mode: :inline, &example
+    end
+
+    it "returns the result from a message immediately" do
+      @counter = Counter.start "inline counter", initial_value: 100
+      @time = Time.now
+
+      expect(@counter.name.await).to eq "inline counter"
+      expect(@counter.count.await).to eq 100
+      expect(Time.now - @time).to be < 0.1
+
+      expect(@counter.slow_query.await).to eq 100
+      expect(Time.now - @time).to be > 0.1
+    end
+
+    it "sends all commands immediately" do
+      @counter = Counter.start "inline counter", initial_value: 100
+      @time = Time.now
+
+      @counter.slowly_increment
+
+      expect(@counter.count.await).to eq 101
+      expect(Time.now - @time).to be > 0.1
+    end
+  end
+
+  [:threaded, :async].each do |mode|
+    context mode.to_s do
+      around :example do |example|
+        Sync do
+          Plumbing.configure mode: mode, &example
+        end
+      end
+
+      it "performs queries in the background and waits for the response" do
+        @counter = Counter.start "async counter", initial_value: 100
+        @time = Time.now
+
+        expect(@counter.name.await).to eq "async counter"
+        expect(@counter.count.await).to eq 100
+        expect(Time.now - @time).to be < 0.1
+
+        expect(@counter.slow_query.await).to eq 100
+        expect(Time.now - @time).to be > 0.1
+      end
+
+      it "performs queries ignoring the response and returning immediately" do
+        @counter = Counter.start "threaded counter", initial_value: 100
+        @time = Time.now
+
+        @counter.slow_query
+
+        expect(Time.now - @time).to be < 0.1
+      end
+
+      it "performs commands in the background and returning immediately" do
+        @counter = Counter.start "threaded counter", initial_value: 100
+        @time = Time.now
+
+        @counter.slowly_increment
+        expect(Time.now - @time).to be < 0.1
+
+        # wait for the background task to complete
+        expect(101).to become_equal_to { @counter.count.await }
+        expect(Time.now - @time).to be > 0.1
+      end
+
+      it "re-raises exceptions when checking the result" do
+        @counter = Counter.start "failure"
+
+        expect { @counter.raises_error.await }.to raise_error "I'm an error"
+      end
+
+      it "does not raise exceptions if ignoring the result" do
+        @counter = Counter.start "failure"
+
+        expect { @counter.raises_error }.not_to raise_error
+      end
+    end
+  end
+
+  context "threaded" do
+    around :example do |example|
+      Plumbing.configure mode: :threaded, &example
+    end
+
+    # 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
+
+    class Actor
+      include Plumbing::Actor
+      async :get_object_id, :get_object
+
+      private def get_object_id(record) = record.object_id
+      private def get_object(record) = record
+    end
+    # standard:enable Lint/ConstantDefinitionInBlock
+
+    it "packs and unpacks arguments when sending them across threads" do
+      @actor = Actor.start
+      @record = Record.new "999"
+
+      @object_id = @actor.get_object_id(@record).await
+
+      expect(@object_id).to_not eq @record.object_id
+    end
+
+    it "packs and unpacks results when sending them across threads" do
+      @actor = Actor.start
+      @record = Record.new "999"
+
+      @object = @actor.get_object(@record).await
+
+      expect(@object.id).to eq @record.id
+      expect(@object.object_id).to_not eq @record.object_id
+    end
+  end
+end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: standard-procedure-plumbing
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.4.0
 platform: ruby
 authors:
 - Rahoul Baruah
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-14 00:00:00.000000000 Z
-dependencies: []
+date: 2024-09-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: globalid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A composable event pipeline and sequential pipelines of operations
 email:
 - rahoulb@echodek.co
@@ -20,6 +34,13 @@ files:
 - README.md
 - Rakefile
 - lib/plumbing.rb
+- lib/plumbing/actor.rb
+- lib/plumbing/actor/async.rb
+- lib/plumbing/actor/inline.rb
+- lib/plumbing/actor/kernel.rb
+- lib/plumbing/actor/rails.rb
+- lib/plumbing/actor/threaded.rb
+- lib/plumbing/actor/transporter.rb
 - lib/plumbing/config.rb
 - lib/plumbing/custom_filter.rb
 - lib/plumbing/error.rb
@@ -35,26 +56,21 @@ files:
 - lib/plumbing/rubber_duck/object.rb
 - lib/plumbing/rubber_duck/proxy.rb
 - lib/plumbing/types.rb
-- lib/plumbing/valve.rb
-- lib/plumbing/valve/async.rb
-- lib/plumbing/valve/inline.rb
-- lib/plumbing/valve/message.rb
-- lib/plumbing/valve/rails.rb
-- lib/plumbing/valve/threaded.rb
 - lib/plumbing/version.rb
 - spec/become_equal_to_matcher.rb
+- spec/examples/actor_spec.rb
 - spec/examples/pipe_spec.rb
 - spec/examples/pipeline_spec.rb
 - spec/examples/rubber_duck_spec.rb
-- spec/examples/valve_spec.rb
 - spec/plumbing/a_pipe.rb
+- spec/plumbing/actor/transporter_spec.rb
+- spec/plumbing/actor_spec.rb
 - spec/plumbing/custom_filter_spec.rb
 - spec/plumbing/filter_spec.rb
 - spec/plumbing/junction_spec.rb
 - spec/plumbing/pipe_spec.rb
 - spec/plumbing/pipeline_spec.rb
 - spec/plumbing/rubber_duck_spec.rb
-- spec/plumbing/valve_spec.rb
 - spec/plumbing_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/standard-procedure/plumbing

data/lib/plumbing/valve/async.rb

@@ -1,43 +0,0 @@
-require "async"
-require "async/semaphore"
-require "timeout"
-
-module Plumbing
-  module Valve
-    class Async
-      attr_reader :target
-
-      def initialize target
-        @target = target
-        @queue = []
-        @semaphore = ::Async::Semaphore.new(1)
-      end
-
-      # Ask the target to answer the given message
-      def ask(message, *args, **params, &block)
-        task = @semaphore.async do
-          @target.send message, *args, **params, &block
-        end
-        Timeout.timeout(timeout) do
-          task.wait
-        end
-      end
-
-      # Tell the target to execute the given message
-      def tell(message, *args, **params, &block)
-        @semaphore.async do |task|
-          @target.send message, *args, **params, &block
-        rescue
-          nil
-        end
-        nil
-      end
-
-      private
-
-      def timeout
-        Plumbing.config.timeout
-      end
-    end
-  end
-end

data/lib/plumbing/valve/inline.rb

@@ -1,20 +0,0 @@
-module Plumbing
-  module Valve
-    class Inline
-      def initialize target
-        @target = target
-      end
-
-      # Ask the target to answer the given message
-      def ask(message, ...)
-        @target.send(message, ...)
-      end
-
-      # Tell the target to execute the given message
-      def tell(message, ...)
-        @target.send(message, ...)
-        nil
-      end
-    end
-  end
-end

data/lib/plumbing/valve/message.rb

@@ -1,5 +0,0 @@
-module Plumbing
-  module Valve
-    Message = Struct.new :message, :args, :params, :block, :result, :status
-  end
-end