standard-procedure-plumbing 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a51cb6cf16fcc70cd0f6607a461e817c7021ed9f0de445e1f628ff1a8de9e489
-  data.tar.gz: 992e53f3a79cb4f3597b9758e10953156ec9dda073eff97bc740e6050746fddc
+  metadata.gz: ace6c01658b88c08c34d48406f983fdad449bc4f122b8dfed026853841b48d35
+  data.tar.gz: 96b4458d0c667e10bb47fb8881de2e21df0ff40243cf07ff30e2e22f29892625
 SHA512:
-  metadata.gz: f4ff32c0bbd46d2433bcb051572914fa96378f5ffe6badd0fa77462565c058357b6803ff98afcf4534a739a571bb9084e39fe045ec4415dd084379d12e99e684
-  data.tar.gz: 6a1d52c882d1edb1d5705383596e4b4c556f4f561770466a4bd18529e8e21630d3c522d323feb6fed8e0b87c22bc35b56075b47ae53a62a9176473061b0840a0
+  metadata.gz: a5ee7af05314dbb45d9f46a302f6102f93237334224f82f1c34cdd5c252829039bf6b4bc18a562fcdb5d76a8ca229a484b0f3d3e123b7e5efd46d302f50c72b4
+  data.tar.gz: 005f6cee1eb899207659955ea5a4179133c65e07db913e8f3f9c730cfca8947684927c9b99b675e9f54dc4ea4820159d709d61b146113a993783cec2a0c5842c

data/README.md

