standard-procedure-plumbing 0.4.5 → 0.4.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14d6355c882a36f026eb602842b5024b58a653d698352239b283cac6703e042f
-  data.tar.gz: 0e3944c06292f6747cff1e816843c9eeb8d3f3969cf46619389745b6a2c3a890
+  metadata.gz: 82a3aa2f2a6718e748faf14e12dcf8df50928cfcdb19bf75641731e38122c694
+  data.tar.gz: d13610908d60830323e6921f77628c73ce9920475086a1475f21323def38f3a3
 SHA512:
-  metadata.gz: ebd0ce6803ce1d06d99eb4941bbdcc0f0f047a5f2fd2fb3df744ae18db948b9ce6bdd093e7ba5048e43417fc3420cce4185d52ee7cc7d092dba5794c4afdad82
-  data.tar.gz: d40d1334d75bcfe44b64dc2f5b8ebc6f8b9299cfce653f1b9264caea3016c215a2fa2285ffff82171b9cea2e46ce34de15dcd68c56a8047775374368c2fb8d95
+  metadata.gz: e54c7820faf040901935c80797d737cc89dd1b6c7da873621361295446b35d2dab4987dee6ee423086a9dc3a7b6fb3ce20f699a5ff92edf1c7673ef071f089f9
+  data.tar.gz: f47b41311a3aa11fc38479d98f0fc11ce1f370f23ceea127ac44462ea7bf148c66d190662dcd05d50f955cab117b9802cd4d8bb639d747a91db8136bcda16e43

data/README.md

@@ -2,509 +2,25 @@
 
 Actors, Observers and Data Pipelines.
 
-## Configuration
+## Usage
 
-The most important configuration setting is the `mode`, which governs how background tasks are handled.
+Start off by [configuring Plumbing](/docs/config.md) and selecting your `mode`.
 
-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).
+## Pipelines
 
-`: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.
+[Data transformations](/docs/pipelines.md) similar to unix pipes.
 
-`: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.
+## Actors
 
-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.
+[Asynchronous, thread-safe, objects](/docs/actors.md).
 
-The `timeout` setting is used when performing queries - it defaults to 30s.
+## Pipes
 
-```ruby
-  require "plumbing"
-  puts Plumbing.config.mode
-  # => :inline
-
-  Plumbing.configure mode: :async, timeout: 10
-
-  puts Plumbing.config.mode
-  # => :async
-```
-
-If you are running a test suite, you can temporarily update the configuration by passing a block.
-
-```ruby
-  require "plumbing"
-  puts Plumbing.config.mode
-  # => :inline
-
-  Plumbing.configure mode: :async do
-    puts Plumbing.config.mode
-    # => :async
-    first_test
-    second_test
-  end
-
-  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.
-
-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.
-
-You can also verify that the output generated is as expected by defining a `post_condition`.
-
-### Usage:
-
-[Building an array using multiple steps with a pre-condition and post-condition](/spec/examples/pipeline_spec.rb)
-
-```ruby
-  require "plumbing"
-  class BuildArray < Plumbing::Pipeline
-    perform :add_first
-    perform :add_second
-    perform :add_third
-
-    pre_condition :must_be_an_array do |input|
-      input.is_a? Array
-    end
-
-    post_condition :must_have_three_elements do |output|
-      output.length == 3
-    end
-
-    private
-
-    def add_first(input) = input << "first"
-
-    def add_second(input) = input << "second"
-
-    def add_third(input) = input << "third"
-  end
-
-  BuildArray.new.call []
-  # => ["first", "second", "third"]
-
-  BuildArray.new.call 1
-  # => Plumbing::PreconditionError("must_be_an_array")
-
-  BuildArray.new.call ["extra element"]
-  # => Plumbing::PostconditionError("must_have_three_elements")
-```
-
-[Validating input parameters with a contract](/spec/examples/pipeline_spec.rb)
-```ruby
-  require "plumbing"
-  require "dry/validation"
-
-  class SayHello < Plumbing::Pipeline
-    validate_with "SayHello::Input"
-    perform :say_hello
-
-    private
-
-    def say_hello input
-      "Hello #{input[:name]} - I will now send a load of annoying marketing messages to #{input[:email]}"
-    end
-
-    class Input < Dry::Validation::Contract
-      params do
-        required(:name).filled(:string)
-        required(:email).filled(:string)
-      end
-      rule :email do
-        key.failure("must be a valid email") unless /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i.match? value
-      end
-    end
-  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
-
-  SayHello.new.call(some: "other data")
-  # => Plumbing::PreConditionError
-```
-
-[Building a pipeline through composition](/spec/examples/pipeline_spec.rb)
-
-```ruby
-  require "plumbing"
-  class ExternalStep < Plumbing::Pipeline
-    perform :add_item_to_array
-
-    private
-
-    def add_item_to_array(input) = input << "external"
-  end
-
-  class BuildSequenceWithExternalStep < Plumbing::Pipeline
-    perform :add_first
-    perform :add_second, using: "ExternalStep"
-    perform :add_third
+[Composable observers](/docs/pipes.md).
 
