async_futures 0.1.2

data/lib/async_futures/ractor_executor.rb

@@ -0,0 +1,353 @@
+# frozen_string_literal: true
+
+# :nocov:
+# The Ractor API was different before version 4.x of Ruby.
+if /^3\./ === RUBY_VERSION
+  raise LoadError.new("'async_futures/ractor_executor' is not supported in Ruby version '#{RUBY_VERSION}'")
+end
+
+# :nocov:
+
+require_relative 'executor'
+
+require 'etc'
+require 'set' # rubocop:disable Lint/RedundantRequireStatement
+
+module AsyncFutures
+  # `Executor` implementation based on `Thread` primitives
+  # that uses a pool of up to `max_workers` to execute calls concurrently.
+  #
+  # `RactorExecutor` specific submission considerations:
+  #
+  # For `RactorExecutor` the tasks are never run immediately upon submission.
+  # They are placed into a work queue
+  # to be picked up later by worker threads.
+  #
+  # This does _not_ guarantee
+  # that any particular task will be run concurrently
+  # with any other particular task;
+  # that is dependent on how many worker threads and tasks there are
+  # at any given point in time.
+  class RactorExecutor # rubocop:disable Metrics/ClassLength
+    include Executor
+
+    # Create a new `RactorExecutor`.
+    #
+    # Uses a pool of up to `max_workers`
+    # to execute tasks concurrently.
+    # If no value is given for `max_workers`
+    # it will default to `[32, Etc.nprocessors + 4].min`.
+    # Workers are spawned lazily as needed
+    # when tasks are added to the work queue.
+    #
+    # The parameter `worker_name_prefix` can be used
+    # to optionally add a prefix to generated `Thread` names.
+    #
+    # If the `move_result` keyword argument is `true`,
+    # results from worker ractors will be moved instead of copied.
+    # Moving is faster than copying,
+    # but less safe
+    # if the worker ractor keeps the values around for some reason
+    # (in a cache, for example).
+    # If you aren't doing something like caching inside workers
+    # you are probably safe to set this to `true`.
+    #
+    # If the `move_args` keyword argument is `true`,
+    # `args` and `kwargs` will be moved instead of copied
+    # from the submitting ractor to the worker ractors.
+    # Moving is faster than copying,
+    # but is even less safe than `move_result`
+    # because the submitting ractor
+    # is more likely to have kept references to the submitted values.
+    # You should only set this to `true`
+    # if you are absolutely certain that submitted values
+    # have no remaining references in the submitting ractor
+    # otherwise the submitting ractor will error when accessing them later.
+    def initialize( # rubocop:disable Metrics/AbcSize,Metrics/ParameterLists
+      max_workers: nil,
+      worker_name_prefix: nil,
+      move_result: false,
+      move_args: false,
+      make_args_shareable: false,
+      copy_args: false
+    )
+      if copy_args && !make_args_shareable
+        raise ArgumentError.new('`copy_args` cannot be true unless `make_args_shareable` is also true')
+      end
+
+      @max_workers = (max_workers || [32, Etc.nprocessors + 4].min).to_i
+      @worker_name_prefix = worker_name_prefix
+
+      # This value is passed into worker Ractors.
+      # If the caller passed something not shareable,
+      # it would error when we spawn workers later.
+      # Boolean values are always safely shareable
+      # and since we only care about the truthiness of this value
+      # double negation makes sense here.
+      @move_result = !!move_result # rubocop:disable Style/DoubleNegation
+
+      @move_args = move_args
+      @make_args_shareable = make_args_shareable
+      @copy_args = copy_args
+      @mutex = Thread::Mutex.new
+      @condition = Thread::ConditionVariable.new
+      @tasks = Thread::Queue.new
+      @worker_tasks_ports = Thread::Queue.new
+
+      # All private variables after this point
+      # require synchronization to safely interact with.
+      @results_ports = {}
+      @worker_to_task_port_map = ObjectSpace::WeakKeyMap.new
+      @futures = {}
+
+      @pool = Set.new
+      @worker_count = 0
+
+      @task_feeder = nil
+      @result_feeder = nil
+
+      # The inter-thread communication between these is necessary for shutdown,
+      # so even if nothing is submitted, we still need these to exist for now.
+      maybe_spawn_task_feeder
+      maybe_spawn_result_feeder
+
+      at_exit { shutdown(wait: false) }
+    end
+
+    # Asynchronously submit a task for execution.
+    #
+    # See `AsyncFutures::Executor.submit` method for full documentation.
+    def submit(*args, **kwargs, &block)
+      raise ArgumentError.new('No block given') unless block
+
+      Future.new.tap do |future|
+        # Attempt to make everything shareable upon submit
+        # so that if making shareable would raise an exception
+        # the caller can know immediately
+        # that a given value won't work.
+        # Otherwise the errors could easily get swallowed in a background thread
+        # and the caller would never know.
+        sh_block = Ractor.shareable_proc(&block)
+        sh_args = @make_args_shareable ? Ractor.make_shareable(args, copy: @copy_args) : args
+        sh_kwargs = @make_args_shareable ? Ractor.make_shareable(kwargs, copy: @copy_args) : kwargs
+        ractor_task = [future, sh_block, sh_args, sh_kwargs]
+
+        @tasks.push(ractor_task)
+        maybe_spawn_worker
+        maybe_spawn_task_feeder
+        maybe_spawn_result_feeder
+      rescue ClosedQueueError
+        raise 'RactorExecutor instance is shutdown'
+      end
+    end
+
+    # :nocov:
+
+    # Always returns `true`
+    # for `RactorExecutor`.
+    def support_concurrency?
+      true
+    end
+
+    # :nocov:
+
+    # Shutdown `RactorExecutor` instance.
+    #
+    # See `AsyncFutures::Executor.shutdown` for full documentation.
+    def shutdown(wait: true, cancel_futures: false, &block)
+      block&.call(self)
+    ensure
+      unless check_and_set_shutdown!
+        if cancel_futures
+          while (task = @tasks.pop)
+            future = task[0]
+            future.cancel
+          end
+        end
+
+        synchronize { wait_until { @worker_tasks_ports.closed? && @worker_tasks_ports.empty? } } if wait
+      end
+    end
+
+    private
+
+    def synchronize(&block)
+      @mutex.synchronize do
+        block.call
+      ensure
+        @condition.broadcast
+      end
+    end
+
+    def wait_until
+      @condition.wait(@mutex) until yield
+    end
+
+    # Returns the current shutdown state,
+    # then sets internal shutdown state to `true`.
+    # This is all done atomically to avoid race conditions.
+    def check_and_set_shutdown!
+      synchronize do
+        return true if @tasks.closed?
+
+        @tasks.close
+        return false
+      end
+    end
+
+    def new_worker_name
+      if @worker_name_prefix
+        "#{@worker_name_prefix}_#{@worker_count += 1}"
+      else
+        "#{self.class.name}_#{object_id}_worker_#{@worker_count += 1}"
+      end
+    end
+
+    def maybe_spawn_task_feeder
+      synchronize { spawn_task_feeder unless @task_feeder }
+    end
+
+    def spawn_task_feeder # rubocop:disable Metrics/AbcSize
+      @task_feeder = Thread.new("task_feeder_#{object_id}") do |feeder_name|
+        Thread.current.name = feeder_name
+
+        while (task = @tasks.pop)
+          future, block, args, kwargs = task
+
+          next unless future.set_running_or_notify_cancel
+
+          next_tasks_port = @worker_tasks_ports.pop
+
+          # `block` was already made shareable
+          # in the submitting thread.
+          # `args` and `kwargs` _may_ have been made shareable already.
+          # `object_id` is an `Integer`
+          # and thus is inherently immutable and shareable.
+          ractor_task = [future.object_id, block, args, kwargs].freeze
+          next_tasks_port.send(ractor_task, move: @move_args)
+
+          synchronize do
+            @futures[future.object_id] = future # rubocop:disable Lint/HashCompareByIdentity
+          end
+        end
+
+        # once the task queue closes
+        # that means the executor is shutdown.
+        # We need to shutdown all workers until
+        # the worker queue gets closed by the `@results_feeder`.
+        while (next_tasks_port = @worker_tasks_ports.pop)
+          next_tasks_port.send(:shutdown)
+        end
+      ensure
+        synchronize do
+          @task_feeder = nil
+        end
+      end
+    end
+
+    def maybe_spawn_result_feeder
+      synchronize { spawn_result_feeder unless @result_feeder }
+    end
+
+    def spawn_result_feeder # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+      @result_feeder = Thread.new("result_feeder_#{object_id}") do |feeder_name|
+        Thread.current.name = feeder_name
+
+        loop do
+          break_loop, results_ports_keys = synchronize do
+            wait_until { !@results_ports.empty? || (@pool.empty? && @tasks.closed? && @tasks.empty?) }
+
+            [@results_ports.empty? && @pool.empty? && @tasks.closed? && @tasks.empty?, @results_ports.keys]
+          end
+
+          break if break_loop
+
+          port, msg = Ractor.select(*results_ports_keys)
+
+          case msg
+          when :exited
+            synchronize do
+              worker = @results_ports[port]
+              @pool.delete worker
+              @results_ports.delete(port)
+            end
+            port.close
+          else # Must be an Array
+            future_id, type, value = msg
+
+            future = synchronize { @futures.delete(future_id) { raise "future_id not found #{future_id}" } }
+
+            future.set_exception(value) if type.equal? :exception
+            future.set_result(value) if type.equal? :result
+
+            tasks_port = synchronize do
+              worker = @results_ports[port]
+              @worker_to_task_port_map[worker]
+            end
+            @worker_tasks_ports.push tasks_port
+          end
+        end
+
+        # We synchronize here so that we broadcast the condition afterward.
+        synchronize { @worker_tasks_ports.close }
+      end
+    end
+
+    # Only spawn a worker if one is needed.
+    def maybe_spawn_worker
+      # synchronize when interacting directly with @pool
+      spawn_worker if synchronize { @pool.empty? || (!@tasks.empty? && @pool.size < @max_workers) }
+    end
+
+    # Always spawn a worker
+    def spawn_worker # rubocop:disable Metrics/AbcSize
+      new_results_port = Ractor::Port.new
+
+      # Coverage doesn't currently work outside the main Ractor,
+      # so just skip it for now.
+      # :nocov:
+      worker = Ractor.new(
+        new_results_port,
+        @move_result,
+        name: new_worker_name
+      ) do |results_port, move_result|
+        tasks_port = Ractor::Port.new
+
+        results_port.send(tasks_port)
+
+        Ractor.current.default_port.close
+
+        loop do
+          case (task = tasks_port.receive)
+          when :shutdown
+            break
+          when Array
+            future_id, block, args, kwargs = task
+          else
+            raise RactorError.new("Unknown message received: #{task}")
+          end
+
+          begin
+            result = block.call(*args, **kwargs)
+          rescue Exception => e # rubocop:disable Lint/RescueException
+            results_port.send([future_id, :exception, e], move: move_result)
+          else
+            results_port.send([future_id, :result, result], move: move_result)
+          end
+        end
+      ensure
+        tasks_port.close
+      end
+      # :nocov:
+
+      new_tasks_port = new_results_port.receive
+      worker.monitor new_results_port
+      synchronize do
+        @results_ports[new_results_port] = worker
+        @pool.add worker
+        @worker_to_task_port_map[worker] = new_tasks_port
+      end
+      @worker_tasks_ports.push new_tasks_port
+    end
+  end
+end