@@ -12,7 +12,7 @@ By default it is `:inline`, so every command or query is handled synchronously.
 
 `:threaded` mode handles tasks using a thread pool via [Concurrent Ruby](https://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Promises.html)).  Your code should include the "concurrent-ruby" gem in its bundle, as Plumbing does not load it by default.
 
-However, `:threaded` mode is not safe for Ruby on Rails applications.  In this case, use `:rails` mode, which is identical to `:threaded`, except it wraps the tasks in the Rails executor.  This ensures your actors do not interfere with the Rails framework.  Note that the Concurrent Ruby's default `:io` scheduler will create extra threads at times of high demand, which may put pressure on the ActiveRecord database connection pool.  A future version of plumbing will allow the thread pool to be adjusted with a maximum number of threads, preventing contention with the connection pool.
+However, `:threaded` mode is not safe for Ruby on Rails applications.  In this case, use `:threaded_rails` mode, which is identical to `:threaded`, except it wraps the tasks in the Rails executor.  This ensures your actors do not interfere with the Rails framework.  Note that the Concurrent Ruby's default `:io` scheduler will create extra threads at times of high demand, which may put pressure on the ActiveRecord database connection pool.  A future version of plumbing will allow the thread pool to be adjusted with a maximum number of threads, preventing contention with the connection pool.
 
 The `timeout` setting is used when performing queries - it defaults to 30s.
 
@@ -165,40 +165,82 @@ Actors are different.  Conceptually, each actor has it's own thread of execution
 
 This means each actor is only ever accessed by a single thread and the vast majority of concurrency issues are eliminated.
 
-[Plumbing::Actor](/lib/plumbing/actor.rb) allows you to define the `async` public interface to your objects.  Calling `.start` builds a proxy to the actual instance of your object and ensures that any messages sent are handled in a manner appropriate to the current mode - immediately for inline mode, using fibers for async mode and using threads for threaded and rails mode.
+[Plumbing::Actor](/lib/plumbing/actor.rb) allows you to define the `async` public interface to your objects.  Calling `.start` builds a proxy to the actual instance of your object and ensures that any messages sent are handled in a manner appropriate to the current mode - immediately for inline mode, using fibers for async mode and using threads for threaded and threaded_rails mode.
 
 When sending messages to an actor, this just works.
 
-However, as the caller, you do not have direct access to the return values of the messages that you send.  Instead, you must call `#await` - or alternatively, wrap your call in `await { ... }`.  `await` is added in to ruby's `Kernel` so it is available everywhere.  This then makes the caller's thread block until the receiver's thread has finished its work and returned a value.  Or if the receiver raises an exception, that exception is then re-raised in the calling thread.
+However, as the caller, you do not have direct access to the return values of the messages that you send.  Instead, you must call `#value` - or alternatively, wrap your call in `await { ... }`.  The block form of `await` is added in to ruby's `Kernel` so it is available everywhere.  It is also safe to use with non-actors (in which case it just returns the original value from the block).
+
+```ruby
+@actor = MyActor.start name: "Alice"
+
+@actor.name.value
+# => "Alice"
+
+await { @actor.name }
+# => "Alice"
+
+await { "Bob" }
+# => "Bob"
+```
+
+This then makes the caller's thread block until the receiver's thread has finished its work and returned a value.  Or if the receiver raises an exception, that exception is then re-raised in the calling thread.
+
+The actor model does not eliminate every possible concurrency issue.  If you use `value` or `await`, it is possible to deadlock yourself.
 
-The actor model does not eliminate every possible concurrency issue.  If you use `await`, it is possible to deadlock yourself.
 Actor A, running in Thread 1, sends a message to Actor B and then awaits the result, meaning Thread 1 is blocked.  Actor B, running in Thread 2, starts to work, but needs to ask Actor A a question.  So it sends a message to Actor A and awaits the result.  Thread 2 is now blocked, waiting for Actor A to respond.  But Actor A, running in Thread 1, is blocked, waiting for Actor B to respond.
 
-This potential deadlock only occurs if you use `await` and have actors that call back in to each other.  If your objects are strictly layered, or you never use `await` (perhaps, instead using a Pipe to observe events), then this particular deadlock should not occur.  However, just in case, every call to `await` has a timeout defaulting to 30s.
+This potential deadlock only occurs if you use `value` or `await` and have actors that call back in to each other.  If your objects are strictly layered, or you never use `value` or `await` (perhaps, instead using a Pipe to observe events), then this particular deadlock should not occur.  However, just in case, every call to `value` has a timeout defaulting to 30s.
 
 ### Inline actors
 
-Even though inline mode is not asynchronous, you must still use `await` to access the results from another actor.  However, as deadlocks are impossible in a single thread, there is no timeout.
+Even though inline mode is not asynchronous, you must still use `value` or `await` to access the results from another actor.  However, as deadlocks are impossible in a single thread, there is no timeout.
 
 ### Async actors
 
 Using async mode is probably the easiest way to add concurrency to your application.  It uses fibers to allow for "concurrency but not parallelism" - that is execution will happen in the background but your objects or data will never be accessed by two things at the exact same time.
 
-### Threaded actprs
+### Threaded actors
 
-Using threaded (or rails) mode gives you concurrency and parallelism.  If all your public objects are actors and you are careful about callbacks then the actor model will keep your code safe.  But there are a couple of extra things to consider.
+Using threaded (or threaded_rails) mode gives you concurrency and parallelism.  If all your public objects are actors and you are careful about callbacks then the actor model will keep your code safe.  But there are a couple of extra things to consider.
 
 Firstly, when you pass parameters or return results between threads, those objects are "transported" across the boundaries.
-Most objects are `clone`d. Hashes, keyword arguments and arrays have their contents recursively transported.  And any object that uses `GlobalID::Identification` (for example, ActiveRecord models) are marshalled into a GlobalID, then unmarshalled back in to their original object.  This is to prevent the same object from being amended in both the caller and receiver's threads.
-Secondly, when you pass a block (or Proc parameter) to another actor, the block/proc will be executed in the receiver's thread.  This means you must not access any variables that would normally be in scope for your block (whether local variables or instance variables of other objects - see note below)  This is because you will be accessing them from a different thread to where they were defined, leading to potential race conditions.  And, if you access any actors, you must not use `await` or you risk a deadlock.  If you do pass a block or proc parameter, you should limit your actions to sending a message to other actors without awaiting the results.
+Most objects are cloned. Hashes, keyword arguments and arrays have their contents recursively transported.  And any object that uses `GlobalID::Identification` (for example, ActiveRecord models) are marshalled into a GlobalID, then unmarshalled back in to their original object.  This is to prevent the same object from being amended in both the caller and receiver's threads.
+
+Secondly, when you pass a block (or Proc parameter) to another actor, the block/proc will be executed in the receiver's thread.  This means you must not access any variables that would normally be in scope for your block (whether local variables or instance variables of other objects - see note below)  This is because you will be accessing them from a different thread to where they were defined, leading to potential race conditions.  And, if you access any actors, you must not use `value` or `await` or you risk a deadlock.  If you are within an actor and need to pass a block or proc parameter, you should use the `safely` method to ensure that your block is run within the context of the calling actor, not the receiving actor.
+
+For example, when defining a custom filter,  the filter adds itself as an observer to its source.  The source triggers the `received` method on the filter, which will run in the context of the source.  So the custom filter uses `safely` to move back into its own context and access its instance variables.
+
+```ruby
+class EveryThirdEvent < Plumbing::CustomFilter
+  def initialize source:
+    super
+    @events = []
+  end
+
+  def received event
+    safely do
+      @events << event
+      if @events.count >= 3
+        @events.clear
+        self << event
+      end
+    end
+  end
+end
+```
+
+(Note: we break that rule in the specs for Pipe objects - we use a block observer that sets the value on a local variable.  That's because it is a controlled situation where we know there are only two threads involved and we are explicitly waiting for the second thread to complete.  For almost every app that uses actors, there will be multiple threads and it will be impossible to predict the access patterns).
 
-(Note: we break that rule in the specs for the Pipe object - we use a block observer that sets the value on a local variable.  That's because it is a controlled situation where we know there are only two threads involved and we are explicitly waiting for the second thread to complete.  For almost every app that uses actors, there will be multiple threads and it will be impossible to predict the access patterns).
+### Constructing actors
 
 Instead of constructing your object with `.new`, use `.start`.  This builds a proxy object that wraps the target instance and dispatches messages through a safe mechanism.  Only messages that have been defined as part of the actor are available in this proxy - so you don't have to worry about callers bypassing the actor's internal context.
 
-Even when using actors, there is one condition where concurrency may cause issues.  If object A makes a query to object B which in turn makes a query back to object A, you will hit a deadlock.  This is because A is waiting on the response from B but B is now querying, and waiting for, A.  This does not apply to commands because they do not wait for a response.  However, when writing queries, be careful who you interact with - the configuration allows you to set a timeout (defaulting to 30s) in case this happens.
+### Referencing actors
 
-Also be aware that if you use actors in one place, you need to use them everywhere - especially if you're using threads or ractors (coming soon).  This is because as the actor sends messages to its collaborators, those calls will be made from within the actor's internal context.  If the collaborators are also actors, the subsequent messages will be handled correctly, if not, data consistency bugs could occur.
+If you're within a method inside your actor and you want to pass a reference to yourself, instead of using `self`, you should use `proxy` (which is also aliased as `as_actor` or `async`).
+
+Also be aware that if you use actors in one place, you need to use them everywhere - especially if you're using threads.  This is because as the actor sends messages to its collaborators, those calls will be made from within the actor's internal context.  If the collaborators are also actors, the subsequent messages will be handled correctly, if not, data consistency bugs could occur.  This does not mean that every class needs to be an actor, just your "public API" classes which may be accessed from multiple actors or other threads.
 
 ### Usage
 
@@ -208,17 +250,17 @@ Also be aware that if you use actors in one place, you need to use them everywhe
   require "plumbing"
 
   class Employee
-    attr_reader :name, :job_title
-
     include Plumbing::Actor
-    query :name, :job_title, :greet_slowly
-    command :promote
+    async :name, :job_title, :greet_slowly, :promote
+    attr_reader :name, :job_title
 
     def initialize(name)
       @name = name
       @job_title = "Sales assistant"
     end
 
+    private
+
     def promote
       sleep 0.5
       @job_title = "Sales manager"
@@ -237,16 +279,16 @@ Also be aware that if you use actors in one place, you need to use them everywhe
   await { @person.job_title }
   # => "Sales assistant"
 
-  # `greet_slowly` is a query so will block until a response is received
+  # by using `await`, we will block until `greet_slowly` has returned a value
   await { @person.greet_slowly }
   # =>  "H E L L O"
 
-  # we're not awaiting the result, so this will run in the background (unless we're using inline mode)
+  # this time, we're not awaiting the result, so this will run in the background (unless we're using inline mode)
   @person.greet_slowly
 
-  # This will run in the background
+  # this will run in the background
   @person.promote
-  # this will block, as we wait for the result from #job_title and #job_title will not run until after #promote has completed
+  # this will block - it will not return until the previous calls, #greet_slowly, #promote, and this call to #job_title have completed
   await { @person.job_title }
   # => "Sales manager"
 ```
@@ -302,12 +344,17 @@ Pipes are implemented as actors, meaning that event notifications can be dispatc
     end
 
     def received event
-      # store this event into our buffer
-      @events << event
-      # if this is the third event we've received then clear the buffer and broadcast the latest event
-      if @events.count >= 3
-        @events.clear
-        self << event
+      # #received is called in the context of the `source` actor
+      # in order to safely access the `EveryThirdEvent` instance variables
+      # we need to move into the context of our own actor
+      safely do
+        # store this event into our buffer
+        @events << event
+        # if this is the third event we've received then clear the buffer and broadcast the latest event
+        if @events.count >= 3
+          @events.clear
+          self << event
+        end
       end
     end
   end
@@ -344,31 +391,6 @@ Pipes are implemented as actors, meaning that event notifications can be dispatc
   @second_source.notify "two"
   # => "two"
 ```
-
-[Dispatching events asynchronously (using Fibers)](/spec/examples/pipe_spec.rb):
-```ruby
-  require "plumbing"
-  require "async"
-
-  Plumbing.configure mode: :async
-
-  Sync do
-    @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
-
-    @first_source.notify "one-one"
-    @first_source.notify "one-two"
-    @second_source.notify "two-one"
-    @second_source.notify "two-two"
-  end
-```
-
 ## Plumbing::RubberDuck - duck types and type-casts
 
 Define an [interface or protocol](https://en.wikipedia.org/wiki/Interface_(object-oriented_programming)) specifying which messages you expect to be able to send.

data/lib/plumbing/actor/async.rb

@@ -21,8 +21,19 @@ module Plumbing
         Result.new(task)
       end
 
+      def safely(&)
+        send_message(:perform_safely, &)
+        nil
+      end
+
+      def within_actor? = true
+
+      def stop
+        # do nothing
+      end
+
       Result = Data.define(:task) do
-        def await
+        def value
           Timeout.timeout(Plumbing::Actor.timeout) do
             task.wait
           end

data/lib/plumbing/actor/inline.rb

@@ -13,8 +13,19 @@ module Plumbing
         Result.new(ex)
       end
 
-      Result = Data.define(:value) do
-        def await = value.is_a?(Exception) ? raise(value) : value
+      def safely(&)
+        send_message(:perform_safely, &)
+        nil
+      end
+
+      def within_actor? = true
+
+      def stop
+        # do nothing
+      end
+
+      Result = Data.define(:result) do
+        def value = result.is_a?(Exception) ? raise(result) : result
       end
       private_constant :Result
     end

data/lib/plumbing/actor/kernel.rb

@@ -2,7 +2,8 @@ module Plumbing
   module Actor
     ::Kernel.class_eval do
       def await &block
-        block.call.await
+        result = block.call
+        result.respond_to?(:value) ? result.send(:value) : result
       end
     end
   end

data/lib/plumbing/actor/threaded.rb

@@ -12,28 +12,41 @@ module Plumbing
       def initialize target
         @target = target
         @queue = Concurrent::Array.new
+        @mutex = Thread::Mutex.new
       end
 
       # Send the message to the target and wrap the result
       def send_message message_name, *args, &block
         Message.new(@target, message_name, Plumbing::Actor.transporter.marshal(*args), block, Concurrent::MVar.new).tap do |message|
-          @queue << message
-          send_messages if @queue.size == 1
+          @mutex.synchronize do
+            @queue << message
+            send_messages if @queue.any?
+          end
         end
       end
 
-      protected
+      def safely(&)
+        send_message(:perform_safely, &)
+        nil
+      end
+
+      def within_actor? = @mutex.owned?
 
-      def future(&)
-        Concurrent::Promises.future(&)
+      def stop
+        within_actor? ? @queue.clear : @mutex.synchronize { @queue.clear }
       end
 
+      protected
+
+      def future(&) = Concurrent::Promises.future(&)
+
       private
 
       def send_messages
         future do
-          while (message = @queue.shift)
-            message.call
+          @mutex.synchronize do
+            message = @queue.shift
+            message&.call
           end
         end
       end
@@ -42,12 +55,13 @@ module Plumbing
         def call
           args = Plumbing::Actor.transporter.unmarshal(*packed_args)
           value = target.send message_name, *args, &unsafe_block
+
           result.put Plumbing::Actor.transporter.marshal(value)
         rescue => ex
           result.put ex
         end
 
-        def await
+        def value
           value = Plumbing::Actor.transporter.unmarshal(*result.take(Plumbing.config.timeout)).first
           raise value if value.is_a? Exception
           value

data/lib/plumbing/actor.rb

@@ -3,6 +3,15 @@ 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
@@ -10,8 +19,11 @@ module Plumbing
     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(*, **, &)
-        build_proxy_for(new(*, **, &))
+      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
@@ -41,7 +53,7 @@ module Plumbing
         inline: "Plumbing::Actor::Inline",
         async: "Plumbing::Actor::Async",
         threaded: "Plumbing::Actor::Threaded",
-        rails: "Plumbing::Actor::Rails"
+        threaded_rails: "Plumbing::Actor::Rails"
       }.freeze
       private_constant :PROXY_BASE_CLASSES
 
@@ -59,5 +71,23 @@ module Plumbing
         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/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

@@ -49,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.4.0"
+  VERSION = "0.4.1"
 end

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/actor_spec.rb

@@ -1,6 +1,32 @@
 require "spec_helper"
+require "plumbing/actor/async"
+require "plumbing/actor/threaded"
 
 RSpec.shared_examples "an example actor" do |runs_in_background|
+  # standard:disable Lint/ConstantDefinitionInBlock
+  class Employee
+    include Plumbing::Actor
+    async :name, :job_title, :greet_slowly, :promote
+
+    def initialize(name)
+      @name = name
+      @job_title = "Sales assistant"
+    end
+
+    attr_reader :name, :job_title
+
+    def promote
+      sleep 0.5
+      @job_title = "Sales manager"
+    end
+
+    def greet_slowly
+      sleep 0.2
+      "H E L L O"
+    end
+  end
+  # standard:enable Lint/ConstantDefinitionInBlock
+
   it "queries an object" do
     @person = Employee.start "Alice"
 
@@ -18,41 +44,20 @@ RSpec.shared_examples "an example actor" do |runs_in_background|
 
     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
-    @job_title = await { @person.job_title }
-    expect(@job_title).to eq "Sales manager"
+    expect(@person.job_title.value).to eq "Sales manager"
+  ensure
+    @person.stop
   end
 end
 
 RSpec.describe "Actor example: " do
-  # standard:disable Lint/ConstantDefinitionInBlock
-  class Employee
-    include Plumbing::Actor
-    async :name, :job_title, :greet_slowly, :promote
-
-    def initialize(name)
-      @name = name
-      @job_title = "Sales assistant"
-    end
-
-    attr_reader :name, :job_title
-
-    def promote
-      sleep 0.5
-      @job_title = "Sales manager"
-    end
-
-    def greet_slowly
-      sleep 0.2
-      "H E L L O"
-    end
-  end
-  # standard:enable Lint/ConstantDefinitionInBlock
-
   context "inline mode" do
     around :example do |example|
       Plumbing.configure mode: :inline, &example

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,5 +1,7 @@
 require "spec_helper"
 require "async"
+require "plumbing/actor/async"
+require "plumbing/actor/threaded"
 
 RSpec.describe "Pipe examples" do
   it "observes events" do
@@ -42,17 +44,19 @@ 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 = []
     @filter.add_observer do |event|
@@ -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

@@ -98,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(await { @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

@@ -15,6 +15,7 @@ RSpec.describe Plumbing::Actor::Transporter do
     end
   end
   # standard:enable Lint/ConstantDefinitionInBlock
+
   before do
     GlobalID.app = "rspec"
     GlobalID::Locator.use :rspec do |gid, options|

data/spec/plumbing/actor_spec.rb

@@ -51,6 +51,67 @@ RSpec.describe Plumbing::Actor do
       raise "I'm a failure"
     end
   end
+
+  class WhoAmI
+    include Plumbing::Actor
+    async :me_as_actor, :me_as_self
+
+    private
+
+    def me_as_actor = as_actor
+
+    def me_as_self = self
+
+    def prepare = @calling_thread = Thread.current
+
+    def check = @calling_thread == Thread.current
+  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
+
+  class SafetyCheck
+    include Plumbing::Actor
+    async :called_from_actor_thread?
+
+    def initialize tester
+      @tester = tester
+      @called_from_actor_thread = false
+      configure_safety_check
+    end
+
+    private
+
+    def called_from_actor_thread? = @called_from_actor_thread
+
+    def configure_safety_check
+      @tester.on_safety_check do
+        safely do
+          @called_from_actor_thread = proxy.within_actor?
+        end
+      end
+    end
+  end
+
+  class Tester
+    include Plumbing::Actor
+    async :on_safety_check, :do_safety_check
+
+    def initialize
+      @on_safety_check = nil
+    end
+
+    private
+
+    def on_safety_check(&block) = @on_safety_check = block
+
+    def do_safety_check = @on_safety_check&.call
+  end
   # standard:enable Lint/ConstantDefinitionInBlock
 
   it "knows which async messages are understood" do
@@ -65,15 +126,22 @@ RSpec.describe Plumbing::Actor do
     expect(@counter.class).to eq @proxy_class
   end
 
-  it "includes commands and queries from the superclass" do
+  it "includes async messages 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
+    expect(@step_counter.count.value).to eq 100
+    expect(@step_counter.step_value.value).to eq 10
     @step_counter.slowly_increment
-    expect(@step_counter.count.await).to eq 110
+    expect(@step_counter.count.value).to eq 110
+  end
+
+  it "can access its own proxy" do
+    @actor = WhoAmI.start
+
+    expect(await { @actor.me_as_self }).to_not eq @actor
+    expect(await { @actor.me_as_actor }).to eq @actor
   end
 
   context "inline" do
@@ -85,11 +153,11 @@ RSpec.describe Plumbing::Actor 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(@counter.name.value).to eq "inline counter"
+      expect(@counter.count.value).to eq 100
       expect(Time.now - @time).to be < 0.1
 
-      expect(@counter.slow_query.await).to eq 100
+      expect(@counter.slow_query.value).to eq 100
       expect(Time.now - @time).to be > 0.1
     end
 
@@ -99,9 +167,18 @@ RSpec.describe Plumbing::Actor do
 
       @counter.slowly_increment
 
-      expect(@counter.count.await).to eq 101
+      expect(@counter.count.value).to eq 101
       expect(Time.now - @time).to be > 0.1
     end
+
+    it "can safely access its own data" do
+      @tester = Tester.start
+      @safety_check = SafetyCheck.start @tester
+
+      @tester.do_safety_check
+
+      expect(true).to become_equal_to { @safety_check.called_from_actor_thread?.value }
+    end
   end
 
   [:threaded, :async].each do |mode|
@@ -116,12 +193,14 @@ RSpec.describe Plumbing::Actor 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(@counter.name.value).to eq "async counter"
+        expect(@counter.count.value).to eq 100
         expect(Time.now - @time).to be < 0.1
 
-        expect(@counter.slow_query.await).to eq 100
+        expect(@counter.slow_query.value).to eq 100
         expect(Time.now - @time).to be > 0.1
+      ensure
+        @counter.stop
       end
 
       it "performs queries ignoring the response and returning immediately" do
@@ -131,6 +210,8 @@ RSpec.describe Plumbing::Actor do
         @counter.slow_query
 
         expect(Time.now - @time).to be < 0.1
+      ensure
+        @counter.stop
       end
 
       it "performs commands in the background and returning immediately" do
@@ -141,20 +222,26 @@ RSpec.describe Plumbing::Actor do
         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(101).to become_equal_to { @counter.count.value }
         expect(Time.now - @time).to be > 0.1
+      ensure
+        @counter.stop
       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"
+        expect { @counter.raises_error.value }.to raise_error "I'm an error"
+      ensure
+        @counter.stop
       end
 
       it "does not raise exceptions if ignoring the result" do
         @counter = Counter.start "failure"
 
         expect { @counter.raises_error }.not_to raise_error
+      ensure
+        @counter.stop
       end
     end
   end
@@ -164,6 +251,13 @@ RSpec.describe Plumbing::Actor do
       Plumbing.configure mode: :threaded, &example
     end
 
+    before do
+      GlobalID.app = "rspec"
+      GlobalID::Locator.use :rspec do |gid, options|
+        Record.new gid.model_id
+      end
+    end
+
     # standard:disable Lint/ConstantDefinitionInBlock
     class Record
       include GlobalID::Identification
@@ -176,33 +270,41 @@ RSpec.describe Plumbing::Actor do
         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
+      @object_id = @actor.get_object_id(@record).value
 
       expect(@object_id).to_not eq @record.object_id
+    ensure
+      @actor.stop
     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
+      @object = @actor.get_object(@record).value
 
       expect(@object.id).to eq @record.id
       expect(@object.object_id).to_not eq @record.object_id
+    ensure
+      @actor.stop
+    end
+
+    it "can safely access its own data" do
+      @tester = Tester.start
+      @safety_check = SafetyCheck.start @tester
+
+      @tester.do_safety_check
+
+      expect(true).to become_equal_to { @safety_check.called_from_actor_thread?.value }
+    ensure
+      @tester.stop
+      @safety_check.stop
     end
   end
 end

data/spec/plumbing/custom_filter_spec.rb

@@ -15,7 +15,7 @@ RSpec.describe Plumbing::CustomFilter do
     # standard:enable Lint/ConstantDefinitionInBlock
 
     @pipe = Plumbing::Pipe.start
-    @filter = ReversingFilter.new(source: @pipe)
+    @filter = ReversingFilter.start(source: @pipe)
     @result = []
     @filter.add_observer do |event|
       @result << event.type

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: standard-procedure-plumbing
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Rahoul Baruah
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-15 00:00:00.000000000 Z
+date: 2024-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: globalid
@@ -59,6 +59,7 @@ files:
 - lib/plumbing/version.rb
 - spec/become_equal_to_matcher.rb
 - spec/examples/actor_spec.rb
+- spec/examples/await_spec.rb
 - spec/examples/pipe_spec.rb
 - spec/examples/pipeline_spec.rb
 - spec/examples/rubber_duck_spec.rb