-    private
+## Rubber ducks
 
-    def add_first(input) = input << "first"
-
-    def add_third(input) = input << "third"
-  end
-
-  BuildSequenceWithExternalStep.new.call([])
-  # => ["first", "external", "third"]
-```
-
-## 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 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 `#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.
-
-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 `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 `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 actors
-
-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 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).
-
-### 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.
-
-### Referencing actors
-
-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
-
-[Defining an actor](/spec/examples/actor_spec.rb)
-
-```ruby
-  require "plumbing"
-
-  class Employee
-    include Plumbing::Actor
-    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"
-    end
-
-    def greet_slowly
-      sleep 0.2
-      "H E L L O"
-    end
-  end
-
-  @person = Employee.start "Alice"
-
-  await { @person.name }
-  # =>  "Alice"
-  await { @person.job_title }
-  # => "Sales assistant"
-
-  # by using `await`, we will block until `greet_slowly` has returned a value
-  await { @person.greet_slowly }
-  # =>  "H E L L O"
-
-  # 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
-  @person.promote
-  # 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"
-```
-
-## 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.
-
-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
-
-[A simple observer](/spec/examples/pipe_spec.rb):
-```ruby
-  require "plumbing"
-
-  @source = Plumbing::Pipe.start
-  @observer = @source.add_observer do |event|
-    puts event.type
-  end
-
-  @source.notify "something_happened", message: "But what was it?"
-  # => "something_happened"
-```
-
-[Simple filtering](/spec/examples/pipe_spec.rb):
-```ruby
-  require "plumbing"
-
-  @source = Plumbing::Pipe.start
-  @filter = Plumbing::Filter.start source: @source do |event|
-    %w[important urgent].include? event.type
-  end
-  @observer = @filter.add_observer do |event|
-    puts event.type
-  end
-
-  @source.notify "important", message: "ALERT! ALERT!"
-  # => "important"
-  @source.notify "unimportant", message: "Nothing to see here"
-  # => <no output>
-```
-
-[Custom filtering](/spec/examples/pipe_spec.rb):
-```ruby
-  require "plumbing"
-  class EveryThirdEvent < Plumbing::CustomFilter
-    def initialize source:
-      super source: source
-      @events = []
-    end
-
-    def received 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
-
-  @source = Plumbing::Pipe.start
-  @filter = EveryThirdEvent.start(source: @source)
-  @observer = @filter.add_observer do |event|
-    puts event.type
-  end
-
-  1.upto 10 do |i|
-    @source.notify i.to_s
-  end
-  # => "3"
-  # => "6"
-  # => "9"
-```
-
-[Joining multiple sources](/spec/examples/pipe_spec.rb):
-```ruby
-  require "plumbing"
-
-  @first_source = Plumbing::Pipe.start
-  @second_source = Plumbing::Pipe.start
-
-  @junction = Plumbing::Junction.start @first_source, @second_source
-
-  @observer = @junction.add_observer do |event|
-    puts event.type
-  end
-
-  @first_source.notify "one"
-  # => "one"
-  @second_source.notify "two"
-  # => "two"
-```
-## 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.  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
-
-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
-
-  PersonData = Struct.new(:first_name, :last_name, :email, :favourite_food)
-  CarData = Struct.new(:make, :model, :colour)
-
-  @porsche_911 = CarData.new "Porsche", "911", "black"
-  @person = @porsche_911.as Person
-  # => Raises a TypeError as CarData does not respond_to #first_name, #last_name, #email
-
-  @alice = PersonData.new "Alice", "Aardvark", "alice@example.com", "Ice cream"
-  @person = @alice.as Person
-  @person.first_name
-  # => "Alice"
-  @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
-  # => "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"
-```
-
-## Testing
-
-As soon as you're working in :async or :threaded mode, you'll find your tests become unpredictable.
-
-To help with this there are some helpers that you can include in your code.
-
-Firstly, you can wait for something to become true.  The `#wait_for` method is added into `Kernel` so it is available everywhere.  It repeatedly executes the given block until a truthy value is returned or the timeout is reached (at which point it raises a Timeout::Error). Note that you still need to use `await` (or call `#value`) to access return values from messages sent to actors.
-
-```ruby
-@target = SomeActor.start
-@subject = SomeOtherActor.start
-
-@subject.do_something_to @target
-
-wait_for do
-  await { @target.was_updated? }
-end
-
-```
-
-Secondly, if you're using RSpec, you can `require "plumbing/spec/become_matchers"` to add some extra expectation matchers.  These matchers use `wait_for` to repeatedly evaluate the given block until it reaches the expected value or times out.  The matchers are `become(value)`, `become_true`, `become_false`, `become_truthy` and `become_falsey`.  Note that you still need to use `await` (or call `#value`) to access return values from messages sent to actors.
-
-```ruby
-@target = SomeActor.start
-@subject = SomeOtherActor.start
-
-@subject.do_something_to @target
-
-expect { @target.was_updated?.value }.to become_true
-
-@employee = Employee.start
-
-expect { @employee.job_title.value }.to become "Sales assistant"
-
-@employee.promote!
-
-expect { @employee.job_title.value }.to become "Manager"
-```
+[Type-safety the ruby way](/docs/rubber_ducks.md).
 
 ## Installation
 
