concurrent_rails 0.1.7 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe2277deed1f15f3c47a332667db0b85bbfb0d39d58bcb6539fa0d15d843c55d
-  data.tar.gz: 0e347f69da65b60fcbdb63a04cdcb3bac782ba01b6e543db93428ff4c2bdbdc0
+  metadata.gz: fd75cf15aa7d7d0354bea478936bde3967d20a8e38daabff9e3fddf5c11bd5b6
+  data.tar.gz: 8c5faee065ed6de8bb7fedf2b29c3bc371792f579c7a00e6195d4b4e18ee0a29
 SHA512:
-  metadata.gz: '079c165494e1eea8ae9c98fe89031c87408808527a3f90eda3c5c5d87598bfb5932b0285acaa99d4e5e714a1012af3676bc16fc9b5929268ff26640b90f4b191'
-  data.tar.gz: 97944d3f3db134d08eb894f6f3211a705cb080ec4d4ec331657c94940fd08a08c4f1f46859d430f3c2e5097a1cc54d7de322e9f39a0fcc48de78d49982cd26e8
+  metadata.gz: 649cf84ed43e2b6c7e70f89840a3091fefea3ade9df62af7d50ee7e7ef309af24729912bd9dbc5adc4112da953d3964e8b0ac4d41b36d3eb256edd73813c979f
+  data.tar.gz: 818ffd9287980e87473f9445b0424a5a006271b3ce4a070a4bd4b6fb08c4405576eff466e4def1c5ddce032614600f3d9a830951d20cfbb29823b7667545780a

data/README.md

