Skip to content
Tutorials Center
My learning

Topics

Lesson 99 of 134 ยท Concurrency

Parallelism and Ractors

Understand the Ruby GVL and learn when to use threads, Ractors or processes to use more than one CPU core. Includes Ractor-safe code rules and a decision guide.

Your computer has several CPU cores, but a plain Ruby program usually uses only one of them at a time. That surprises many people, because Ruby has had threads for decades. The reason is a lock inside the interpreter, and understanding it is the key to choosing the right tool: threads for waiting, Ractors or processes for computing.

This lesson explains what the lock does and does not prevent, shows how to split CPU-heavy work across Ractors, lists what makes code Ractor-safe, and then compares Ractors with processes so that you can pick the right one. If you have not seen them yet, read Threads, Mutex, Queue and ConditionVariable and Ractors first.

Our code runner gives every program one CPU core. You will not see programs get faster here, and we deliberately never print timings. Every example below checks that the answers are correct. On your own multi-core machine the same code can run in parallel.

Concurrency is not parallelism

Two words get mixed up all the time.

  • Concurrency means several jobs are in progress at once. They may take turns on a single core.
  • Parallelism means several jobs are running at the same instant on different cores.

A cook who chops onions while the soup simmers is concurrent. Two cooks working in two kitchens are parallel. Ruby threads give you concurrency for sure. Whether they also give you parallelism depends on what the threads are doing.

The GVL in one minute

The reference Ruby interpreter (CRuby) has a Global VM Lock, usually called the GVL. Only the thread that holds the GVL may execute Ruby code. A thread gives it up in two situations:

  1. It starts a blocking operation, such as reading from a socket, sleeping, or waiting for a child process. While it waits, another thread takes the lock.
  2. The interpreter's timer decides it has had its turn, and passes the lock on.

The consequence is simple. I/O-bound work gets faster with threads, CPU-bound work does not. Ten threads waiting for ten web servers overlap their waiting. Ten threads adding up numbers still run one after another.

Ruby Threads overlap waiting, not computing

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Sleeping ten times for 0.1 seconds takes about 0.1 seconds in total, not a full second, because sleeping releases the GVL. The prime counting, in contrast, keeps the lock busy: two threads computing take about as long as one thread doing both halves. The check elapsed < 0.5 prints true without us ever showing a time, so the output stays stable on any machine.

The GVL also protects the interpreter's own data structures, which is why single operations such as Array#push are safe in CRuby. It does not make your own multi-step logic safe. counter += 1 is a read, an add and a write, and a thread switch can land in the middle. Use a Mutex for that, as shown in Mutex, Queue and ConditionVariable.

Splitting CPU work across Ractors

A Ractor has its own GVL, so Ractors really can execute Ruby code on separate cores. The price is isolation: a Ractor shares no mutable objects with the others and talks through messages.

The classic recipe for CPU-bound work is split, compute, combine:

  1. Cut the input into chunks, one per worker.
  2. Start one Ractor per chunk and hand it its chunk as an argument.
  3. Call value on each Ractor and combine the partial results.
Ruby Count primes with four Ractors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Notice that the Ractor block repeats the counting loop instead of reading the variables from and to or the chunks array from the code around it. Every value the block uses must arrive as an argument. Here lo and hi are small integers, which are always shareable. The sequential count_primes call at the end only serves to prove that the parallel answer is right.

The answer is identical to the sequential run. On a four-core machine the Ractor version can finish in roughly a quarter of the time, plus the start-up cost of the Ractors. That overhead is the reason you split into a few large chunks rather than thousands of tiny jobs.

Collecting results as they finish

value waits for one specific Ractor. If you would rather handle results in the order they finish, let every worker send its answer to a shared Ractor::Port, as described in Ractors. The main Ractor then reads the port once per worker and sorts or merges.

Ruby Merging results from a port

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Arrival order is not predictable, so the program sorts before printing. That habit is worth keeping in every concurrent program you write: make the output independent of scheduling.

What makes code Ractor-safe

Code is Ractor-safe when it touches only data that the running Ractor owns or that is shareable (deeply frozen, or a number, symbol, class or module). The rules you will meet most often:

Pattern Inside a non-main Ractor
Local variables from outside the block Not allowed: pass them as arguments
Global variables ($counter) Ractor::IsolationError
Constants holding unfrozen objects Ractor::IsolationError when read
Class-level instance variables (@count on a class) Ractor::IsolationError on access
Class variables (@@count) Ractor::IsolationError
Deeply frozen constants (Ractor.make_shareable) Fine
Methods and classes defined at the top level Fine, if they only use safe data

Here is a typical trap: a helper that caches results in a class variable. Everything works in the main Ractor and breaks the moment you move it into a worker.