data/lib/async_futures/thread_executor.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+require_relative 'executor'
+
+require 'etc'
+require 'set' # rubocop:disable Lint/RedundantRequireStatement
+
+module AsyncFutures
+  # `Executor` implementation based on `Thread` primitives
+  # that uses a pool of up to `max_workers` to execute calls concurrently.
+  #
+  # `ThreadExecutor` specific submission considerations:
+  #
+  # For `ThreadExecutor`, with no arguments passed,
+  # the tasks are not run immediately upon submission.
+  # They are placed into a work queue
+  # to be picked up later by worker threads.
+  #
+  # This does _not_ guarantee
+  # that any particular task will be run concurrently
+  # with any other particular task;
+  # that is dependent on how many worker threads and tasks there are
+  # at any given point in time
+  # and whether the `strict_concurrency` argument is passed.
+  class ThreadExecutor # rubocop:disable Metrics/ClassLength
+    include Executor
+
+    # Create a new `ThreadExecutor`.
+    #
+    # Uses a pool of up to `max_workers`
+    # to execute tasks concurrently.
+    # If no value is given for `max_workers`
+    # it will default to `[32, Etc.nprocessors + 4].min`.
+    # Workers are spawned lazily as needed
+    # when tasks are added to the work queue.
+    #
+    # The `strict_concurrency` argument
+    # changes the behavior of both `submit` and `submit_concurrent`.
+    # When the argument is `false`
+    # then both methods will just put tasks on a queue
+    # and assume they will get picked up later.
+    # When the argument is `true` then the following happens:
+    #
+    # - `submit`: if adding another task to the queue
+    #   would make more tasks than available (or potential) workers,
+    #   then the task is run immediately
+    #   and a completed future is returned to the caller.
+    # - `submit_concurrent`: if adding another task to the queue
+    #   would make more tasks than available (or potential) workers,
+    #   then a `NoConcurrencyError` is raised.
+    #
+    # With `strict_concurrency: false`
+    # you can do interesting/dangerous things.
+    # For example, you can add tasks to the executor
+    # from within a executor worker thread,
+    # even if the max worker count is only `1`.
+    # If you think through this scenario
+    # you will realize that joining on the returned future
+    # will deadlock the worker thread.
+    #
+    # This defaults to `false` precisely because
+    # scenarios like this are uncommon.
+    # The most common scenario is firing of many tasks
+    # from the main thread of execution
+    # that do not interact other than to return a value
+    # to the main thread.
+    #
+    # A scenario where you might want `strict_concurrency` to be `true`:
+    # you have client and server tasks
+    # and they *must* run concurrent to each other in order to work correctly.
+    #
+    # Consider this pseudocode, for example:
+    #
+    # ```ruby
+    # ThreadExecutor.new(max_workers: 1, strict_concurrency: true).shutdown do |executor|
+    #   # ... other work, potentially using executor ...
+    #
+    #   # This can fail if all workers are busy. Good! We want it to.
+    #   # It doesn't make sense to run the client code afterward
+    #   # if the server isn't first running concurrently.
+    #   executor.submit_concurrent { Server.new.listen() }
+    #
+    #   # The client doesn't *need* to run concurrently;
+    #   # It is logically correct to run it either concurrently OR immediately,
+    #   # so we use `submit` instead of `submit_concurrent` for client code.
+    #   executor.submit do
+    #     client = Client.new
+    #     client.ping()
+    #     # ... interact with `client` while server runs in background concurrently ...
+    #   ensure
+    #     client.signal_server_shutdown()
+    #   end
+    #
+    #   # ... maybe more code after ...
+    # end
+    # ```
+    #
+    # If the `reap_after` keyword argument is given,
+    # worker threads will be shut down
+    # if they haven't received any work after this amount of seconds.
+    # If it is `nil` or not given,
+    # they will not be reaped until the `ThreadExecutor` instance is `shutdown`.
+    #
+    # The parameter `worker_name_prefix` can be used
+    # to optionally add a prefix to generated `Thread` worker names.
+    def initialize(
+      max_workers: nil,
+      strict_concurrency: false,
+      reap_after: nil,
+      worker_name_prefix: nil
+    )
+      @max_workers = (max_workers || [32, Etc.nprocessors + 4].min).to_i
+      @strict_concurrency = strict_concurrency
+      @reap_after = reap_after
+      @worker_name_prefix = worker_name_prefix
+      @mutex = Thread::Mutex.new
+      @tasks = Thread::Queue.new
+
+      # Set Hash value to `true` when a worker is running
+      # and `false` otherwise.
+      @pool = {}
+      @worker_count = 0
+
+      at_exit { shutdown(wait: false) }
+    end
+
+    # Asynchronously submit a task for execution.
+    #
+    # May run task immediately
+    # and return a completed `Future`
+    # under certain circumstances.
+    #
+    # See `AsyncFutures::Executor.submit` method for full documentation.
+    def submit(*args, **kwargs, &block)
+      raise ArgumentError.new('No block given') unless block
+
+      Future.new.tap do |f|
+        f.complete(*args, **kwargs, &block) unless queue_task(f, *args, **kwargs, &block)
+      rescue ClosedQueueError
+        raise 'ThreadExecutor instance is shutdown'
+      end
+    end
+
+    # Submit a task for concurrent execution.
+    #
+    # Will raise `NoConcurrencyError`
+    # if it is not possible
+    # to run the task concurrently
+    # with other already scheduled tasks.
+    #
+    # See `AsyncFutures::Executor.submit_concurrent` method for full documentation.
+    def submit_concurrent(*args, **kwargs, &block)
+      raise ArgumentError.new('No block given') unless block
+
+      Future.new.tap do |f|
+        raise NoConcurrencyError.new('Tasks exceed potential workers') unless queue_task(f, *args, **kwargs, &block)
+      rescue ClosedQueueError
+        raise 'ThreadExecutor instance is shutdown'
+      end
+    end
+
+    # Return the current size of the worker pool
+    def pool_size
+      synchronize { @pool.size }
+    end
+
+    # :nocov:
+
+    # Always returns `true`
+    # for `ThreadExecutor`.
+    def support_concurrency?
+      true
+    end
+
+    # :nocov:
+
+    # Shutdown `ThreadExecutor` instance.
+    #
+    # See `AsyncFutures::Executor.shutdown` for full documentation.
+    def shutdown(wait: true, cancel_futures: false, &block)
+      block&.call(self)
+    ensure
+      unless check_and_set_shutdown!
+        if cancel_futures
+          while (task = @tasks.pop)
+            future = task[0]
+            future.cancel
+          end
+        end
+
+        if wait
+          synchronize { @pool.dup }.each do |thread|
+            thread.join
+            synchronize { @pool.delete(thread) }
+          end
+        end
+      end
+    end
+
+    private
+
+    def synchronize(&)
+      @mutex.synchronize(&)
+    end
+
+    # Returns the current shutdown state,
+    # then sets internal shutdown state to `true`.
+    # This is all done atomically to avoid race conditions.
+    def check_and_set_shutdown!
+      synchronize do
+        return true if @tasks.closed?
+
+        @tasks.close
+        return false
+      end
+    end
+
+    # Attempt to queue task.
+    # Return `true` if successful, `false` otherwise.
+    #
+    # Raises `ClosedQueueError` if the task queue is closed.
+    #
+    # If `@strict_concurrency` is `false`,
+    # this method always queues the task.
+    #
+    # If `@strict_concurrency` is `true`,
+    # task may or may not be queued
+    # based on whether there are any potentially available workers.
+    #
+    # May spawn a new worker, if the task was queued.
+    def queue_task(future, *args, **kwargs, &block)
+      queued = if @strict_concurrency
+                 synchronize do
+                   potential_workers = (@max_workers - @pool.size) + @pool.values.count(&:!)
+                   if (@tasks.size + 1) <= potential_workers
+                     @tasks.push([future, block, args, kwargs])
+                     true
+                   else
+                     raise ClosedQueueError if @tasks.closed?
+
+                     false
+                   end
+                 end
+               else
+                 @tasks.push([future, block, args, kwargs])
+                 true
+               end
+
+      queued.tap { maybe_spawn_worker if queued }
+    end
+
+    # Only spawn a worker if one is needed.
+    def maybe_spawn_worker
+      # synchronize when interacting directly with @pool
+      spawn_worker if !@tasks.empty? && synchronize { @pool.size } < @max_workers
+    end
+
+    def new_worker_name
+      synchronize do
+        if @worker_name_prefix
+          "#{@worker_name_prefix}_#{@worker_count += 1}"
+        else
+          "#{self.class.name}_#{object_id}_worker_#{@worker_count += 1}"
+        end
+      end
+    end
+
+    # Always spawn a worker
+    def spawn_worker # rubocop:disable Metrics/AbcSize
+      thread = Thread.new do
+        Thread.current.name = new_worker_name
+        while (task = @tasks.pop(timeout: @reap_after))
+          synchronize { @pool[Thread.current] = true }
+
+          tfuture, tblock, targs, tkwargs = task
+          tfuture.complete(*targs, **tkwargs, &tblock)
+
+          synchronize { @pool[Thread.current] = false }
+        end
+      ensure
+        synchronize { @pool.delete Thread.current }
+      end
+      synchronize { @pool[thread] ||= false }
+    end
+  end
+end

data/lib/async_futures/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module AsyncFutures
+  # Version of the library as a String instance.
+  VERSION = '0.1.2'
+end

data/lib/async_futures.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Library to create Future instances.
+#
+# Has Executor implementations for Ractor, Thread, and Fiber primitives.
+module AsyncFutures
+end
+
+# In order of dependency (roughly)
+require_relative 'async_futures/logger'
+require_relative 'async_futures/version'
+require_relative 'async_futures/error'
+require_relative 'async_futures/future'
+require_relative 'async_futures/executor'
+require_relative 'async_futures/fiber_executor'
+require_relative 'async_futures/thread_executor'
+
+# ractor executor is only support in version 4.x or greater,
+# so it must be required explicitly.
+# require_relative 'async_futures/ractor_executor'

data/sig/async_futures.rbs

@@ -0,0 +1,4 @@
+module AsyncFutures
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end