@@ -2,8 +2,7 @@
 
 ![status](https://github.com/luizkowalski/concurrent_rails/actions/workflows/ruby.yml/badge.svg?branch=master)
 
-Multithread is hard. [concurrent-ruby](https://github.com/ruby-concurrency/concurrent-ruby) did an amazing job
-implementing the concepts of multithread in the Ruby world. The problem is that Rails doesn't play nice with it. Rails have a complex way of managing threads called Executor and concurrent-ruby (most specifically, [Future](https://github.com/ruby-concurrency/concurrent-ruby/blob/master/docs-source/future.md)) does not work seamlessly with it.
+Multithread is hard. [concurrent-ruby](https://github.com/ruby-concurrency/concurrent-ruby) did an amazing job implementing the concepts of multithread in the Ruby world. The problem is that Rails doesn't play nice with it. Rails have a complex way of managing threads called Executor and concurrent-ruby (most specifically, [Future](https://github.com/ruby-concurrency/concurrent-ruby/blob/master/docs-source/future.md)) does not work seamlessly with it.
 
 The goal of this gem is to provide a simple library that allows the developer to work with Futures without having to care about Rails's Executor and the whole pack of problems that come with it: autoload, thread pools, active record connections, etc.
 
@@ -13,8 +12,7 @@ This library provides three classes that will help you run tasks in parallel: `C
 
 ### Promises
 
-`Promises` is the recommended way from `concurrent-ruby` to create `Future`s as `Concurrent::Future` will be deprecated at some point.
-Similar to other classes, all you have to do is call `.future` helper and pass a block:
+`Promises` is the recommended way from `concurrent-ruby` to create `Future`s as `Concurrent::Future` will be deprecated at some point. All you have to do is call `#future` and pass a block to be executed asynchronously:
 
 ```ruby
 irb(main):001:0> future = ConcurrentRails::Promises.future(5) { |v| sleep(v); 42 }
@@ -40,9 +38,52 @@ irb(main):002:0> future.value
 => 84
 ```
 
-### Future
+### Delayed futures
 
-`ConcurrentRails::Future` will execute your code in a separated thread and you can check the progress of it whenever you need it. When the task is ready, you can access the result with `#result` function:
+Delayed future is a future that is enqueued but not run until `#touch` or any other method that requires a resolution is called.
+
+```ruby
+irb(main):002:0> delay = ConcurrentRails::Promises.delay { 42 }
+=> #<ConcurrentRails::Promises:0x00007f8b55333d48 @executor=:io, @instan...
+
+irb(main):003:0> delay.state
+=> :pending
+
+irb(main):004:0> delay.touch
+=> #<Concurrent::Promises::Future:0x00007f8b553325b0 pending>
+
+irb(main):005:0> delay.state
+=> :fulfilled
+
+irb(main):006:0> delay.value
+=> 42
+```
+
+Three methods will trigger a resolution: `#touch`, `#value` and `#wait`: `#touch` will simply trigger the execution but won't block the main thread, while `#wait` and `#value` will block the main thread until a resolution is given.
+
+### Callbacks
+
+Delayed and regular futures can set a callback to be executed after the resolution of the future. There are three different callbacks:
+
+* `on_resolution`: runs after the future is resolved and yields three parameters to the callback in the following order: `true/false` for future's fulfillment, `value` as the result of the future execution, and `reason`, that will be `nil` if the future fulfilled or the error that the future triggered.
+
+* `on_fulfillment`: runs after the future is fulfilled and yields `value` to the callback
+
+* `on_rejection`: runs after the future is rejected and yields the `error` to the callback
+
+```ruby
+delay = ConcurrentRails::Promises.delay { complex_find_user_query }.
+        on_fulfillment { |user| user.update!(name: 'John Doe') }.
+        on_rejection { |reason| log_error(reason) }
+
+delay.touch
+```
+
+All of these callbacks have a bang version (e.g. `on_fulfillment!`). The bang version will execute the callback on the same thread pool that was initially set up and the version without bang will run asynchronously on a different executor.
+
+### (Deprecated) Future
+
+`ConcurrentRails::Future` will execute your code in a separate thread and you can check the progress of it whenever you need it. When the task is ready, you can access the result with `#result` function:
 
 ```ruby
 irb(main):001:0> future = ConcurrentRails::Future.new do
@@ -81,7 +122,7 @@ irb(main):005:0> future.reason
 => #<ZeroDivisionError: divided by 0>
 ```
 
-### Multi
+### (Deprecated) Multi
 
 `ConcurrentRails::Multi` will let you execute multiple tasks in parallel and aggregate the results of each task when they are done. `Multi` accepts an undefined number of `Proc`s.
 
@@ -132,6 +173,39 @@ irb(main):007:0> multi.errors
 
 It is worth mention that a failed proc will return `nil`.
 
+## Testing
+If you are using RSpec, you will notice that it might not play well with threads. ActiveRecord opens a database connection for every thread and since RSpec tests are wrapped in a transaction, by the time your promise tries to access something on the database, for example, a user, gems like Database Cleaner probably already triggered and deleted the user, resulting in `ActiveRecord::RecordNotFound` errors. You have a couple of solutions like disable transactional fixtures if you are using it or update the Database Cleaner strategy (that will result in much slower tests).
+Since none of these solutions were satisfactory to me, I created `ConcurrentRails::Testing` with two strategies: `immediate` and `fake`. When you wrap a Promise's `future` with `immediate`, the executor gets replaced from `:io` to `:immediate`. It still returns a promise anyway. This is not the case with `fake` strategy: it executes the task outside the `ConcurrentRails` engine and returns whatever `.value` would return:
+
+`immediate` strategy:
+```ruby
+irb(main):001:1* result = ConcurrentRails::Testing.immediate do
+irb(main):002:1*       ConcurrentRails::Promises.future { 42 }
+irb(main):003:0> end
+=>
+#<ConcurrentRails::Promises:0x000000013e5fc870 
+...
+irb(main):004:0> result.class
+=> ConcurrentRails::Promises # <-- Still a `ConcurrentRails::Promises` class
+irb(main):005:0> result.executor
+=> :immediate # <-- default executor (:io) gets replaced
+```
+
+`fake` strategy:
+
+```ruby
+irb(main):001:1* result = ConcurrentRails::Testing.fake do
+irb(main):002:1*       ConcurrentRails::Promises.future { 42 }
+irb(main):003:0> end
+=> 42 # <-- yields the task but does not return a Promise
+irb(main):004:0> result.class
+=> Integer
+```
+
+You can also set the stragegy globally using `ConcurrentRails::Testing.fake!` or `ConcurrentRails::Testing.immediate!`
+
+## Further reading
+
 For more information on how Futures work and how Rails handle multithread check these links:
 
 [Future documentation](https://github.com/ruby-concurrency/concurrent-ruby/blob/master/docs-source/future.md)
@@ -143,19 +217,19 @@ For more information on how Futures work and how Rails handle multithread check
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'concurrent_rails', '~> 0.1.7'
+gem 'concurrent_rails', '~> 0.2.1'
 ```
 
 And then execute:
 
 ```bash
-$ bundle
+bundle
 ```
 
 Or install it yourself as:
 
 ```bash
-$ gem install concurrent_rails
+gem install concurrent_rails
 ```
 
 ## Contributing

data/lib/concurrent_rails/delay_adapter.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ConcurrentRails::DelayAdapter
+  extend ActiveSupport::Concern
+
+  class_methods do
+    def delay(*args, &task)
+      delay_on(:io, *args, &task)
+    end
+
+    def delay_on(executor, *args, &task)
+      new(executor).delay_on_rails(*args, &task)
+    end
+  end
+
+  def delay_on_rails(*args, &task)
+    @instance = rails_wrapped { delay_on(executor, *args, &task) }
+
+    self
+  end
+end

data/lib/concurrent_rails/future.rb

@@ -1,42 +1,47 @@
 # frozen_string_literal: true
 
-module ConcurrentRails
-  class Future
-    extend Forwardable
-
-    def initialize(executor: :fast, &block)
-      @executor = executor
-      @future   = run_on_rails(block)
-    end
+class ConcurrentRails::Future
+  def initialize(executor: :io, &block)
+    @executor = executor
+    @future   = run_on_rails(block)
+    ActiveSupport::Deprecation.warn('ConcurrentRails::Future is deprecated. See README for details')
+  end
 
-    def execute
-      future.execute
+  def execute
+    future.execute
 
-      self
-    end
+    self
+  end
 
-    %i[value value!].each do |method_name|
-      define_method method_name do
-        Rails.application.executor.wrap do
-          ActiveSupport::Dependencies.interlock.permit_concurrent_loads do
-            future.__send__(method_name)
-          end
-        end
+  %i[value value!].each do |method_name|
+    define_method method_name do
+      permit_concurrent_loads do
+        future.__send__(method_name)
       end
     end
+  end
 
-    def_delegators :@future, :state, :reason, :rejected?, :complete?, :add_observer
+  delegate :state, :reason, :rejected?, :complete?, :add_observer, to: :future
 
-    private
+  private
 
-    def run_on_rails(block)
-      @future = Rails.application.executor.wrap do
-        Concurrent::Future.new(executor: executor) do
-          Rails.application.executor.wrap(&block)
-        end
+  def run_on_rails(block)
+    @future = rails_wrapped do
+      Concurrent::Future.new(executor: executor) do
+        rails_wrapped(&block)
       end
     end
+  end
 
-    attr_reader :executor, :future
+  def rails_wrapped(&block)
+    Rails.application.executor.wrap(&block)
   end
+
+  def permit_concurrent_loads(&block)
+    rails_wrapped do
+      ActiveSupport::Dependencies.interlock.permit_concurrent_loads(&block)
+    end
+  end
+
+  attr_reader :executor, :future
 end

data/lib/concurrent_rails/future_adapter.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ConcurrentRails::FutureAdapter
+  extend ActiveSupport::Concern
+
+  class_methods do
+    def future(*args, &task)
+      future_on(:io, *args, &task)
+    end
+
+    def future_on(executor, *args, &task)
+      new(executor).future_on_rails(*args, &task)
+    end
+  end
+
+  def future_on_rails(*args, &task)
+    @instance = rails_wrapped { future_on(executor, *args, &task) }
+
+    self
+  end
+end

data/lib/concurrent_rails/multi.rb

@@ -1,53 +1,49 @@
 # frozen_string_literal: true
 
-module ConcurrentRails
-  class Multi
-    def self.enqueue(*actions, executor: :io)
-      unless actions.all? { |action| action.is_a?(Proc) }
-        raise ArgumentError, '#enqueue accepts `Proc`s only'
-      end
-
-      new(actions, executor).enqueue
-    end
+class ConcurrentRails::Multi
+  def self.enqueue(*actions, executor: :io)
+    raise ArgumentError, '#enqueue accepts `Proc`s only' unless actions.all?(Proc)
 
-    def initialize(actions, executor)
-      @actions    = actions
-      @executor   = executor
-      @exceptions = Concurrent::Array.new
-    end
+    new(actions, executor).enqueue
+  end
 
-    def enqueue
-      @futures = actions.map do |action|
-        f = ConcurrentRails::Future.new(executor: executor, &action)
-        f.add_observer(self)
-        f.execute
-      end
+  def initialize(actions, executor)
+    @actions    = actions
+    @executor   = executor
+    @exceptions = Concurrent::Array.new
+  end
 
-      self
+  def enqueue
+    @futures = actions.map do |action|
+      f = ConcurrentRails::Future.new(executor: executor, &action)
+      f.add_observer(self)
+      f.execute
     end
 
-    def compute
-      futures.map(&:value)
-    end
+    self
+  end
 
-    def compute!
-      futures.map(&:value!)
-    end
+  def compute
+    futures.map(&:value)
+  end
 
-    def complete?
-      futures.all?(&:complete?)
-    end
+  def compute!
+    futures.map(&:value!)
+  end
 
-    def errors
-      @exceptions
-    end
+  def complete?
+    futures.all?(&:complete?)
+  end
 
-    private
+  def errors
+    @exceptions
+  end
 
-    def update(_time, _value, reason)
-      @exceptions << reason if reason
-    end
+  private
 
-    attr_reader :actions, :futures, :exceptions, :executor
+  def update(_time, _value, reason)
+    @exceptions << reason if reason
   end
+
+  attr_reader :actions, :futures, :exceptions, :executor
 end

data/lib/concurrent_rails/promises.rb

@@ -1,58 +1,81 @@
 # frozen_string_literal: true
 
-module ConcurrentRails
-  class Promises
-    extend Forwardable
-    include Concurrent::Promises::FactoryMethods
-
-    class << self
-      def future(*args, &task)
-        future_on(:fast, *args, &task)
-      end
+require 'concurrent_rails/future_adapter'
+require 'concurrent_rails/delay_adapter'
+
+class ConcurrentRails::Promises
+  include Concurrent::Promises::FactoryMethods
+  include ConcurrentRails::DelayAdapter
+  include ConcurrentRails::FutureAdapter
+
+  def initialize(executor)
+    @executor = executor
+  end
 
-      def future_on(executor, *args, &task)
-        new.with_rails(executor, *args, &task)
+  %i[value value!].each do |method_name|
+    define_method(method_name) do |timeout = nil, timeout_value = nil|
+      permit_concurrent_loads do
+        instance.public_send(method_name, timeout, timeout_value)
       end
     end
+  end
 
-    def then(*args, &task)
-      @future_instance = Rails.application.executor.wrap do
-        future_instance.then(*args, &task)
+  %i[then chain].each do |chainable|
+    define_method(chainable) do |*args, &task|
+      method = "#{chainable}_on"
+      @instance = rails_wrapped do
+        instance.public_send(method, executor, *args, &task)
       end
 
       self
     end
+  end
 
-    def chain(*args, &task)
-      Rails.application.executor.wrap do
-        future_instance.chain(*args, &task)
-      end
+  def touch
+    @instance = rails_wrapped { instance.touch }
 
-      self
-    end
+    self
+  end
+
+  def wait(timeout = nil)
+    result = permit_concurrent_loads { instance.__send__(:wait_until_resolved, timeout) }
 
-    %i[value value!].each do |method_name|
-      define_method method_name do |timeout = nil, timeout_value = nil|
-        Rails.application.executor.wrap do
-          ActiveSupport::Dependencies.interlock.permit_concurrent_loads do
-            future_instance.__send__(method_name, timeout, timeout_value)
-          end
-        end
+    timeout ? result : self
+  end
+
+  %i[on_fulfillment on_rejection on_resolution].each do |method|
+    define_method(method) do |*args, &callback_task|
+      rails_wrapped do
+        @instance = instance.__send__("#{method}_using", executor, *args, &callback_task)
       end
+
+      self
     end
 
-    def with_rails(executor, *args, &task)
-      @future_instance = Rails.application.executor.wrap do
-        future_on(executor, *args, &task)
+    define_method("#{method}!") do |*args, &callback_task|
+      rails_wrapped do
+        @instance = instance.__send__(:add_callback, "callback_#{method}", args, callback_task)
       end
 
       self
     end
+  end
 
-    def_delegators :@future_instance, :state, :reason, :rejected?, :resolved?
+  delegate :state, :reason, :rejected?, :resolved?, :fulfilled?, to: :instance
 
-    private
+  attr_reader :executor
 
-    attr_reader :future_instance
+  private
+
+  def rails_wrapped(&block)
+    Rails.application.executor.wrap(&block)
   end
+
+  def permit_concurrent_loads(&block)
+    rails_wrapped do
+      ActiveSupport::Dependencies.interlock.permit_concurrent_loads(&block)
+    end
+  end
+
+  attr_reader :instance
 end

data/lib/concurrent_rails/railtie.rb

@@ -1,6 +1,4 @@
 # frozen_string_literal: true
 
-module ConcurrentRails
-  class Railtie < ::Rails::Railtie
-  end
+class ConcurrentRails::Railtie < ::Rails::Railtie
 end

data/lib/concurrent_rails/testing.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+class ConcurrentRails::Testing
+  class << self
+    attr_reader :execution_mode
+
+    %w[immediate fake real].each do |test_mode|
+      define_method(test_mode) do |&task|
+        @execution_mode = test_mode
+        result          = task.call
+        @execution_mode = :real
+
+        result
+      end
+
+      define_method("#{test_mode}!") do
+        @execution_mode = test_mode
+      end
+
+      define_method("#{test_mode}?") do
+        execution_mode == test_mode
+      end
+    end
+  end
+
+  module TestingFuture
+    def future(*args, &task)
+      if ConcurrentRails::Testing.immediate?
+        future_on(:immediate, *args, &task)
+      elsif ConcurrentRails::Testing.fake?
+        yield
+      else
+        super
+      end
+    end
+  end
+
+  ConcurrentRails::Promises.extend(TestingFuture)
+end

data/lib/concurrent_rails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ConcurrentRails
-  VERSION = '0.1.7'
+  VERSION = '0.3.0'
 end

data/lib/concurrent_rails.rb

@@ -4,7 +4,5 @@ require 'concurrent_rails/future'
 require 'concurrent_rails/multi'
 require 'concurrent_rails/promises'
 require 'concurrent_rails/railtie'
+require 'concurrent_rails/testing'
 require 'concurrent_rails/version'
-
-module ConcurrentRails
-end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: concurrent_rails
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.3.0
 platform: ruby
 authors:
 - Luiz Eduardo Kowalski
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-05-04 00:00:00.000000000 Z
+date: 2021-11-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: minitest-reporters
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -38,6 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop-minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.12'
 - !ruby/object:Gem::Dependency
   name: rubocop-performance
   requirement: !ruby/object:Gem::Requirement
@@ -63,12 +91,14 @@ files:
 - README.md
 - Rakefile
 - lib/concurrent_rails.rb
+- lib/concurrent_rails/delay_adapter.rb
 - lib/concurrent_rails/future.rb
+- lib/concurrent_rails/future_adapter.rb
 - lib/concurrent_rails/multi.rb
 - lib/concurrent_rails/promises.rb
 - lib/concurrent_rails/railtie.rb
+- lib/concurrent_rails/testing.rb
 - lib/concurrent_rails/version.rb
-- lib/tasks/concurrent_rails_tasks.rake
 homepage: https://github.com/luizkowalski/concurrent_rails
 licenses:
 - MIT
@@ -91,7 +121,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.2.31
 signing_key:
 specification_version: 4
 summary: Multithread is hard

data/lib/tasks/concurrent_rails_tasks.rake

@@ -1,5 +0,0 @@
-# frozen_string_literal: true
-# desc "Explaining what the task does"
-# task :concurrent_rails do
-#   # Task goes here
-# end