Ruby A class variable cache breaks inside a Ractor (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

The run prints 144 and then Ractor::IsolationError with the message can not access class variables from non-main Ractors (@@cache from Squarer). The class variable is shared state, so a second Ractor may not touch it. The fix is to keep the cache inside the Ractor (a local variable that lives and dies with it), or to drop the cache.

Ruby Keep mutable state inside the Ractor

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

The shareable CONFIG is read by the worker, and the mutable cache is created and used by the worker alone. This split, shared read-only data plus private mutable data, is the design that Ractors reward.

Most gems were written long before Ractors. Many keep state in class variables, globals or lazily filled constants, so they raise Ractor::IsolationError inside a worker. Test every library you depend on before building a Ractor design around it.

Processes: the proven way to use all cores

A process is an operating-system program with its own memory. Two processes cannot trip over each other's variables, and each has its own GVL, so processes give true parallelism today for any Ruby code and any gem. On Unix systems fork creates a copy of the running process cheaply (the memory is copied lazily, "copy on write").

The children have to send their answers back, because memory is not shared. A pipe plus Marshal (Ruby's binary serialization) is the simplest channel.

Ruby Parallel work with fork and pipes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Each child computes its own range and writes the answer to its pipe. The parent reads every pipe, waits for the child with Process.wait and checks the exit status in $?. Processes and Subprocesses goes deeper into fork, Process, Open3 and signals.

Two cautions. fork does not exist on Windows (use Process.spawn or a different design there), and forking a process that has running threads is risky, because only the calling thread survives in the child.

Choosing the right tool

Situation Best choice Why
Many network calls, file reads, database queries Threads (or a Fiber scheduler) Waiting releases the GVL, and threads are cheap
CPU-bound loops on your own simple data Ractors Parallel, no locks, results come back as values
CPU-bound work that uses many gems Processes Everything works; memory is not shared
One-off command-line tools and shell jobs Subprocesses Each tool is already its own program
A web server that must use all cores Several worker processes (Puma, Unicorn) Proven, isolates crashes
Need to share one mutable object Threads and a Mutex Ractors cannot share mutable data

A few rules of thumb that save a lot of pain:

  • Measure first. Profile before parallelizing; the slow part is often an algorithm, not a core count. See Benchmarking.
  • Parallel workers need big jobs. Starting a Ractor or process costs milliseconds; a job must be much bigger than that.
  • Fewer workers than cores. Etc.nprocessors tells you the core count; using a few less leaves room for the main program and the operating system.
  • Return values, do not print. Output from parallel workers interleaves unpredictably; gather results and print them in one place.
Ruby How many cores, and a sensible worker count

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Common mistakes

  • Expecting threads to speed up number crunching. The GVL runs one thread of Ruby code at a time.
  • Parallelizing tiny jobs. Start-up and message-passing costs swamp the gain.
  • Sharing a mutable object between Ractors. It cannot be done; send a copy, move it, or freeze it.
  • Assuming a gem is Ractor-safe. Try it in a small experiment first.
  • Forgetting to wait. Call value or join on Ractors and Process.wait on children, otherwise errors vanish and zombies pile up.
  • Printing from workers. Collect results and print them from the main program.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which workload benefits most from using plain Ruby threads in CRuby?

    A thread that waits for I/O releases the GVL, so other threads can run meanwhile. CPU-bound work keeps the lock busy, so threads add no speed.
  2. 2. Why can two Ractors run Ruby code at the same moment while two threads cannot?

    Isolation lets every Ractor have its own GVL. Because nothing mutable is shared, no global lock is needed between them.
  3. 3. A Ractor block reads a constant that holds an unfrozen array. What happens?

    A constant is only usable from another Ractor when its value is shareable. Wrap it in Ractor.make_shareable when you define it.
  4. 4. You must parallelize CPU-heavy work that relies on several older gems. Which option is safest today?

    Processes run any Ruby code and any gem, each with its own GVL and memory. Many gems are not Ractor-safe yet, and threads cannot run CPU work in parallel.
  5. 5. How should parallel workers report their results in a program whose output must be reproducible?

    Worker output interleaves unpredictably. Returning values lets the main program control the order of what is printed.

Summary

  • CRuby's GVL lets only one thread run Ruby code at a time, so threads help with waiting (I/O) but not with computing.
  • Concurrency means jobs overlap in time; parallelism means they run on several cores simultaneously.
  • Ractors have their own GVL and can run Ruby code in parallel, but they share nothing mutable: pass data in as arguments and get answers back as values.
  • Ractor-safe code avoids globals, class variables and unfrozen constants; use Ractor.make_shareable for read-only shared data.
  • Processes (fork, spawn) give parallelism for any code and any gem, at the cost of copying data through pipes.
  • Pick threads for I/O, Ractors for self-contained CPU work, processes for everything else, and always measure first.

Next: Testing with Minitest