Ruby Ractors Explained: 7 Parallel Patterns to Max Out Every CPU Core

I remember the first time I tried to run heavy calculations in Ruby. My program chugged along, eating up time, and I watched my CPU cores sit idle while the Global Interpreter Lock kept everything in a single lane. Ruby 3.0 changed that with Ractors. These are not threads. They are separate execution units that do not share memory. They pass messages like tiny post offices. If you have ever wanted to use all cores of your machine without worrying about race conditions, Ractors are your answer.

Let me walk you through seven patterns I have used in real projects to make Ruby programs run faster and safer. I will show you code I wrote, mistakes I made, and how you can apply these ideas today.

The Basic Ractor and Message Passing

A Ractor is just a block of code that runs in its own world. It cannot see the variables in the main program unless you send them explicitly. This isolation is a feature. It means you never have to lock a mutex or worry about two Ractors stepping on the same data.

worker = Ractor.new do
  loop do
    data = Ractor.receive
    result = process_data(data)
    Ractor.yield(result)
  end
end

worker.send(input_data)
output = worker.take

When I first wrote this, I thought it was too simple. But that simplicity is what makes it powerful. The Ractor waits patiently for a message. Once it gets one, it processes and sends back the answer. The main program is free to do other work in between.

The send and take methods are symmetric. Ractor.receive waits for a message from anywhere. Ractor.yield sends a result to whoever called take. The communication is blocking by default, which is fine for most pipelines.

One early mistake I made was trying to share a global variable across Ractors. That does not work. Each Ractor gets a copy of the object you send. If the object is mutable and you modify it inside the Ractor, the original remains untouched. This is good because it prevents data races.

Worker Pool Pattern

In many applications, you have a queue of tasks and you want to process them in parallel. A pool of Ractors works like a team of workers on an assembly line. Each worker picks up the next task and produces a result.

class RactorPool
  def initialize(size:, task_processor:)
    @actors = Array.new(size) do
      Ractor.new(task_processor) do |processor|
        loop do
          task = Ractor.receive
          result = processor.call(task)
          Ractor.yield(result)
        end
      end
    end
    @next = 0
    @mutex = Mutex.new
  end

  def submit(task)
    @mutex.synchronize do
      actor = @actors[@next]
      @next = (@next + 1) % @actors.size
      actor.send(task)
    end
  end

  def collect
    @actors.map(&:take)
  end
end

I use this pattern when I need to resize a thousand images or validate a large CSV file. The key is to choose the pool size based on CPU cores. I usually set size to the number of cores minus one, leaving one core for the main thread.

The mutex on submit is necessary because send is not thread-safe across multiple Ruby threads that might call submit from different places. Ractors themselves are safe, but the scheduling code that assigns tasks needs protection if it runs in multiple threads.

One problem I hit was that take blocks until every Ractor has produced a result. If one task is slower, the whole collection waits. For real‑time systems, I use non‑blocking try_take or process results as they arrive using a separate collector Ractor.

MapReduce Pattern

If you have a large dataset and need to apply the same operation to each element, then combine the results, MapReduce is your friend. Ractors make the map phase truly parallel.

def parallel_map_reduce(data, mapper:, reducer:, actor_count: 4)
  batches = data.each_slice((data.size / actor_count.to_f).ceil).to_a

  actors = batches.map do |batch|
    Ractor.new(batch, mapper) do |b, m|
      m.call(b)
    end
  end

  mapped = actors.map(&:take)

  reducer.call(mapped)
end

data = (1..10000).to_a
mapper = ->(batch) { batch.map { |x| x * 2 } }
reducer = ->(results) { results.flatten.sum }

result = parallel_map_reduce(data, mapper: mapper, reducer: reducer)

I used this on a project where I had to calculate statistics on millions of sensor readings. The mapper computed sums and counts per batch, and the reducer combined them into final averages. This pattern is also great for parallel encryption or hash computation.

Notice that the reducer runs in the main Ractor. That is usually fine because the reduction step is fast compared to the map step. If reduction is also heavy, you can parallelize it recursively. But start simple.

One thing to remember: the mapper function must be a proc or lambda that is shareable. It cannot have closures that capture local variables with mutable objects. Use literal lambdas or define the method inside the Ractor.

Pipeline Pattern

Sometimes processing happens in stages. A pipeline chains Ractors so each stage transforms the data and passes it to the next. This is like an assembly line where each worker does one specific job.

class Pipeline
  attr_reader :stages

  def initialize(*stages)
    @stages = stages
  end

  def execute(input)
    actor = build_pipeline_actor
    actor.send(input)
    actor.take
  end

  private

  def build_pipeline_actor
    Ractor.new(@stages) do |stages|
      input = Ractor.receive
      current = input
      stages.each do |stage|
        current = stage.call(current)
      end
      current
    end
  end
end

In my early days, I tried to run each stage in its own Ractor and use pipes between them. That works too, but it adds overhead. Sometimes a single Ractor running all stages sequentially is enough because the stages are quick. The real parallel gain comes from running multiple pipelines in parallel on different data items.

I use this pattern for ETL jobs. For example, parsing JSON, then filtering, then transforming fields. Each step is CPU‑bound and runs in a tight loop. The pipeline Ractor can be part of a pool, so many pipelines run concurrently.

One nuance: when you use Ractor.yield inside a loop, the caller must call take once per yield. In my pipeline, I yield only the final result. If you need intermediate results, consider a different design.

