Concurrent Ruby

The Actor abstraction is designed to match Erlang-like behavior. The implementation supports different modes depending on the use case:

• Thread-backed: Each actor is backed by its own thread. Best for a limited number of long-running actors where a simple actor body is desired.
• Stack-less: Each message triggers a method call on the actor. These can run on a thread pool, allowing for a large number of short-lived actors, but they are less suitable for complex bodies that change behavior.
• Simulated process: Offers the most flexibility with no limitations, but requires more complex actor body implementations.

Concurrent Ruby provides several high-level abstractions for managing asynchronous tasks:

• Async: A mixin module for providing simple asynchronous behavior to a class (inspired by Erlang's gen_server).
• ScheduledTask: A task scheduled to run at a specific future time.
• TimerTask: A thread that periodically performs work at regular intervals.
• Promises: A unified, non-blocking, and lock-free framework that replaces Future, Promise, IVar, Event, dataflow, and Delay. It is the recommended way to handle asynchronous values and dependencies.

Promises allow non-blocking task composition:

• .then { |val| ... }: Executes the block only if the preceding future is fulfilled. The result of the previous future is passed as an argument.
• .chain { |fulfilled, value, reason| ... }: Executes the block regardless of whether the preceding future was fulfilled or rejected. The block receives the status, the value (if fulfilled), and the reason (if rejected).
• .rescue { |err| ... }: Executes the block only if the preceding future is rejected. This is used to recover from errors and return a new fulfilled value.

The Top Stock example demonstrates how to concurrently fetch stock data from the Alpha Vantage service to determine which stock had the highest closing price in a given year.

To run this example, you must first obtain a free API key from Alpha Vantage. Then, execute the script from the root of the repository providing your key via the ALPHAVANTAGE_KEY environment variable.

$ ALPHAVANTAGE_KEY=YOUR_API_KEY bundle exec ruby top-stock-scala/top-stock.rb

The project follows Semantic Versioning (SemVer) with specific rules for its components:

• concurrent-ruby: Uses standard Semantic Versioning.
• concurrent-ruby-ext: Always matches the version of concurrent-ruby.
• concurrent-ruby-edge: Uses 0.y.z versioning. While it follows SemVer, minor version increments indicate incompatible changes, and patch increments indicate compatible changes. Because it is in initial development, the public API is not considered stable and may change at any time.

The Concurrent::Promises::FactoryMethods module provides constructor methods for creating Future and Event objects. Instead of direct inheritance, use composition by including or extending this module.

By default, Concurrent::Promises is already extended with these methods. You can also override the default_executor within a module that extends FactoryMethods to change the execution context for tasks created via that module.

# Including in a class
Class.new do
  include Concurrent::Promises::FactoryMethods
  def a_method
    resolvable_event
  end
end.new.a_method

# Extending a module and overriding the executor
mod = Module.new do
  extend Concurrent::Promises::FactoryMethods
  def self.default_executor
    :fast
  end
end 
mod.future { 1 }.default_executor # => :fast

When spawning an actor, choose a type based on your scale requirements:

• :on_thread: The receive method blocks the actor's thread until a message is available. This is simpler to write but each actor consumes a full Ruby thread. Use this for a small number of actors.
• :on_pool: The receive method returns immediately, freeing the thread back to a pool. You must provide a block (or blocks) to receive that acts as a continuation to be executed when a message arrives. This is much more efficient for hundreds or thousands of short-lived actors as it is limited by RAM rather than thread count.