standard-procedure-plumbing 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54681502a7df050136406e706c4fd6b9d9bffea81e44c151e969379e6803c532
-  data.tar.gz: ed03cbc9476d43822792fd6a4788b0c2e6c629545056063342f15c0861dc7dd0
+  metadata.gz: a51cb6cf16fcc70cd0f6607a461e817c7021ed9f0de445e1f628ff1a8de9e489
+  data.tar.gz: 992e53f3a79cb4f3597b9758e10953156ec9dda073eff97bc740e6050746fddc
 SHA512:
-  metadata.gz: 1387fdd83a547157541f444ccf2dcb9465c261616f424dc530ef4c9c13dda52214c21c4d50c99eb825e4827268f4892d62a29d212af9be21bc5bd65dd83422a4
-  data.tar.gz: c0dcbde3271e4d34cd41d16bda9c488ee40bd838ac0f006fd46bd23eb2c0c1cc4ea18d86236de1d8e87f6b5b97fc5dc728bedbd5a3e354fa09886094866404c9
+  metadata.gz: f4ff32c0bbd46d2433bcb051572914fa96378f5ffe6badd0fa77462565c058357b6803ff98afcf4534a739a571bb9084e39fe045ec4415dd084379d12e99e684
+  data.tar.gz: 6a1d52c882d1edb1d5705383596e4b4c556f4f561770466a4bd18529e8e21630d3c522d323feb6fed8e0b87c22bc35b56075b47ae53a62a9176473061b0840a0

data/README.md

@@ -1,55 +1,61 @@
 # Plumbing
 
-## Configuration 
+Actors, Observers and Data Pipelines.
 
-The most important configuration setting is the `mode`, which governs how messages are handled by Valves.   
+## Configuration
 
-By default it is `:inline`, so every command or query is handled synchronously.  
+The most important configuration setting is the `mode`, which governs how background tasks are handled.
 
