standard-procedure-plumbing 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a51cb6cf16fcc70cd0f6607a461e817c7021ed9f0de445e1f628ff1a8de9e489
-  data.tar.gz: 992e53f3a79cb4f3597b9758e10953156ec9dda073eff97bc740e6050746fddc
+  metadata.gz: 77cd887e8bdfc09198bcf94c65b6d52014383b6691625f41e7301b52ae223adf
+  data.tar.gz: 4196496eff4bbc7b277592b22855dca3c29d87115130ca08a57796cb14436aae
 SHA512:
-  metadata.gz: f4ff32c0bbd46d2433bcb051572914fa96378f5ffe6badd0fa77462565c058357b6803ff98afcf4534a739a571bb9084e39fe045ec4415dd084379d12e99e684
-  data.tar.gz: 6a1d52c882d1edb1d5705383596e4b4c556f4f561770466a4bd18529e8e21630d3c522d323feb6fed8e0b87c22bc35b56075b47ae53a62a9176473061b0840a0
+  metadata.gz: 8e8614ed73bb33446e89294b7c94da3f39786a3c82704ac1c5187d5310edb5756db00bdfd38128743496b4af2bd1fdbde3027850a83406efdf76d5bd5fb3cf74
+  data.tar.gz: f5b1d8f95e6a275817348a95b3761d0dcb991d2e504b87dbcf2a35f1b4a4ac0f96bc0a90a70f59113644034291dd9af83f30adcfb30965bc4c35ec3dc5996502

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.
@@ -447,6 +469,8 @@ You can also use the same `@object.as type` to type-check instances against modu
 
 ## Installation
 
+Note: this gem is licensed under the [LGPL](/LICENCE).  This may or may not make it unsuitable for use by you or your company.
+
 Install the gem and add to the application's Gemfile by executing:
 
 ```sh

data/lib/plumbing/actor/async.rb

@@ -14,15 +14,24 @@ module Plumbing
       end
 
       # Send the message to the target and wrap the result
-      def send_message message_name, *args, &block
+      def send_message(message_name, *, **, &)
         task = @semaphore.async do
-          @target.send message_name, *args, &block
+          @target.send(message_name, *, **, &)
         end
         Result.new(task)
       end
 
+      def safely(&)
+        send_message(:perform_safely, &)
+        nil
+      end
+
+      def within_actor? = true
+
+      def stop = nil
+
       Result = Data.define(:task) do
-        def await
+        def value
           Timeout.timeout(Plumbing::Actor.timeout) do
             task.wait
           end

data/lib/plumbing/actor/inline.rb

@@ -6,15 +6,24 @@ module Plumbing
       end
 
       # Send the message to the target and wrap the result
-      def send_message(message_name, *, &)
-        value = @target.send(message_name, *, &)
+      def send_message(message_name, *, **, &)
+        value = @target.send(message_name, *, **, &)
         Result.new(value)
       rescue => ex
         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 = nil
+
+      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
+      def send_message(message_name, *args, **params, &block)
+        Message.new(@target, message_name, Plumbing::Actor.transporter.marshal(*args, **params), block, Concurrent::MVar.new).tap do |message|
+          @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
 
@@ -52,12 +64,30 @@ module Plumbing
       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)
+            proxy_class.define_method message do |*args, **params, &block|
+              send_message(message, *args, **params, &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/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.2"
 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,32 +51,176 @@ RSpec.describe Plumbing::Actor do
       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]
+  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
 
-  it "reuses existing proxy classes" do
-    @counter = Counter.start "inline counter", initial_value: 100
-    @proxy_class = @counter.class
+  class Actor
+    include Plumbing::Actor
+    async :get_object_id, :get_object
 
-    @counter = Counter.start "another inline counter", initial_value: 200
-    expect(@counter.class).to eq @proxy_class
+    private def get_object_id(record) = record.object_id
+    private def get_object(record) = record
   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]
+  class SafetyCheck
+    include Plumbing::Actor
+    async :called_from_actor_thread?
+
+    def initialize tester
+      @tester = tester
+      @called_from_actor_thread = false
+      configure_safety_check
+    end
 
-    @step_counter = StepCounter.start "step counter", initial_value: 100, step_value: 10
+    private
 
-    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
+    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
 
-  context "inline" do
+  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
+
+  class ParameterHandler
+    include Plumbing::Actor
+    async :set_values, :args, :params, :block
+    attr_reader :args, :params, :block
+
+    def initialize
+      @args = nil
+      @params = nil
+      @block = nil
+    end
+
+    private
+
+    def set_values *args, **params, &block
+      @args = args
+      @params = params
+      @block = block
+    end
+  end
+  # standard:enable Lint/ConstantDefinitionInBlock
+
+  [:inline, :async, :threaded].each do |mode|
+    context "In #{mode} mode" do
+      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 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.value).to eq 100
+        expect(@step_counter.step_value.value).to eq 10
+        @step_counter.slowly_increment
+        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
+      it "sends a single positional parameter" do
+        @parameter_handler = ParameterHandler.start
+
+        @parameter_handler.set_values "this"
+        expect(await { @parameter_handler.args }).to eq ["this"]
+      end
+
+      it "sends multiple positional parameters" do
+        @parameter_handler = ParameterHandler.start
+
+        @parameter_handler.set_values "this", "that"
+        expect(await { @parameter_handler.args }).to eq ["this", "that"]
+      end
+
+      it "sends keyword parameters" do
+        @parameter_handler = ParameterHandler.start
+
+        @parameter_handler.set_values something: "for nothing", cat: "dog", number: 123
+        expect(await { @parameter_handler.params }).to eq({something: "for nothing", cat: "dog", number: 123})
+      end
+
+      it "sends a mix of positional and keyword parameters" do
+        @parameter_handler = ParameterHandler.start
+
+        @parameter_handler.set_values "what do you say", 123, something: "for nothing"
+        expect(await { @parameter_handler.args }).to eq ["what do you say", 123]
+        expect(await { @parameter_handler.params }).to eq({something: "for nothing"})
+      end
+
+      it "sends a block parameter" do
+        @parameter_handler = ParameterHandler.start
+
+        @parameter_handler.set_values do
+          "HELLO"
+        end
+
+        @block = await { @parameter_handler.block }
+        expect(@block.call).to eq "HELLO"
+      end
+
+      it "sends a mix of positional and keyword parameters with a block" do
+        @parameter_handler = ParameterHandler.start
+
+        @parameter_handler.set_values "what do you say", 123, something: "for nothing" do
+          "BOOM"
+        end
+
+        expect(await { @parameter_handler.args }).to eq ["what do you say", 123]
+        expect(await { @parameter_handler.params }).to eq({something: "for nothing"})
+        @block = await { @parameter_handler.block }
+        expect(@block.call).to eq "BOOM"
+      end
+    end
+  end
+
+  context "Inline mode only" do
     around :example do |example|
       Plumbing.configure mode: :inline, &example
     end
@@ -85,11 +229,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,13 +243,22 @@ 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|
-    context mode.to_s do
+    context "Asynchronously (#{mode})" do
       around :example do |example|
         Sync do
           Plumbing.configure mode: mode, &example
@@ -116,12 +269,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 +286,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,29 +298,42 @@ 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
 
-  context "threaded" do
+  context "Threaded mode only" do
     around :example do |example|
       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 +346,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.2
 platform: ruby
 authors:
 - Rahoul Baruah
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-15 00:00:00.000000000 Z
+date: 2024-09-17 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
@@ -95,7 +96,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.12
+rubygems_version: 3.5.17
 signing_key:
 specification_version: 4
 summary: Plumbing - various pipelines for your ruby application