async_futures 0.1.2

data/lib/async_futures/io_async.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+require_relative 'future'
+
+require 'timeout'
+require 'openssl'
+require 'stringio'
+require 'set' # rubocop:disable Lint/RedundantRequireStatement
+
+module AsyncFutures
+  # This is a simple example mixin module
+  # to add async IO to the `IO` and `OpenSSL::SSLSocket` classes.
+  # You can also `include` this in other classes
+  # so long as they have the methods `write_nonblock` and `read_nonblock`
+  # and they behave the same way as `IO` and/or `OpenSSL::SSLSocket`.
+  #
+  # All reads and writes are done on (at least) one background worker thread.
+  #
+  # This is not the most efficient implementation.
+  # It is just meant to be an example
+  # of how one can use the `Future` class
+  # outside of an `Executor` implementation.
+  #
+  # It's only real efficiencies, so to speak,
+  # are that it doesn't use a thread per future
+  # (which would potentially use up a lot of memory),
+  # nor do futures need to wait until a thread opens up on a worker pool
+  # (which would block newer IO work until older IO work completely finished).
+  # Instead work is picked up immediately
+  # on at least one background worker thread,
+  # and attempts to read/write are started immediately
+  # via `read_nonblock` and `write_nonblock`.
+  # If `read_nonblock`/`write_nonblock` cannot proceed
+  # (because they would block)
+  # for any particular `IO` object
+  # then the next operation for the next `IO` object is attempted,
+  # and so forth,
+  # until all the work is completed (or a timeout happens).
+  #
+  # However, all of this is accomplished via a simplistic, unoptimized busy loop.
+  # This is less than ideal.
+  # There are some simple sleeps and timeouts added
+  # to avoid completely eating up the CPU,
+  # but this is still a very naive approach.
+  #
+  # A better implementation would utilize higher performance OS specific features
+  # like FreeBSD's kqueue/aio or Linux's epoll/io_uring.
+  # However, the logic for integrating these
+  # is beyond the scope of this example code.
+  #
+  # This could probably be done using the FFI library fiddle,
+  # which is bundled with ruby,
+  # so it wouldn't need to reach outside the standard library.
+  # However I have a very good reason for not doing that right now:
+  # I don't want to.
+  module IOAsync
+    # Return an incomplete future
+    # that will eventually contain an integer with the number of bytes written
+    # or an exception if the string could not be written for some reason.
+    #
+    # The `string` argument is written in a nonblocking fashion
+    # on a background worker thread.
+    #
+    # The optional `timeout` argument
+    # causes the work to finish the future exceptionally with `Timeout::Error`
+    # if it takes longer than `timeout` seconds to complete.
+    # This is used to avoid having background work that spins forever
+    # on IO that may never complete.
+    # If `nil` or no value is given, this means no timeout
+    # (i.e. potentially spin indefinitely).
+    #
+    # This should *not* be confused with the `Timeout::Error` raised via the
+    # `timeout` argument on `Future.result` and `Future.exception`.
+    # If it matters for your purposes to differentiate between the two,
+    # you can do something like the following:
+    #
+    # ```ruby
+    # # `join` returns `nil` on timeout
+    # result = if future.join(1.0)
+    #            # If `Timeout::Error` is raised here,
+    #            # it is from the `timeout` parameter to the `*_async` method.
+    #            future.result
+    #          else
+    #            raise Timeout::Error.new('Timed out on `join`')
+    #          end
+    # ```
+    #
+    # The optional `sleep_timeout` keyword argument
+    # is used to determine how quickly the worker thread
+    # stops polling the input work queue
+    # and how much sleep time happens between failed nonblocking IO attempts.
+    # It defaults to 1ms.
+    # If existing worker(s) have already been spawned,
+    # then this argument isn't used.
+    #
+    # If the process shuts down before the future can be fully completed,
+    # the work may be abandoned even if it partially completed.
+    def write_async(string, timeout = nil, sleep_timeout: 0.001) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity
+      Future.new.tap do |ftr|
+        clock_timeout = timeout && (Time.now.to_f + timeout)
+
+        work_proc = proc do
+          # :nocov:
+          break ftr unless ftr.set_running_or_notify_cancel(set_context: true)
+          # :nocov:
+
+          to_err = Timeout::Error.new('execution expired')
+          all_written = 0
+
+          loop do
+            cur_to = timeout && (Time.now.to_f - clock_timeout)
+            break ftr.tap { ftr.set_exception(to_err) } unless timeout.nil? || cur_to.positive?
+
+            bytes_written = write_nonblock(string)
+            string = string[bytes_written..nil]
+            all_written += bytes_written
+            break ftr.tap { ftr.set_result(all_written) } if string.empty?
+          rescue IO::WaitReadable, IO::WaitWritable, Errno::EINTR
+            Fiber.yield nil
+            retry
+          rescue Exception => e # rubocop:disable Lint/RescueException
+            break ftr.tap { ftr.set_exception(e) }
+          end
+        end
+
+        io_async_queue.push(work_proc)
+        maybe_spawn_worker(sleep_timeout)
+      end
+    end
+
+    # Return an incomplete future
+    # that will eventually contain the string value read from the IO object
+    # or an exception if the IO object could not be read from for some reason.
+    #
+    # A string up to `maxlen` in length is read in a nonblocking fashion
+    # on a background worker thread.
+    #
+    # The optional `timeout` argument
+    # causes the work to finish the future exceptionally with `Timeout::Error`
+    # if it takes longer than `timeout` seconds to complete.
+    # This is used to avoid having background work that spins forever
+    # on IO that may never complete.
+    # If `nil` or no value is given, this means no timeout
+    # (i.e. potentially spin indefinitely).
+    #
+    # This should *not* be confused with the `Timeout::Error` raised via the
+    # `timeout` argument on `Future.result` and `Future.exception`.
+    # If it matters for your purposes to differentiate between the two,
+    # you can do something like the following:
+    #
+    # ```ruby
+    # # `join` returns `nil` on timeout
+    # result = if future.join(1.0)
+    #            # If `Timeout::Error` is raised here,
+    #            # it is from the `timeout` parameter to the `*_async` method.
+    #            future.result
+    #          else
+    #            raise Timeout::Error.new('Timed out on `join`')
+    #          end
+    # ```
+    #
+    # The optional `sleep_timeout` keyword argument
+    # is used to determine how quickly the worker thread
+    # stops polling the input work queue
+    # and how much sleep time happens between failed nonblocking IO attempts.
+    # It defaults to 1ms.
+    # If existing worker(s) have already been spawned,
+    # then this argument isn't used.
+    #
+    # If the process shuts down before the future can be fully completed,
+    # the work may be abandoned even if it partially completed.
+    def read_async(maxlen, timeout = nil, sleep_timeout: 0.001) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity
+      Future.new.tap do |ftr|
+        clock_timeout = timeout && (Time.now.to_f + timeout)
+
+        work_proc = proc do
+          # :nocov:
+          break ftr unless ftr.set_running_or_notify_cancel(set_context: true)
+          # :nocov:
+
+          to_err = Timeout::Error.new('execution expired')
+          to_read_length = maxlen
+          retrieved_str = String.new
+
+          loop do
+            cur_to = timeout && (Time.now.to_f - clock_timeout)
+            break ftr.tap { ftr.set_exception(to_err) } unless timeout.nil? || cur_to.positive?
+
+            retrieved_str << read_nonblock(to_read_length)
+            to_read_length = maxlen - retrieved_str.size
+            break ftr.tap { ftr.set_result(retrieved_str) } if to_read_length.zero?
+          rescue IO::WaitReadable, IO::WaitWritable, Errno::EINTR
+            Fiber.yield nil
+            retry
+          rescue EOFError
+            break ftr.tap { ftr.set_result(retrieved_str) }
+          rescue Exception => e # rubocop:disable Lint/RescueException
+            break ftr.tap { ftr.set_exception(e) }
+          end
+        end
+
+        io_async_queue.push(work_proc)
+        maybe_spawn_worker(sleep_timeout)
+      end
+    end
+
+    private
+
+    # This method will spawn *at least* one worker thread.
+    # It *may* spawn more than one worker thread
+    # based on submission thread timing,
+    # but that is ok,
+    # because they will all eventually reap once they run out of work
+    # and the individual work is grabbed exclusively per thread
+    # via the thread safe queue.
+    #
+    # If work starts up again after reaping all threads,
+    # then new worker thread(s) will be spawned again.
+    def maybe_spawn_worker(sleep_timeout)
+      Ractor[:io_async_worker] ||= Thread.new do
+        worker_fibers = Set.new
+
+        while (fproc = io_async_queue.pop(timeout: sleep_timeout))
+          worker_fibers.add(Fiber.new(&fproc))
+          worker_fibers.reject!(&:resume)
+        end
+
+        # We need to unset the worker thread
+        # since we're no longer polling the input queue.
+        #
+        # If more work comes in,
+        # new worker thread(s) need to be spawned.
+        Ractor[:io_async_worker] = nil
+
+        # FIXME: if we have IO that never finishes,
+        # this will create zombie threads that busy loop and never complete.
+        until worker_fibers.empty?
+          # Sleep when no fiber in the set completes
+          sleep(sleep_timeout) unless worker_fibers.reject!(&:resume)
+        end
+      end
+    end
+
+    GLOBAL_MUTEX = Thread::Mutex.new
+
+    private_constant :GLOBAL_MUTEX
+
+    def io_async_queue
+      GLOBAL_MUTEX.synchronize do
+        Ractor[:io_async_queue] ||= Thread::Queue.new
+      end
+    end
+  end
+
+  # Simple mixin for sync IO with an async interface.
+  module IOSync
+    # Return a completed future
+    # containing an integer with the number of bytes written.
+    #
+    # This exists for classes such as `StringIO` to maintain compatibility
+    # with classes with true nonblocking methods (such as `IO`).
+    #
+    # There is no performance benefit
+    # to calling this instead of directly calling `write`.
+    # In fact,
+    # there may be a slight performance degradation
+    # because of the added overhead of instantiating
+    # and completing a `Future` object.
+    #
+    # You should only use this method if you are dealing with a mix
+    # of `IO`, `OpenSSL::SSLSocket`, and/or `StringIO` objects
+    # and want to interact with them identically in a nonblocking manner.
+    # Or you may want to use this method with `StringIO`
+    # as a type of mock object for testing
+    # in place of real `IO` or `OpenSSL::SSLSocket` objects.
+    def write_async(string, *args, **kwargs) # rubocop:disable Lint/UnusedMethodArgument
+      Future.new.tap do |ftr|
+        ftr.complete(string, &method(:write))
+      end
+    end
+
+    # Return a completed future
+    # containing a string up to `maxlen` bytes long.
+    #
+    # This exists for classes such as `StringIO` to maintain compatibility
+    # with classes with true nonblocking methods (such as `IO`).
+    #
+    # There is no performance benefit
+    # to calling this instead of directly calling `read`.
+    # In fact,
+    # there may be a slight performance degradation
+    # because of the added overhead of instantiating
+    # and completing a `Future` object.
+    #
+    # You should only use this method if you are dealing with a mix
+    # of `IO`, `OpenSSL::SSLSocket`, and/or `StringIO` objects
+    # and want to interact with them identically in a nonblocking manner.
+    # Or you may want to use this method with `StringIO`
+    # as a type of mock object for testing
+    # in place of real `IO` or `OpenSSL::SSLSocket` objects.
+    def read_async(maxlen, *args, **kwargs) # rubocop:disable Lint/UnusedMethodArgument
+      Future.new.tap do |ftr|
+        ftr.complete(maxlen, &method(:read))
+      end
+    end
+  end
+end
+
+IO.include AsyncFutures::IOAsync
+
+OpenSSL::SSL::SSLSocket.include AsyncFutures::IOAsync
+
+StringIO.include AsyncFutures::IOSync

