async_futures 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d1d673d78fe3b8bae70c67b12abf800e58cd79b95a7690c939b3d6d125d4224a
+  data.tar.gz: 4806d60aa3da8d213aa286874dbc8c7a90902832acb22e35ed00060595a8419f
+SHA512:
+  metadata.gz: 9a3ee85e2d1d7a99feaae35124610c1d6265a43b27da902a3e32f683eb32d159a0b4cb7f6441e71de9e04da8827a30504058f9908976273abf11bec038c97fa8
+  data.tar.gz: 11cb824b92cd4dee667e477a0f67b0b8fce864ce5eef5dd3781fc5f345d27cfd0cdedb349c95695ab957506a46027f67bb6b278825f147f5f6a84045ff59e375

data/.tool-versions

@@ -0,0 +1 @@
+ruby 4.0.5

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-05-07
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,12 @@
+Copyright (C) 2025 Ethan D. Estrada <ethan@misterfidget.com>
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

data/README.md

@@ -0,0 +1,220 @@
+# AsyncFutures
+
+## Launch asynchronous tasks
+
+[![CI Status](https://github.com/eestrada/async_futures/actions/workflows/main.yml/badge.svg?branch=master)](https://github.com/eestrada/async_futures/actions/workflows/main.yml)
+
+This library is heavily inspired by Python's `concurrent.futures` module.
+It's API (mostly) follows the same one as the Python
+[library](https://docs.python.org/3.13/library/concurrent.futures.html).
+There are some differences to make it more Ruby-ish where it makes sense
+(e.g. taking blocks instead of callable parameters, etc).
+There are also separate submission methods
+for concurrent versus non-concurrent tasks
+for reasons explained later.
+
+It has a different name for several reasons:
+
+1. The [concurrent-ruby](https://rubygems.org/gems/concurrent-ruby) library
+   already exists and is very popular.
+   Naming this library `concurrent-futures`
+   would place it under the same `Concurrent` module namespace.
+   This would be confusing,
+   since this project isn't associated with that one.
+2. This library does not _require_ that `Executor` implementations support concurrency,
+   only asynchrony.
+   (See Loris Cro's excellent article
+   [Asynchrony is not Concurrency](https://kristoff.it/blog/asynchrony-is-not-concurrency/)
+   to understand the way these terms are used in this project's documentation).
+   Consequently, this library implements (and supports) `Executor` implementations
+   that conform to an asynchronous interface,
+   but can in reality run immediately in synchronous modes.
+   This is still logically correct based on Loris Cro's definition of asynchrony:
+   the possibility for tasks to run out of order
+   and still be correct.
+   This means tasks run strictly in order
+   (i.e. synchronously)
+   are _also_ correct.
+3. The more straightforward gem names [future](https://rubygems.org/gems/future)
+   and [futures](https://rubygems.org/gems/futures)
+   were already taken.
+
+This Gem has multiple `Executor` implementations for creating `Future` instances
+for tasks executed by `Ractor`, `Thread`, and `Fiber` concurrency primitives.
+Users of the library can easily test out the performance differences
+of primitives while only changing their code minimally.
+
+Although the base `Executor` module is meant to be used as a mixin interface,
+the module can also be run directly
+to have a synchronous `Executor` implementation
+that runs code immediately
+and returns a completed future at the point of submission.
+Although this may seem pointless, it has the benefit
+that users of this library can trivially change their code execution
+from serial to concurrent and back again
+simply by using different `Executor` implementations.
+In other words, their code does not require multiple complicated code paths
+for correctness: it need only supply a different `Executor` instance
+to get different performance
+(assuming their code logic supports asynchrony
+and doesn't require concurrency for correctness).
+
+### Why wouldn't I just use `concurrent-ruby` for concurrency?
+
+`concurrent-ruby` is a good library.
+It is mainly focused on `Thread` primitives and thread safety.
+If that is all you want/need, then you should use it.
+
+The focus of this library is different.
+This is meant to be a uniform
+(albeit simple)
+interface around _all_ concurrency/async primitives offered by Ruby.
+You can indicate async versus concurrent intent
+using the `submit` versus `submit_concurrent` methods
+on `Executor` implementations.
+It should also be possible to use the `Future` class
+for things like event based libraries (i.e. async)
+that were not intended to be used in this way.
+Thus the `Executor` interface is not required
+for the use of async futures.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add async_futures
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install async_futures
+```
+
+## Usage
+
+The test suite and benchmark script
+are probably the best place to see example usage.
+
+However, here are some quick introductory examples:
+
+
+```ruby
+require 'async_futures'
+
+# Base `Executor` mixin module (inline execution):
+bexec = AsyncFutures::Executor
+ftr1 = bexec.submit('world') { |subject| 'hello ' + subject.to_s }
+final_string = ftr1.result
+
+begin
+   ftr1 = bexec.submit_concurrent('world') { |subject| 'hello ' + subject.to_s }
+rescue AsyncFutures::NoConcurrencyError
+   # This will always trigger
+end
+
+subjects = ['Alice', 'Bob', 'Charlie']
+final_strings = bexec.map(subjects) { |subject| 'hello ' + subject.to_s }.to_a
+
+# `ThreadExecutor`:
+texec = AsyncFutures::ThreadExecutor.new
+ftr1 = texec.submit('world') { |subject| 'hello ' + subject.to_s }
+final_string = ftr1.result
+
+begin
+   ftr1 = texec.submit_concurrent('world') { |subject| 'hello ' + subject.to_s }
+rescue AsyncFutures::NoConcurrencyError
+   # This will not trigger by default
+   # but may trigger based on some initialize arguments.
+   # See docs for details.
+end
+
+subjects = ['Alice', 'Bob', 'Charlie']
+final_strings = texec.map(subjects) { |subject| 'hello ' + subject.to_s }.to_a
+
+# `FiberExecutor`:
+Fiber.set_scheduler(some_scheduler)
+fexec = AsyncFutures::FiberExecutor.new
+
+# It isn't necessary to submit within a scheduled fiber
+# but if we want to join in the same thread
+# we need to run within the scheduler.
+# However, cross thread joining is safe.
+Fiber.schedule do
+   ftr1 = fexec.submit('world') { |subject| 'hello ' + subject.to_s }
+   final_string = ftr1.result
+
+   begin
+      ftr1 = fexec.submit_concurrent('world') { |subject| 'hello ' + subject.to_s }
+   rescue AsyncFutures::NoConcurrencyError
+      # This will trigger by default
+      # but can be suppressed by an initialize argument.
+      # See docs for details.
+   end
+
+   subjects = ['Alice', 'Bob', 'Charlie']
+   final_strings = fexec.map(subjects) { |subject| 'hello ' + subject.to_s }.to_a
+end
+
+# Unsetting the scheduler causes it to run to completion.
+# Otherwise, we may need to wait until process exit
+# for it to fully finish running.
+Fiber.set_scheduler(nil)
+
+# `RactorExecutor`:
+
+# This must be explicitly required
+# since it doesn't run on anything prior to Ruby version 4.x
+# (the API changed a lot between versions so it only targets 4.x for now).
+# Also, the Java based VMs (JRuby and TruffleRuby)
+# don't support Ractor primitives *at all* yet.
+require 'async_futures/ractor_executor'
+
+rexec = AsyncFutures::RactorExecutor.new
+ftr1 = rexec.submit('world') { |subject| 'hello ' + subject.to_s }
+final_string = ftr1.result
+
+begin
+   ftr1 = rexec.submit_concurrent('world') { |subject| 'hello ' + subject.to_s }
+rescue AsyncFutures::NoConcurrencyError
+   # This will not currently trigger.
+   # This may change in a future version to be more like ThreadExecutor.
+end
+
+subjects = ['Alice', 'Bob', 'Charlie']
+final_strings = rexec.map(subjects) { |subject| 'hello ' + subject.to_s }.to_a
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies.
+Then, run `rake test` to run the tests.
+You can also run `bin/console` for an interactive prompt
+that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+To release a new version, update the version number in `version.rb`,
+and then run `bundle exec rake release`,
+which will create a git tag for the version,
+push git commits and the created tag,
+and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+### Benchmarks
+
+There is a simple benchmarking script in this repo at `bin/benchmark`.
+It takes no command line arguments.
+Just read it,
+then run it
+to see the difference in executor performance
+on different types of workloads.
+
+### Documentation
+
+The documentation in this repo uses [Semantic Line breaks](https://sembr.org/).
+If you contribute documentation changes, please follow the same convention.
+
+## Contributing
+
+Bug reports and pull requests are welcome on Codeberg at
+<https://codeberg.org/eestrada/async_futures>.

data/Rakefile

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'minitest/test_task'
+require 'rubocop/rake_task'
+require 'rdoc/task'
+
+Minitest::TestTask.create
+
+# https://github.com/simplecov-ruby/simplecov/issues/1032#issuecomment-2087973750
+Minitest::TestTask.create(:coverage) do |t|
+  # simplecov can be configured inside the `test/minitest_helper.rb` file, but it
+  # needs to be required before minitest, otherwise it's at_exit hook won't be
+  # registered in the correct order, which will cause coverage to be missed.
+  #
+  # Run `rake test:cmd` and `rake coverage:cmd` to see the difference.
+  t.test_prelude = 'require "simplecov"'
+  t.verbose = true
+end
+
+CLEAN << 'coverage'
+
+RuboCop::RakeTask.new
+
+namespace :rbs do
+  desc 'Generate prototypes for all library files'
+  task :prototype do
+    Dir.chdir('lib') do
+      Dir.glob('**/*.rb').each do |e|
+        FileUtils.mkdir_p("../sig/#{File.dirname(e)}")
+        sh "bundle exec rbs prototype rb '#{e}' > '../sig/#{e}s'"
+      end
+    end
+  end
+
+  desc 'Validate RBS files'
+  task :validate do
+    sh 'bundle', 'exec', 'rbs', 'validate'
+  end
+end
+
+# https://docs.ruby-lang.org/en/3.4/RDoc/Task.html
+RDoc::Task.new do |rdoc|
+  rdoc.markup = 'markdown'
+  rdoc.main = 'README.md'
+  rdoc.rdoc_files.include('README.md', 'lib/**/*.rb')
+
+  # `docs` directory is what GitHub currently supports as pages source.
+  rdoc.rdoc_dir = 'docs'
+end
+
+task default: %i[rubocop coverage]

data/lib/async_futures/error.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module AsyncFutures
+  # Base error class.
+  class Error < StandardError; end
+
+  # Error that signals that concurrency is not available for the requested operation.
+  # This may be permanent or temporary.
+  class NoConcurrencyError < Error; end
+
+  # Error raised for all invalid Future states.
+  class InvalidStateError < Error
+    attr_reader :future, :state
+
+    def initialize(future, state)
+      @future = future
+      @state = state
+
+      super("Unexpected state '#{@state}' for Future: #{@future}")
+    end
+  end
+
+  # Error that is raised for invalid operations on a cancelled Future.
+  class CancelledError < Error; end
+
+  # Error for Executor errors related to Ractors.
+  class RactorError < Error; end
+
+  # Error for Future errors related to deadlocks.
+  class DeadlockError < Error
+    attr_reader :future
+
+    def initialize(future)
+      @future = future
+
+      super("Future would deadlock: #{@future}")
+    end
+  end
+end

data/lib/async_futures/executor.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require_relative 'error'
+require_relative 'future'
+
+require 'timeout'
+
+module AsyncFutures
+  # `Executor` mixin module.
+  # Has a simple implementation
+  # that just runs submitted blocks immediately
+  # and returns a completed `Future`.
+  # Can be used standalone as a stateless `Executor`
+  # that runs submitted blocks immediately.
+  #
+  # Classes using this mixin should override the `submit` method.
+  #
+  # `shutdown` should be overridden if there is cleanup to be performed.
+  #
+  # If an implementation wants to signal that it supports true concurrency,
+  # it should override the `submit_concurrent` method;
+  # this can be as simple as aliasing it
+  # to the previously overridden `submit` method.
+  #
+  # The `map` method should *never* be overridden.
+  # This is already logically correct
+  # and should work with any `Executor` implementation.
+  module Executor
+    # Schedules the block
+    # to be executed as `block.call(*args, **kwargs)`
+    # and returns a `Future` object representing the execution of the block.
+    #
+    # Some Executor implementations may,
+    # under some or all circumstances,
+    # run the given block immediately and synchronously
+    # and return an already completed `Future` object.
+    def submit(...)
+      Future.new.tap { |future| future.complete(...) }
+    end
+
+    # Schedules the block, to be executed as `block.call(*args, **kwargs)` and
+    # returns a `Future` object representing the execution of the block.
+    #
+    # Executor must support concurrency otherwise this method will raise the
+    # exception `NoConcurrencyError`.
+    #
+    # This method should *never* run the block to completion before returning.
+    # This could cause a serious deadlock condition that cannot be overcome.
+    # If an implementation cannot schedule this to run concurrently
+    # it is better for it to raise an exception such as `NoConcurrencyError`.
+    # This at least allows the caller an opportunity to recover
+    # instead of potentially deadlocking.
+    def submit_concurrent(...)
+      raise NoConcurrencyError unless support_concurrency?
+
+      submit(...)
+    end
+
+    # Return whether the current `Executor` implementation supports concurrency.
+    def support_concurrency?
+      false
+    end
+
+    # Similar to `enumerable.map(&block)` except:
+    #
+    # - `block` is executed asynchronously
+    # - several calls to block may be made concurrently
+    # - Instead of an `Array`, an `Enumerator::Lazy` is returned
+    #
+    # Just like `enumerable.map`,
+    # args are splatted for the block if there are multiple args.
+    # Thus you can do things like this:
+    #
+    # ```ruby
+    # ThreadExecutor.new.map(enum.each_with_index) do |e, i|
+    #     [e, i]
+    # end
+    # ```
+    #
+    # `Future` instances are joined
+    # as the returned `Enumerator::Lazy` is enumerated over
+    # via a terminal method like `force`, `to_a`, or `each`.
+    # The `Future.result` values,
+    # and not the `Future` instances themselves,
+    # are what is returned.
+    #
+    # If a `block` call raises an exception,
+    # then that exception will be raised
+    # when its value is retrieved when enumerating
+    # over the `Enumerator::Lazy` instance.
+    # Any remaining `Future` instances will attempt to be cancelled
+    # in the case of a raised exception.
+    # However, because of possible concurrent execution
+    # there is no guarantee that they will be cancelled
+    # before being picked up, run, and completed.
+    #
+    # If `timeout` is given and not `nil`,
+    # then execution will raise `Timeout::Error`
+    # if more than `timeout` seconds elapses.
+    # The elapsed time includes both the initial submission of tasks
+    # *and* the enumeration of `Future` results from the returned `Enumerator::Lazy`.
+    #
+    # Keep in mind that an `Enumerator::Lazy` can be enumerated over more than once
+    # *and* that the `timeout` value will be evaluated each time it is enumerated
+    # *and* that the timeout value will be calculated from the time of first submission.
+    # Thus, enumeration could succeed on the first enumeration,
+    # but fail with a `Timeout::Error` on a subsequent enumeration.
+    # To avoid timing out on an enumeration after the first enumeration,
+    # you should save the result of the first enumeration in an `Array` (or similar)
+    # using something like `to_a` on the returned `Enumerator::Lazy` instance.
+    # If you immediately enumerate the returned `Enumerator::Lazy` only once
+    # or you have passed no `timeout` value,
+    # then none of this is a concern.
+    #
+    # Negative `timeout` values are allowed,
+    # but they just raise `Timeout::Error` immediately.
+    #
+    # Do ***not*** call this method with an infinite `Enumerable`
+    # and no `timeout` value:
+    # the first thing this method does is force it into a finite collection of futures.
+    # An infinite `Enumerable` forced into a finite collection
+    # will run forever and eventually eat up all memory.
+    def map(enumerable, timeout = nil, &block) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+      timeout = nil if timeout&.zero?
+
+      clock_timeout = Time.now.to_f + timeout if timeout
+
+      futures = []
+      begin
+        local_timeout = timeout && (clock_timeout - Time.now.to_f)
+        raise Timeout::Error unless timeout.nil? || local_timeout.positive?
+
+        Timeout.timeout(local_timeout) do
+          enumerable.each { |*args| futures << submit(*args, &block) }
+        end
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        futures.each(&:cancel)
+        raise e
+      end
+
+      futures.each_with_index.lazy.map do |future, index|
+        local_timeout = timeout && (clock_timeout - Time.now.to_f)
+        raise Timeout::Error unless timeout.nil? || local_timeout.positive?
+
+        Timeout.timeout(local_timeout) { future.result }
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        # If *any* future raises an exception,
+        # we need to be sure to cancel the remaining ones.
+        # It's ok if we call cancel on already completed ones.
+        (index...futures.size).each { |i| futures[i].cancel }
+        raise e
+      end
+    end
+
+    # Signal the executor that it should free any resources that it is using
+    # when the currently pending futures are done executing. Calls to
+    # Executor.submit() and Executor.map() made after shutdown will raise
+    # RuntimeError.
+    #
+    # If `wait` is `true` then this method will not return until all the pending
+    # futures are done executing and the resources associated with the executor
+    # have been freed. If `wait` is `False` then this method will return immediately
+    # and the resources associated with the executor will be freed when all
+    # pending futures are done executing. Regardless of the value of `wait`, the
+    # entire Ruby program will not exit until all pending futures are done
+    # executing.
+    #
+    # If `cancel_futures` is `true`, this method will cancel all pending futures
+    # that the executor has not started running. Any futures that are completed
+    # or running won't be cancelled, regardless of the value of `cancel_futures`.
+    #
+    # If both `cancel_futures` and `wait` are `true`, all futures that the executor
+    # has started running will be completed prior to this method returning. The
+    # remaining futures are cancelled.
+    #
+    # You can ensure this gets called under all circumstances
+    # by calling this method with a block.
+    # The block will be called
+    # and then any shutdown cleanup logic will be run
+    # after the block completes.
+    # The block will be passed one parameter: the executor instance.
+    #
+    # ```ruby
+    # ThreadExecutor.new(max_workers: 4).shutdown do |executor|
+    #     executor.submit('src1.txt', 'dest1.txt', &FileUtils.method(:cp))
+    #     executor.submit('src2.txt', 'dest2.txt', &FileUtils.method(:cp))
+    #     executor.submit('src3.txt', 'dest3.txt', &FileUtils.method(:cp))
+    #     executor.submit('src4.txt', 'dest4.txt', &FileUtils.method(:cp))
+    # end
+    # ```
+    #
+    # `shutdown` can be called multiple times.
+    # The block given will always be run,
+    # but the actual procedure to shutdown afterward will only be called once,
+    # on the first time.
+    #
+    # It is the caller's responsibility
+    # to ensure that the passed block can deal with a shutdown executor
+    # if there is any possibility
+    # of `shutdown` being called more than once with a block.
+    # Unless the caller is doing something very out of the ordinary,
+    # this is unlikely to be an issue.
+    #
+    # This method returns the return value of the block,
+    # or `nil` if no block is given.
+    def shutdown(wait: true, cancel_futures: false, &block) # rubocop:disable Lint/UnusedMethodArgument
+      block&.call(self)
+    ensure # rubocop:disable Lint/EmptyEnsure
+      # Cleanup logic goes here.
+      #
+      # The mixin has no state,
+      # so it has nothing to cleanup.
+      #
+      # Also, this is the only implementation that will *not* raise
+      # an exception when new tasks are submitted after shutdown,
+      # precisely because it has no state
+      # to even keep track of whether shutdown has previously been called or not.
+    end
+
+    module_function :submit, :submit_concurrent, :support_concurrency?, :map, :shutdown
+
+    public :submit, :submit_concurrent, :support_concurrency?, :map, :shutdown
+  end
+end