-If it is set to `:async`, commands and queries will be handled using fibers (via the [Async gem](https://socketry.github.io/async/index.html)).
+By default it is `:inline`, so every command or query is handled synchronously.  This is the ruby behaviour you know and love (although see the section on `await` below).
 
-The `timeout` setting is used when performing queries - it defaults to 30s.  
+`:async` mode handles tasks using fibers (via the [Async gem](https://socketry.github.io/async/index.html)).  Your code should include the "async" gem in its bundle, as Plumbing does not load it by default.
+
+`: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.
+
+The `timeout` setting is used when performing queries - it defaults to 30s.
 
 ```ruby
   require "plumbing"
-  puts Plumbing.config.mode 
+  puts Plumbing.config.mode
   # => :inline
 
   Plumbing.configure mode: :async, timeout: 10
 
-  puts Plumbing.config.mode 
+  puts Plumbing.config.mode
   # => :async
 ```
 
-If you are running a test suite, you can temporarily update the configuration by passing a block.  
+If you are running a test suite, you can temporarily update the configuration by passing a block.
 
 ```ruby
   require "plumbing"
-  puts Plumbing.config.mode 
+  puts Plumbing.config.mode
   # => :inline
 
-  Plumbing.configure mode: :async do 
-    puts Plumbing.config.mode 
+  Plumbing.configure mode: :async do
+    puts Plumbing.config.mode
     # => :async
     first_test
     second_test
   end
 
-  puts Plumbing.config.mode 
+  puts Plumbing.config.mode
   # => :inline
 ```
 
 ## Plumbing::Pipeline - transform data through a pipeline
 
-Define a sequence of operations that proceed in order, passing their output from one operation as the input to another.  [Unix pipes](https://en.wikipedia.org/wiki/Pipeline_(Unix)) in Ruby.  
+Define a sequence of operations that proceed in order, passing their output from one operation as the input to another.  [Unix pipes](https://en.wikipedia.org/wiki/Pipeline_(Unix)) in Ruby.
 
-Use `perform` to define a step that takes some input and returns a different output.  
-  Specify `using` to re-use an existing `Plumbing::Pipeline` as a step within this pipeline.  
-Use `execute` to define a step that takes some input, performs an action but passes the input, unchanged, to the next step.  
+Use `perform` to define a step that takes some input and returns a different output.
+  Specify `using` to re-use an existing `Plumbing::Pipeline` as a step within this pipeline.
+Use `execute` to define a step that takes some input, performs an action but passes the input, unchanged, to the next step.
 
-If you have [dry-validation](https://dry-rb.org/gems/dry-validation/1.10/) installed, you can validate your input using a `Dry::Validation::Contract`.  Alternatively, you can define a `pre_condition` to test that the inputs are valid.  
+If you have [dry-validation](https://dry-rb.org/gems/dry-validation/1.10/) installed, you can validate your input using a `Dry::Validation::Contract`.  Alternatively, you can define a `pre_condition` to test that the inputs are valid.
 
-You can also verify that the output generated is as expected by defining a `post_condition`.  
+You can also verify that the output generated is as expected by defining a `post_condition`.
 
 ### Usage:
 
@@ -116,7 +122,7 @@ You can also verify that the output generated is as expected by defining a `post
   end
 
   SayHello.new.call(name: "Alice", email: "alice@example.com")
-  # => Hello Alice - I will now send a load of annoying marketing messages to alice@example.com 
+  # => Hello Alice - I will now send a load of annoying marketing messages to alice@example.com
 
   SayHello.new.call(some: "other data")
   # => Plumbing::PreConditionError
@@ -150,36 +156,61 @@ You can also verify that the output generated is as expected by defining a `post
   # => ["first", "external", "third"]
 ```
 
-## Plumbing::Valve - safe asynchronous objects
+## Plumbing::Actor - safe asynchronous objects
+
+An [actor](https://en.wikipedia.org/wiki/Actor_model) defines the messages an object can receive, similar to a regular object.
+However, in traditional object-orientated programming, a thread of execution moves from one object to another.  If there are multiple threads, then each object may be accessed concurrently, leading to race conditions or data-integrity problems - and very hard to track bugs.
+
+Actors are different.  Conceptually, each actor has it's own thread of execution, isolated from every other actor in the system.  When one actor sends a message to another actor, the receiver does not execute its method in the caller's thread.  Instead, it places the message on a queue and waits until its own thread is free to process the work.  If the caller would like to access the return value from the method, then it must wait until the receiver has finished processing.
+
+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.
+
+When sending messages to an actor, this just works.
 
-An [actor](https://en.wikipedia.org/wiki/Actor_model) defines the messages an object can receive, similar to a regular object.  However, a normal object if accessed concurrently can have data consistency issues and race conditions leading to hard-to-reproduce bugs.  Actors, however, ensure that, no matter which thread (or fiber) is sending the message, the internal processing of the message (the method definition) is handled sequentially.  This means the internal state of an object is never accessed concurrently, eliminating those issues.  
+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.
 
-[Plumbing::Valve](/lib/plumbing/valve.rb) ensures that all messages received are channelled into a concurrency-safe queue. This allows you to take an existing class and ensures that messages received via its public API are made concurrency-safe.  
+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.
 
-Include the Plumbing::Valve module into your class, define the messages the objects can respond to and set the `Plumbing` configuration to set the desired concurrency model.  Messages themselves are split into two categories: commands and queries.  
+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.
 
-- Commands have no return value so when the message is sent, the caller does not block, the task is called asynchronously and the caller continues immediately
-- Queries return a value so the caller blocks until the actor has returned a value
-- However, if you call a query and pass `ignore_result: true` then the query will not block, although you will not be able to access the return value - this is for commands that do something and then return a result based on that work (which you may or may not be interested in - see Plumbing::Pipe#add_observer)
-- None of the above applies if the `Plumbing mode` is set to `:inline` (which is the default) - in this case, the actor behaves like normal ruby code
+### Inline 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 valve are available in this proxy - so you don't have to worry about callers bypassing the valve's internal context.  
+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 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.  
+### Async actors
 
-Also be aware that if you use valves in one place, you need to use them everywhere - especially if you're using threads or ractors (coming soon).  This is because as the valve sends messages to its collaborators, those calls will be made from within the valve's internal context.  If the collaborators are also valves, the subsequent messages will be handled correctly, if not, data consistency bugs could occur.  
+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.
 
-### Usage 
+### Threaded actprs
+
+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.
+
+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.
+
+(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).
+
+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.
+
+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.
+
+### Usage
 
-[Defining an actor](/spec/examples/valve_spec.rb)
+[Defining an actor](/spec/examples/actor_spec.rb)
 
 ```ruby
   require "plumbing"
-  
+
   class Employee
     attr_reader :name, :job_title
 
-    include Plumbing::Valve
+    include Plumbing::Actor
     query :name, :job_title, :greet_slowly
     command :promote
 
@@ -193,70 +224,40 @@ Also be aware that if you use valves in one place, you need to use them everywhe
       @job_title = "Sales manager"
     end
 
-    def greet_slowly 
+    def greet_slowly
       sleep 0.2
       "H E L L O"
     end
   end
-```
 
-[Acting inline](/spec/examples/valve_spec.rb) with no concurrency
-
-```ruby
-  require "plumbing"
-    
   @person = Employee.start "Alice"
 
-  puts @person.name
-  # => "Alice"
-  puts @person.job_title
-  # => "Sales assistant"
+  await { @person.name }
+  # =>  "Alice"
+  await { @person.job_title }
+  # => "Sales assistant"
 
-  @person.promote
-  # this will block for 0.5 seconds
-  puts @person.job_title
-  # => "Sales manager"
+  # `greet_slowly` is a query so will block until a response is received
+  await { @person.greet_slowly }
+  # =>  "H E L L O"
 
-  @person.greet_slowly 
-  # this will block for 0.2 seconds before returning "H E L L O"
-
-  @person.greet_slowly(ignore_result: true)
-  # this will block for 0.2 seconds (as the mode is :inline) before returning nil
-```
-
-[Using fibers](/spec/examples/valve_spec.rb) with concurrency but no parallelism
-
-```ruby
-  require "plumbing"
-  require "async"
-
-  Plumbing.configure mode: :async 
-  @person = Employee.start "Alice"
-
-  puts @person.name
-  # => "Alice"
-  puts @person.job_title
-  # => "Sales assistant"
+  # 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
   @person.promote
-  # this will return immediately without blocking
-  puts @person.job_title
-  # => "Sales manager" (this will block for 0.5s because #job_title query will not start until the #promote command has completed)
-
-  @person.greet_slowly 
-  # this will block for 0.2 seconds before returning "H E L L O"
-
-  @person.greet_slowly(ignore_result: true)
-  # this will not block and returns nil
+  # this will block, as we wait for the result from #job_title and #job_title will not run until after #promote has completed
+  await { @person.job_title }
+  # => "Sales manager"
 ```
 
 ## Plumbing::Pipe - a composable observer
 
 [Observers](https://ruby-doc.org/3.3.0/stdlibs/observer/Observable.html) in Ruby are a pattern where objects (observers) register their interest in another object (the observable).  This pattern is common throughout programming languages (event listeners in Javascript, the dependency protocol in [Smalltalk](https://en.wikipedia.org/wiki/Smalltalk)).
 
-[Plumbing::Pipe](lib/plumbing/pipe.rb) makes observers "composable".  Instead of simply just registering for notifications from a single observable, we can build sequences of pipes.  These sequences can filter notifications and route them to different listeners, or merge multiple sources into a single stream of notifications.  
+[Plumbing::Pipe](lib/plumbing/pipe.rb) makes observers "composable".  Instead of simply just registering for notifications from a single observable, we can build sequences of pipes.  These sequences can filter notifications and route them to different listeners, or merge multiple sources into a single stream of notifications.
 
-Pipes are implemented as valves, meaning that event notifications can be dispatched asynchronously.  The observer's callback will be triggered from within the pipe's internal context so you should immediately trigger a command on another valve to maintain safety.  
+Pipes are implemented as actors, meaning that event notifications can be dispatched asynchronously.  The observer's callback will be triggered from within the pipe's internal context so you should immediately trigger a command on another actor to maintain safety.
 
 ### Usage
 
@@ -279,7 +280,7 @@ Pipes are implemented as valves, meaning that event notifications can be dispatc
 
   @source = Plumbing::Pipe.start
   @filter = Plumbing::Filter.start source: @source do |event|
-    %w[important urgent].include? event.type 
+    %w[important urgent].include? event.type
   end
   @observer = @filter.add_observer do |event|
     puts event.type
@@ -349,16 +350,16 @@ Pipes are implemented as valves, meaning that event notifications can be dispatc
   require "plumbing"
   require "async"
 
-  Plumbing.configure mode: :async 
+  Plumbing.configure mode: :async
 
-  Sync do 
-    @first_source = Plumbing::Pipe.start 
+  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 
+      %w[one-one two-two].include? event.type
     end
 
     @first_source.notify "one-one"
@@ -370,19 +371,20 @@ Pipes are implemented as valves, meaning that event notifications can be dispatc
 
 ## 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.  Then cast an object into that type, which first tests that the object can respond to those messages and then builds a proxy that responds to just those messages and no others (so no-one can abuse the specific type-casting you have specified).  However, if you take one of these proxies, you can safely re-cast it as another type (as long as the original target object is castable).
+Define an [interface or protocol](https://en.wikipedia.org/wiki/Interface_(object-oriented_programming)) specifying which messages you expect to be able to send.
 
+Then cast an object into that type.  This first tests that the object can respond to those messages and then builds a proxy that responds to those messages (and no others).  However, if you take one of these proxies, you can safely re-cast it as another type (as long as the original target object responds to the correct messages).
 
-### Usage 
+### Usage
 
-Define your interface (Person in this example), then cast your objects (instances of PersonData and CarData).  
+Define your interface (Person in this example), then cast your objects (instances of PersonData and CarData).
 
 [Casting objects as duck-types](/spec/examples/rubber_duck_spec.rb):
 ```ruby
   require "plumbing"
 
-  Person = Plumbing::RubberDuck.define :first_name, :last_name, :email 
-  LikesFood = Plumbing::RubberDuck.define :favourite_food 
+  Person = Plumbing::RubberDuck.define :first_name, :last_name, :email
+  LikesFood = Plumbing::RubberDuck.define :favourite_food
 
   PersonData = Struct.new(:first_name, :last_name, :email, :favourite_food)
   CarData = Struct.new(:make, :model, :colour)
@@ -395,17 +397,54 @@ Define your interface (Person in this example), then cast your objects (instance
   @person = @alice.as Person
   @person.first_name
   # => "Alice"
-  @person.email 
+  @person.email
   # => "alice@example.com"
   @person.favourite_food
   # => NoMethodError - #favourite_food is not part of the Person rubber duck (even though it is part of the underlying PersonData struct)
 
   # Cast our Person into a LikesFood rubber duck
-  @hungry = @person.as LikesFood 
-  @hungry.favourite_food 
+  @hungry = @person.as LikesFood
+  @hungry.favourite_food
   # => "Ice cream"
 ```
 
+You can also use the same `@object.as type` to type-check instances against modules or classes.  This creates a RubberDuck proxy based on the module or class you're casting into.  So the cast will pass if the object responds to the correct messages, even if a strict `.is_a?` test would fail.
+
+```ruby
+  require "plumbing"
+
+  module Person
+    def first_name = @first_name
+
+    def last_name = @last_name
+
+    def email = @email
+  end
+
+  module LikesFood
+    def favourite_food = @favourite_food
+  end
+
+  PersonData = Struct.new(:first_name, :last_name, :email, :favourite_food)
+  CarData = Struct.new(:make, :model, :colour)
+
+  @porsche_911 = CarData.new "Porsche", "911", "black"
+  expect { @porsche_911.as Person }.to raise_error(TypeError)
+
+  @alice = PersonData.new "Alice", "Aardvark", "alice@example.com", "Ice cream"
+
+  @alics.is_a? Person
+  # => false - PersonData does not `include Person`
+  @person = @alice.as Person
+  # This cast is OK because PersonData responds to :first_name, :last_name and :email
+  expect(@person.first_name).to eq "Alice"
+  expect(@person.email).to eq "alice@example.com"
+  expect { @person.favourite_food }.to raise_error(NoMethodError)
+
+  @hungry = @person.as LikesFood
+  expect(@hungry.favourite_food).to eq "Ice cream"
+```
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -418,6 +457,9 @@ Then:
 
 ```ruby
 require 'plumbing'
+
+# Set the mode for your Actors and Pipes
+Plumbing.config mode: :async
 ```
 
 ## Development

data/lib/plumbing/actor/async.rb

@@ -0,0 +1,38 @@
+require "async"
+require "async/semaphore"
+require "timeout"
+
+module Plumbing
+  module Actor
+    class Async
+      attr_reader :target
+
+      def initialize target
+        @target = target
+        @queue = []
+        @semaphore = ::Async::Semaphore.new(1)
+      end
+
+      # Send the message to the target and wrap the result
+      def send_message message_name, *args, &block
+        task = @semaphore.async do
+          @target.send message_name, *args, &block
+        end
+        Result.new(task)
+      end
+
+      Result = Data.define(:task) do
+        def await
+          Timeout.timeout(Plumbing::Actor.timeout) do
+            task.wait
+          end
+        end
+      end
+      private_constant :Result
+    end
+
+    def self.timeout
+      Plumbing.config.timeout
+    end
+  end
+end

data/lib/plumbing/actor/inline.rb

@@ -0,0 +1,22 @@
+module Plumbing
+  module Actor
+    class Inline
+      def initialize target
+        @target = target
+      end
+
+      # Send the message to the target and wrap the result
+      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
+      end
+      private_constant :Result
+    end
+  end
+end

data/lib/plumbing/actor/kernel.rb

@@ -0,0 +1,9 @@
+module Plumbing
+  module Actor
+    ::Kernel.class_eval do
+      def await &block
+        block.call.await
+      end
+    end
+  end
+end

data/lib/plumbing/actor/rails.rb

@@ -0,0 +1,15 @@
+require_relative "threaded"
+
+module Plumbing
+  module Actor
+    class Rails < Threaded
+      protected
+
+      def future(&)
+        Concurrent::Promises.future do
+          Rails.application.executor.wrap(&)
+        end
+      end
+    end
+  end
+end

data/lib/plumbing/actor/threaded.rb

@@ -0,0 +1,62 @@
+require "concurrent/array"
+require "concurrent/mvar"
+require "concurrent/immutable_struct"
+require "concurrent/promises"
+require_relative "transporter"
+
+module Plumbing
+  module Actor
+    class Threaded
+      attr_reader :target
+
+      def initialize target
+        @target = target
+        @queue = Concurrent::Array.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
+        end
+      end
+
+      protected
+
+      def future(&)
+        Concurrent::Promises.future(&)
+      end
+
+      private
+
+      def send_messages
+        future do
+          while (message = @queue.shift)
+            message.call
+          end
+        end
+      end
+
+      class Message < Concurrent::ImmutableStruct.new(:target, :message_name, :packed_args, :unsafe_block, :result)
+        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
+          value = Plumbing::Actor.transporter.unmarshal(*result.take(Plumbing.config.timeout)).first
+          raise value if value.is_a? Exception
+          value
+        end
+      end
+    end
+
+    def self.transporter
+      @transporter ||= Plumbing::Actor::Transporter.new
+    end
+  end
+end

data/lib/plumbing/actor/transporter.rb

@@ -0,0 +1,61 @@
+require "global_id"
+
+module Plumbing
+  module Actor
+    class Transporter
+      def marshal *arguments
+        pack_array arguments
+      end
+
+      def unmarshal *arguments
+        unpack_array arguments
+      end
+
+      private
+
+      def pack argument
+        case argument
+        when GlobalID::Identification then pack_global_id argument
+        when Array then pack_array argument
+        when Hash then pack_hash argument
+        else argument.clone
+        end
+      end
+
+      def pack_array arguments
+        arguments.map { |a| pack a }
+      end
+
+      def pack_hash arguments
+        arguments.transform_values { |v| pack v }
+      end
+
+      def pack_global_id argument
+        argument.to_global_id.to_s
+      end
+
+      def unpack argument
+        case argument
+        when String then unpack_string argument
+        when Array then unpack_array argument
+        when Hash then unpack_hash argument
+        else argument
+        end
+      end
+
+      def unpack_array arguments
+        arguments.map { |a| unpack a }
+      end
+
+      def unpack_hash arguments
+        arguments.to_h do |key, value|
+          [key, unpack(value)]
+        end
+      end
+
+      def unpack_string argument
+        argument.start_with?("gid://") ? GlobalID::Locator.locate(argument) : argument
+      end
+    end
+  end
+end