data/lib/async_futures/logger.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module AsyncFutures # rubocop:disable Style/Documentation
+  class << self
+    # Configurable logger for the library. All calls assume the standard logger interface.
+    #
+    # Defaults to being unset (i.e. `nil`).
+    attr_accessor :logger
+  end
+end

data/lib/async_futures/process_executor.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require_relative 'executor'
+
+require 'etc'
+require 'set' # rubocop:disable Lint/RedundantRequireStatement
+
+module AsyncFutures
+  # `Executor` implementation based on Process forking
+  # that uses up to `max_workers` to execute calls concurrently.
+  #
+  # `ProcessExecutor` specific submission considerations:
+  #
+  # For `ProcessExecutor` the tasks are never run immediately upon submission.
+  # They are placed into a work queue
+  # to be picked up later.
+  #
+  # Process workers are not reused for work.
+  # Each task gets a freshly forked process.
+  # This is because marshalling anonymous blocks is not trivial;
+  # it is simpler to just fork after the block closure has been defined.
+  # Use `ThreadExecutor` or `RactorExecutor`
+  # for `Executor` implementations that support worker reuse.
+  #
+  # Consequently, this executor is only really useful for expensive calculations
+  # where the startup time for a process
+  # is dwarfed by the time needed for the actual work.
+  # If RactorExecutor is available on your Ruby version
+  # it is almost certainly a better choice than this.
+  #
+  # 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 ProcessExecutor
+    include Executor
+
+    # Create a new `ProcessExecutor`.
+    #
+    # 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 `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 `ProcessExecutor` instance is `shutdown`.
+    def initialize(max_workers: nil, worker_name_prefix: '', reap_after: nil)
+      @max_workers = (max_workers || [32, Etc.nprocessors + 4].min).to_i
+      @worker_name_prefix = worker_name_prefix.to_s
+      @reap_after = reap_after
+      @mutex = Thread::Mutex.new
+      @tasks = Thread::Queue.new
+      @pool = Set.new
+
+      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
+      raise 'ProcessExecutor instance is shutdown' if @tasks.closed?
+
+      Future.new.tap do |future|
+        @tasks.push([future, block, args, kwargs])
+        maybe_spawn_worker
+      end
+    end
+
+    alias submit_concurrent submit
+
+    public :map
+
+    # Shutdown `ProcessExecutor` 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
+
+    # 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
+
+    # Always spawn a worker
+    def spawn_worker # rubocop:disable Metrics/AbcSize
+      thread = Thread.new do
+        Thread.current.name = "#{@worker_name_prefix}_#{Thread.current.object_id}" unless @worker_name_prefix.empty?
+
+        while (task = @tasks.pop(timeout: @reap_after))
+          tfuture, tblock, targs, tkwargs = task
+
+          next unless tfuture.set_running_or_notify_cancel
+
+          begin
+            result = tblock.call(*targs, **tkwargs)
+          rescue Exception => e # rubocop:disable Lint/RescueException
+            tfuture.set_exception(e)
+          else
+            tfuture.set_result(result)
+          end
+        end
+      ensure
+        synchronize { @pool.delete Thread.current }
+      end
+      synchronize { @pool.add thread }
+    end
+  end
+end