@@ -525,6 +41,8 @@ require 'plumbing'
 Plumbing.config mode: :async
 ```
 
+
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/plumbing/actor/async.rb

@@ -9,20 +9,24 @@ module Plumbing
 
       def initialize target
         @target = target
-        @queue = []
-        @semaphore = ::Async::Semaphore.new(1)
+        @semaphore = ::Async::Semaphore.new(Plumbing.config.max_concurrency)
       end
 
       # Send the message to the target and wrap the result
-      def send_message(message_name, *, **, &)
+      def send_message(message_name, *args, **params, &block)
+        Plumbing.config.logger.debug { "-> #{@target.class}##{message_name}(#{args.inspect}, #{params.inspect})" }
         task = @semaphore.async do
-          @target.send(message_name, *, **, &)
+          Plumbing.config.logger.debug { "---> #{@target.class}##{message_name}(#{args.inspect}, #{params.inspect})" }
+          @target.send(message_name, *args, **params, &block)
         end
+        sleep 0.01
         Result.new(task)
       end
 
       def safely(&)
+        Plumbing.config.logger.debug { "-> #{@target.class}#perform_safely" }
         send_message(:perform_safely, &)
+        sleep 0.01
         nil
       end
 
@@ -32,6 +36,7 @@ module Plumbing
 
       Result = Data.define(:task) do
         def value
+          sleep 0.01
           Timeout.timeout(Plumbing::Actor.timeout) do
             task.wait
           end

data/lib/plumbing/actor/inline.rb

@@ -6,14 +6,19 @@ 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, *args, **params, &)
+        Plumbing.config.logger.debug { "-> #{@target.class}##{message_name}(#{args.inspect}, #{params.inspect})" }
+        Plumbing.config.logger.debug { "---> #{@target.class}##{message_name}(#{args.inspect}, #{params.inspect})" }
+        value = @target.send(message_name, *args, **params, &)
+        Plumbing.config.logger.debug { "===> #{@target.class}##{message_name} => #{value}" }
         Result.new(value)
       rescue => ex
+        Plumbing.config.logger.debug { "!!!! #{@target.class}##{message_name} => #{ex}" }
         Result.new(ex)
       end
 
       def safely(&)
+        Plumbing.config.logger.debug { "-> #{@target.class}#perform_safely" }
         send_message(:perform_safely, &)
         nil
       end

data/lib/plumbing/actor/threaded.rb

@@ -8,8 +8,6 @@ require_relative "transporter"
 module Plumbing
   module Actor
     class Threaded
-      attr_reader :target
-
       def initialize target
         @target = target
         @queue = Concurrent::Array.new
@@ -18,7 +16,7 @@ module Plumbing
 
       # Send the message to the target and wrap the result
       def send_message(message_name, *args, **params, &block)
-        puts "->#{@target.class}##{message_name}(#{args.inspect}, #{params.inspect})\n#{Thread.current.name}" if Plumbing.config.debug
+        Plumbing.config.logger.debug { "-> #{@target.class}##{message_name}(#{args.inspect}, #{params.inspect})\n#{Thread.current.name}" }
         Message.new(@target, message_name, Plumbing::Actor.transporter.marshal(*args), Plumbing::Actor.transporter.marshal(params).first, block, Concurrent::MVar.new).tap do |message|
           @queue << message
           send_messages
@@ -26,6 +24,7 @@ module Plumbing
       end
 
       def safely(&)
+        Plumbing.config.logger.debug { "-> #{@target.class}#perform_safely\n#{Thread.current.name}" }
         send_message(:perform_safely, &)
         nil
       end
@@ -58,13 +57,13 @@ module Plumbing
         def call
           args = Plumbing::Actor.transporter.unmarshal(*packed_args)
           params = Plumbing::Actor.transporter.unmarshal(packed_params)
-          puts "=> #{target.class}##{message_name}(#{args.first.inspect}, #{params.first.inspect}, &#{!unsafe_block.nil?})\n#{Thread.current.name}" if Plumbing.config.debug
+          Plumbing.config.logger.debug { "---> #{target.class}##{message_name}(#{args.first.inspect}, #{params.first.inspect}, &#{!unsafe_block.nil?})\n#{Thread.current.name}" }
           value = target.send message_name, *args, **params.first, &unsafe_block
+          Plumbing.config.logger.debug { "===> #{target.class}##{message_name} => #{value}\n#{Thread.current.name}" }
 
           result.put Plumbing::Actor.transporter.marshal(value)
         rescue => ex
-          puts ex
-          puts ex.backtrace
+          Plumbing.config.logger.debug { "!!!! #{target.class}##{message_name} => #{ex}\n#{Thread.current.name}" }
           result.put ex
         end
 

data/lib/plumbing/actor.rb

@@ -86,7 +86,7 @@ module Plumbing
       instance_eval(&)
       nil
     rescue => ex
-      puts ex
+      Plumbing.config.logger.error { "!!!! #{self.class}#perform_safely => #{ex}" }
       nil
     end
   end

data/lib/plumbing/config.rb

@@ -1,16 +1,7 @@
+require "logger"
+
 # Pipes, pipelines, actors and rubber ducks
 module Plumbing
-  Config = Data.define :mode, :actor_proxy_classes, :timeout, :debug do
-    def actor_proxy_class_for target_class
-      actor_proxy_classes[target_class]
-    end
-
-    def register_actor_proxy_class_for target_class, proxy_class
-      actor_proxy_classes[target_class] = proxy_class
-    end
-  end
-  private_constant :Config
-
   # Access the current configuration
   # @return [Config]
   def self.config
@@ -45,7 +36,23 @@ module Plumbing
   private_class_method :set_configuration_and_yield
 
   def self.configs
-    @configs ||= [Config.new(mode: :inline, timeout: 30, actor_proxy_classes: {}, debug: false)]
+    @configs ||= [Config.new(mode: :inline, timeout: 30, actor_proxy_classes: {}, max_concurrency: 12, logger: logger)]
   end
   private_class_method :configs
+
+  def self.logger
+    @logger = Logger.new($stdout, level: Logger::INFO)
+  end
+  private_class_method :logger
+
+  Config = Data.define :mode, :actor_proxy_classes, :timeout, :max_concurrency, :logger do
+    def actor_proxy_class_for target_class
+      actor_proxy_classes[target_class]
+    end
+
+    def register_actor_proxy_class_for target_class, proxy_class
+      actor_proxy_classes[target_class] = proxy_class
+    end
+  end
+  private_constant :Config
 end

data/lib/plumbing/{custom_filter.rb → pipe/custom_filter.rb}

@@ -1,15 +1,17 @@
 module Plumbing
   # A pipe that can be subclassed to filter events from a source pipe
-  class CustomFilter < Pipe
+  class Pipe::CustomFilter < Pipe
     # Chain this pipe to the source pipe
     # @param source [Plumbing::Observable] the source from which to receive and filter events
     def initialize source:
       super()
-      source.as(Observable).add_observer { |event| received event }
+      source.as(Observable).add_observer do |event_name, data|
+        received event_name, data
+      end
     end
 
     protected
 
-    def received(event) = raise NoMethodError.new("Subclass should define #received")
+    def received(event_name, data) = raise NoMethodError.new("Subclass should define #received")
   end
 end

data/lib/plumbing/{filter.rb → pipe/filter.rb}

@@ -1,7 +1,7 @@
 require_relative "custom_filter"
 module Plumbing
   # A pipe that filters events from a source pipe
-  class Filter < CustomFilter
+  class Pipe::Filter < Pipe::CustomFilter
     # Chain this pipe to the source pipe
     # @param source [Plumbing::Observable] the source from which to receive and filter events
     # @param &accepts [Block] a block that returns a boolean value - true to accept the event, false to reject it
@@ -14,9 +14,10 @@ module Plumbing
 
     protected
 
-    def received(event)
-      return nil unless @accepts.call event
-      dispatch event
+    def received(event_name, data)
+      safely do
+        notify event_name, **data if @accepts.call(event_name, data)
+      end
     end
   end
 end

data/lib/plumbing/{junction.rb → pipe/junction.rb}

@@ -1,6 +1,6 @@
 module Plumbing
   # A pipe that filters events from a source pipe
-  class Junction < Pipe
+  class Pipe::Junction < Pipe
     # Chain multiple sources to this pipe
     # @param sources [Array<Plumbing::Observable>] the sources which will be joined and relayed
     def initialize *sources
@@ -11,9 +11,9 @@ module Plumbing
     private
 
     def add source
-      source.as(Observable).add_observer do |event|
+      source.as(Observable).add_observer do |event_name, **data|
         safely do
-          dispatch event
+          notify event_name, **data
         end
       end
     end

data/lib/plumbing/pipe.rb

@@ -3,21 +3,19 @@ module Plumbing
   class Pipe
     include Plumbing::Actor
 
-    async :notify, :<<, :remove_observer, :add_observer, :is_observer?, :shutdown
+    async :notify, :remove_observer, :add_observer, :is_observer?, :shutdown
 
-    # Push an event into the pipe
-    # @param event [Plumbing::Event] the event to push into the pipe
-    def << event
-      raise Plumbing::InvalidEvent.new event unless event.is_a? Plumbing::Event
-      dispatch event
-    end
-
-    # A shortcut to creating and then pushing an event
-    # @param event_type [String] representing the type of event this is
+    # Notify observers about an event
+    # @param event_name [String] representing the type of event this is
     # @param data [Hash] representing the event-specific data to be passed to the observers
-    def notify event_type, data = nil
-      Event.new(type: event_type, data: data).tap do |event|
-        self << event
+    def notify event_name, **data
+      Plumbing.config.logger.debug { "-> #{self.class}#notify #{event_name}" }
+      observers.each do |observer|
+        Plumbing.config.logger.debug { "===> #{self.class}#dispatch #{event_name}(#{data}) to #{observer}" }
+        observer.call event_name, data
+      rescue => ex
+        Plumbing.config.logger.error { "!!!! #{self.class}#dispatch #{event_name} => #{ex}" }
+        ex
       end
     end
 
@@ -52,23 +50,14 @@ module Plumbing
       stop
     end
 
-    protected
-
-    # Dispatch an event to all observers
-    # @param event [Plumbing::Event]
-    # Enumerates all observers and `calls` them with this event
-    # Discards any errors raised by the observer so that all observers will be successfully notified
-    def dispatch event
-      observers.each do |observer|
-        observer.call event
-      rescue => ex
-        puts ex
-        ex
-      end
-    end
+    private
 
     def observers
       @observers ||= []
     end
+
+    require_relative "pipe/filter"
+    require_relative "pipe/junction"
+
   end
 end

data/lib/plumbing/spec/modes.rb

@@ -0,0 +1,14 @@
+module Plumbing
+  module Spec
+    def self.modes(inline: true, async: true, threaded: true, &)
+      Plumbing.configure(mode: :inline, &) if inline
+      Sync { Plumbing.configure(mode: :async, &) } if async
+      Plumbing.configure(mode: thread_mode, &) if threaded
+    end
+
+    def self.thread_mode
+      defined?(::Rails) ? :threaded_rails : :threaded
+    end
+    private_class_method :thread_mode
+  end
+end

data/lib/plumbing/version.rb

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

data/lib/plumbing.rb

@@ -6,10 +6,7 @@ module Plumbing
   require_relative "plumbing/rubber_duck"
   require_relative "plumbing/types"
   require_relative "plumbing/error"
-  require_relative "plumbing/event"
   require_relative "plumbing/pipe"
-  require_relative "plumbing/filter"
-  require_relative "plumbing/junction"
   require_relative "plumbing/pipeline"
   require_relative "plumbing/version"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: standard-procedure-plumbing
 version: !ruby/object:Gem::Version
-  version: 0.4.5
+  version: 0.4.6
 platform: ruby
 authors:
 - Rahoul Baruah
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-18 00:00:00.000000000 Z
+date: 2024-09-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: globalid
@@ -43,12 +43,11 @@ files:
 - lib/plumbing/actor/threaded.rb
 - lib/plumbing/actor/transporter.rb
 - lib/plumbing/config.rb
-- lib/plumbing/custom_filter.rb
 - lib/plumbing/error.rb
-- lib/plumbing/event.rb
-- lib/plumbing/filter.rb
-- lib/plumbing/junction.rb
 - lib/plumbing/pipe.rb
+- lib/plumbing/pipe/custom_filter.rb
+- lib/plumbing/pipe/filter.rb
+- lib/plumbing/pipe/junction.rb
 - lib/plumbing/pipeline.rb
 - lib/plumbing/pipeline/contracts.rb
 - lib/plumbing/pipeline/operations.rb
@@ -57,6 +56,7 @@ files:
 - lib/plumbing/rubber_duck/object.rb
 - lib/plumbing/rubber_duck/proxy.rb
 - lib/plumbing/spec/become_matchers.rb
+- lib/plumbing/spec/modes.rb
 - lib/plumbing/types.rb
 - lib/plumbing/version.rb
 homepage: https://github.com/standard-procedure/plumbing

data/lib/plumbing/event.rb

@@ -1,4 +0,0 @@
-module Plumbing
-  # An immutable data structure representing an Event
-  Event = Data.define :type, :data
-end