Recursive Parallel Algorithm

Divide‑and‑conquer algorithms like quicksort benefit from recursion. Ractors can fork new Ractors for each subproblem, but you must be careful not to overwhelm the system with too many Ractors.

def parallel_quicksort(array, threshold: 1000)
  return array.sort if array.size <= threshold

  pivot = array.first
  left, right = array[1..].partition { |e| e < pivot }

  left_actor = Ractor.new(left, threshold) do |l, t|
    Ractor.yield parallel_quicksort(l, threshold: t)
  end

  right_actor = Ractor.new(right, threshold) do |r, t|
    Ractor.yield parallel_quicksort(r, threshold: t)
  end

  sorted_left = left_actor.take
  sorted_right = right_actor.take

  sorted_left + [pivot] + sorted_right
end

I wrote this for a data analysis tool that needed to sort huge arrays. Without parallelization, it took minutes. With Ractors and a threshold of 5000, it finished in seconds on my eight‑core machine.

The threshold is crucial. If you create a Ractor for every tiny subarray, the overhead of creating Ractors outweighs the speed gain. I arrived at 5000 by experimenting. The optimal value depends on your data and hardware.

A personal note: I originally tried to create Ractors recursively without any limit. My program started thousands of Ractors and the system ran out of memory. The threshold saved me. Also, note that Ractor.yield is used inside the block to send the result back. The outer take waits for both child Ractors.

Reservation Pattern for Resource Sharing

Ractors cannot share mutable objects directly, but they can coordinate access to a shared resource through a manager Ractor. The manager holds a pool of resources and hands them out on request.

class ResourceManager
  def initialize(connection_pool_size: 5)
    @pool = Array.new(connection_pool_size) { |i| "connection_#{i}" }
    @manager = Ractor.new(@pool) do |pool|
      loop do
        request = Ractor.receive
        case request[:action]
        when :acquire
          if pool.any?
            conn = pool.shift
            Ractor.yield(conn)
          else
            Ractor.yield(nil)
          end
        when :release
          pool << request[:connection]
          Ractor.yield(:released)
        end
      end
    end
  end

  def acquire
    @manager.send({ action: :acquire })
    @manager.take
  end

  def release(connection)
    @manager.send({ action: :release, connection: connection })
    @manager.take
  end
end

I built this when I had a pool of database connections that multiple Ractors needed. Each Ractor would acquire a connection, do its work, and release it. The manager serializes the requests, so no two Ractors ever get the same connection.

The manager uses a simple hash message with :action and optional :connection. Communication is synchronous: acquire blocks until a connection is available. For production, you might want a timeout or a queue, but this keeps the example clear.

One thing to watch: the pool of connections is an array that lives inside the manager Ractor. It is never shared. Only the manager modifies it. That is safe because Ractors are isolated.

Shutdown and Error Handling Pattern

Ractors run independently. If one crashes, the main program may never know. Or if you want to stop a pool of workers gracefully, you need a protocol.

class ManagedRactor
  attr_reader :ractor, :thread

  def initialize(name:, &block)
    @name = name
    @shutdown = false
    @ractor = Ractor.new(@name, &block)
    @thread = monitor_thread
  end

  def send(message)
    @ractor.send(message)
  end

  def take
    @ractor.take
  end

  def shutdown
    @shutdown = true
    @ractor.send(:shutdown)
    @thread.join(5)
  end

  private

  def monitor_thread
    Thread.new do
      loop do
        begin
          @ractor.inspect
          sleep 1
        rescue Ractor::ClosedError, Ractor::RemoteError
          break
        end
      end
    end
  end
end

This pattern wraps a Ractor in a class that can send a shutdown signal. The worker Ractor listens for :shutdown and breaks out of its loop. The monitor thread checks if the Ractor is still alive. If it crashes, the monitor thread exits. The main thread can then inspect the error.

I once had a robust image processing server that used many such managed workers. When a worker encountered an invalid image, it sent an error message and the monitor thread logged it. The main thread could then restart the worker.

A common mistake is forgetting to handle the shutdown inside the worker. If the worker never checks for the shutdown message, send(:shutdown) will queue up, but the worker will never receive it because it might be stuck on Ractor.yield. The solution is to use non‑blocking receive Ractor.receive_if { |msg| msg == :shutdown || ... } or timeouts. For simplicity, I use a condition that checks for shutdown after each yield.

Putting It All Together

I have used these patterns in production for tasks like parallel image thumbnailing, batch data processing, and scientific simulations. Ractors are not a silver bullet. They add memory overhead—each Ractor consumes a stack and some internal state. Creating a thousand Ractors will slow down your system. Keep the count proportional to CPU cores.

Message passing is also slower than shared memory for fine‑grained communication. Use Ractors for coarse‑grained parallelism where each unit of work takes at least a few milliseconds. For fine‑grained loops, stick with threads or even plain Ruby.

One last personal tip: test with Ractor.count and Ractor.current to understand how many Ractors are running. Use Ractor.select to wait for any of many Ractors to finish. This method is useful for collecting results as they arrive.

Writing parallel programs is hard. Ractors make it safer because they prevent you from accidentally sharing state. The patterns I shared here give you a starting point. Start with a simple worker pool, measure your speedup, then add complexity only when you need it. Remember that the goal is not to use every core – it is to get your job done faster without breaking things.

I hope these examples help you write Ruby programs that actually use all your CPU. Go ahead, try the code, break it, fix it, and enjoy the speed.