Ruby Multithreading & Concurrency

Concurrency is about dealing with many things at once (structure). Parallelism is about doing many things at once (execution). You can have concurrency without parallelism.

Visual: Concurrency (1 CPU core, 2 threads)

Time ──────────────────────────────────────▶
Thread A: ████░░░░████░░░░████░░░░
Thread B: ░░░░████░░░░████░░░░████
          ^switch ^switch ^switch
          (CPU switches between them rapidly)

Visual: Parallelism (2 CPU cores, 2 threads)

Time ──────────────────────▶
Core 1 — Thread A: ████████████
Core 2 — Thread B: ████████████
                   (truly simultaneous!)

Ruby Code: Concurrent threads (I/O bound)

Copy# Two threads fetching data "at the same time"
# They don't run in parallel (GIL), but while
# thread A waits for I/O, thread B can run.

require 'net/http'

t1 = Thread.new { Net::HTTP.get(URI("https://api.example.com/users")) }
t2 = Thread.new { Net::HTTP.get(URI("https://api.example.com/orders")) }

result1 = t1.value  # blocks until t1 finishes, returns result
result2 = t2.value

puts "Both fetched!"

Key Rule

• I/O-bound work (HTTP calls, DB queries, file reads) → threads help, even with GIL
• CPU-bound work (image processing, encryption) → threads DON'T help in CRuby; use processes or Ractor

Thread Lifecycle States

  Thread.new
      │
      ▼
  ┌─────────┐   scheduled    ┌─────────┐
  │  sleep  │◄──────────────►│  run    │
  │(waiting)│                │(active) │
  └─────────┘                └────┬────┘
                                  │ finish / kill
                             ┌────▼────┐
                             │  dead   │
                             └─────────┘

  status: "sleep" | "run" | "aborting" | false (dead) | nil (not started)

Creating & Running Threads

Copy# Thread.new — create + start immediately
t = Thread.new do
  puts "Worker started (Thread ID: #{Thread.current.object_id})"
  sleep 1
  puts "Worker done"
end

puts "Main thread keeps running..."
t.join   # Wait for t to finish before continuing
puts "All done!"

# Thread.new with arguments
t = Thread.new("Alice", 3) do |name, count|
  count.times { puts "Hello from #{name}" }
end
t.join

Key Thread Methods

Collecting Results from Multiple Threads

Copy# Map pattern — spawn N threads, collect results
urls = ["https://a.com", "https://b.com", "https://c.com"]

threads = urls.map do |url|
  Thread.new { fetch(url) }  # returns thread
end

results = threads.map(&:value)  # wait for all, collect return values
puts results.inspect

Thread Exceptions

Copy# By default, exceptions in threads are SILENT!
t = Thread.new { raise "Something broke!" }
t.join  # Re-raises the exception here — you MUST join to catch it

# OR set globally
Thread.abort_on_exception = true  # crash main thread if any thread crashes

# OR per thread
t = Thread.new { raise "oops" }
t.abort_on_exception = true

CRuby (MRI) uses a Global Interpreter Lock: a mutex that ensures only one thread executes Ruby bytecode at a time. This makes CRuby simpler and thread-safe internally, but limits CPU parallelism.

Visual: GIL in Action

CPU Core 1    CPU Core 2
     │              │
 Thread A      Thread B
     │              │
  [grab GIL]        │    ← Thread B must wait
  runs Ruby         │
  releases GIL      │
     │         [grab GIL]
     │          runs Ruby
     │          releases GIL
     ▼              ▼
  (threads take TURNS — never truly parallel in CRuby)

The I/O Exception: Why Threads Still Help

When a thread does I/O (reading a file, waiting for an HTTP response, querying a database), it releases the GIL while waiting. This means other threads can run Ruby during that wait.

Thread A:  [GIL]──run──[release GIL: waiting for DB]──────────[GIL]──run──▶
Thread B:            [GIL]──run──[release GIL: HTTP wait]────[GIL]──run──▶
                      ↑ Thread B grabs GIL while A waits for DB!

Copy# I/O bound: threads help! (GIL released during sleep/IO)
require 'benchmark'

def io_work = sleep(0.5)  # simulates DB query or HTTP call

# Sequential: 2 seconds total
Benchmark.measure { 4.times { io_work } }  # ~2.0s

# Concurrent with threads: ~0.5 seconds total
Benchmark.measure {
  threads = 4.times.map { Thread.new { io_work } }
  threads.each(&:join)
}  # ~0.5s — huge speedup!

# CPU bound: threads DON'T help (GIL is held)
def cpu_work = 10_000_000.times { }  # pure Ruby computation
# Sequential and threaded take the same time

Alternatives for True Parallelism

A race condition happens when the outcome of code depends on the unpredictable order in which threads execute. It's one of the hardest bugs to reproduce because it's timing-dependent.

Classic Example: Broken Counter

Copycounter = 0
threads = 1000.times.map do
  Thread.new { counter += 1 }
end
threads.each(&:join)
puts counter  # Expected: 1000. Actual: often 950-999!

Why Does This Happen? (Read-Modify-Write)

The line counter += 1 is NOT atomic — it's three separate steps:

counter += 1  is actually:
  Step 1: READ  counter  (gets 5)
  Step 2: ADD   5 + 1    (gets 6)
  Step 3: WRITE counter = 6

Thread A            Thread B
READ  counter → 5
                    READ  counter → 5  ← B reads BEFORE A writes!
ADD  5 + 1 = 6
WRITE counter = 6
                    ADD  5 + 1 = 6
                    WRITE counter = 6  ← Both wrote 6 instead of 7!

Check-Then-Act Bug

Copy# Dangerous: check and act are not atomic
def withdraw(account, amount)
  if account.balance >= amount    # Thread A checks: balance = 100, amount = 80 ✓
    # --- Thread B runs here: also checks 100 >= 80 ✓, withdraws 80 ---
    account.balance -= amount     # Thread A now withdraws 80: balance = -60 !!!
  end
end

Signs of Race Conditions

• Bug only happens under high load or in production
• Bug disappears when you add logging (Heisenbug)
• Results are "almost right" — off by a few, not completely wrong
• Tests pass individually but fail when run in parallel

Solution: Use Mutex (next topic) to make read-modify-write operations atomic.

A Mutex (Mutual Exclusion lock) is a flag that only one thread can hold at a time. While a thread holds the mutex, all other threads trying to acquire it will wait until it's released.

Visual: Mutex Protecting a Counter

Thread A: ──[ wants lock ]──[  HOLDS LOCK  ]──[ releases ]──────────────▶
Thread B: ──────────────────[ waiting... ]───[ HOLDS LOCK ]──[ releases ]▶
                              ↑ blocked until A releases

Basic Mutex Usage

Copymutex = Mutex.new
counter = 0

threads = 1000.times.map do
  Thread.new do
    mutex.synchronize do   # Only one thread runs this block at a time
      counter += 1         # Now safe!
    end
  end
end

threads.each(&:join)
puts counter  # => Always exactly 1000

Manual lock / unlock (avoid this pattern)

Copymutex = Mutex.new

mutex.lock    # Grab the lock (blocks if already held)
begin
  # critical section
  counter += 1
ensure
  mutex.unlock  # ALWAYS release, even if exception!
end

# synchronize { } is better — it handles the ensure automatically

try_lock — Non-blocking Attempt

Copymutex = Mutex.new

if mutex.try_lock
  begin
    do_work  # got the lock, do work
  ensure
    mutex.unlock
  end
else
  puts "Lock was busy, skipping..."  # didn't block
end

Real-World: Thread-Safe Bank Account

Copyclass BankAccount
  def initialize(balance)
    @balance = balance
    @mutex = Mutex.new
  end

  def deposit(amount)
    @mutex.synchronize { @balance += amount }
  end

  def withdraw(amount)
    @mutex.synchronize do
      raise "Insufficient funds" if @balance < amount
      @balance -= amount
    end
  end

  def balance
    @mutex.synchronize { @balance }  # Even reads can need protection
  end
end

account = BankAccount.new(1000)
threads = 50.times.map { Thread.new { account.deposit(10) } }
threads.each(&:join)
puts account.balance  # => Always 1500

Rules for Mutex

• Never call mutex.lock twice from the same thread — it deadlocks (use Monitor instead)
• Keep critical sections as short as possible — holding a mutex blocks all other threads
• Always use synchronize { } over manual lock/unlock for safety

A Monitor is a re-entrant mutual exclusion mechanism. Unlike Mutex, the same thread can acquire the monitor's lock multiple times without deadlocking itself. It also provides condition variables for thread coordination.

Mutex deadlock vs Monitor safety

Copyrequire 'monitor'

# DANGER with Mutex — re-entrancy causes deadlock:
mutex = Mutex.new
mutex.synchronize do
  mutex.synchronize { }  # => DEADLOCK! (locks itself)
end

# SAFE with Monitor — re-entrant:
monitor = Monitor.new
monitor.synchronize do
  monitor.synchronize { puts "No deadlock!" }  # fine!
end

MonitorMixin — Add to Any Class

Copyrequire 'monitor'

class SafeCache
  include MonitorMixin  # adds synchronize, new_cond, etc.

  def initialize
    super  # must call super to init MonitorMixin
    @data = {}
  end

  def fetch(key)
    synchronize { @data[key] }
  end

  def store(key, value)
    synchronize { @data[key] = value }
  end

  # A method that calls other synchronized methods safely
  def fetch_or_store(key, default)
    synchronize do
      @data[key] ||= default  # calls synchronize internally — OK because re-entrant
    end
  end
end

Condition Variables — Coordinating Threads

A condition variable lets a thread wait until a specific condition is true, then another thread can signal it to wake up. This is the foundation of the producer-consumer pattern.

Copyrequire 'monitor'

monitor = Monitor.new
cond    = monitor.new_cond  # condition variable tied to this monitor
queue   = []

# Consumer thread — waits until there's data
consumer = Thread.new do
  monitor.synchronize do
    cond.wait_while { queue.empty? }  # releases lock + sleeps until signaled
    puts "Got: #{queue.shift}"
  end
end

sleep 0.5  # let consumer start waiting

# Producer thread — adds data then signals
producer = Thread.new do
  monitor.synchronize do
    queue << "hello!"
    cond.signal  # wake up the waiting consumer
  end
end

[consumer, producer].each(&:join)

When to Use Monitor over Mutex

Thread-local variables store data that is private to a specific thread. Every thread has its own independent value for the same key. Changes in one thread never affect another thread's value.

Syntax: Reading and Writing

Copy# Set a thread-local variable
Thread.current[:user_id] = 42

# Read it back
puts Thread.current[:user_id]  # => 42

# In a different thread, it's nil (independent!)
t = Thread.new do
  puts Thread.current[:user_id]  # => nil (different thread!)
  Thread.current[:user_id] = 99
  puts Thread.current[:user_id]  # => 99
end
t.join

puts Thread.current[:user_id]  # => still 42 (main thread unaffected)

# Check which keys exist for current thread
Thread.current.keys  # => [:user_id]

# Delete a key
Thread.current[:user_id] = nil

Real-World: Current User in Web Request

Rails and Rack middleware use thread-local storage to track the current request's user without passing it everywhere as an argument:

Copy# Middleware sets the current user at the start of each request
class CurrentUserMiddleware
  def call(env)
    user = authenticate(env)
    Thread.current[:current_user] = user    # store for this request's thread
    @app.call(env)
  ensure
    Thread.current[:current_user] = nil     # clean up after request!
  end
end

# Anywhere in the app during that request:
module Current
  def self.user
    Thread.current[:current_user]
  end
end

# Usage:
Current.user  # => #

Fiber-Local vs Thread-Local

Copy# Thread[] is actually FIBER-LOCAL in Ruby 3!
# Within the SAME thread but different fibers, values differ.

# For truly thread-local (shared across fibers in same thread):
Thread.current.thread_variable_set(:session_id, "abc")
Thread.current.thread_variable_get(:session_id)  # => "abc"

# Fiber-local (default Thread[:key] behavior):
Thread.current[:request_id] = "req-1"  # isolated per fiber

Fibers are lightweight coroutines that let you pause and resume execution manually. Unlike threads (preemptive), fibers yield control explicitly with Fiber.yield. They run on a single OS thread — there's no parallelism, just controlled interleaving.

Visual: Thread vs Fiber Switching

Threads (OS decides when to switch):
  Thread A: ▓▓▓▓░░░░▓▓▓░░░░▓▓▓▓▓░  ← OS interrupts at any point
  Thread B: ░░░░▓▓▓▓░░░▓▓▓▓░░░░░▓

Fibers (YOU decide when to switch):
  Fiber A:  ▓▓▓▓.yield.░░░░.resume.▓▓▓▓  ← switches only at yield/resume
  Fiber B:  ░░░░.resume.▓▓▓.yield.░░░░░

Basic Fiber API

Copyfiber = Fiber.new do
  puts "Step 1"
  Fiber.yield         # Pause here, return control to caller
  puts "Step 2"
  Fiber.yield "hello" # Pause, send "hello" back to caller
  puts "Step 3"
  "done"              # Final return value
end

fiber.resume          # => prints "Step 1", returns nil
fiber.resume          # => prints "Step 2", returns "hello"
result = fiber.resume # => prints "Step 3", returns "done"

fiber.resume          # => FiberError: dead fiber called

Passing Values In and Out

Copyfiber = Fiber.new do |first_value|
  puts "Got: #{first_value}"          # "Got: hello"
  second = Fiber.yield "first yield"  # sends "first yield" to caller, gets next resume arg
  puts "Got: #{second}"               # "Got: world"
  "all done"
end

r1 = fiber.resume("hello")   # => "first yield"
r2 = fiber.resume("world")   # => "all done"

Fibers as Generators (Infinite Sequences)

Copy# Generate Fibonacci numbers lazily
fibonacci = Fiber.new do
  a, b = 0, 1
  loop do
    Fiber.yield a
    a, b = b, a + b
  end
end

10.times { print "#{fibonacci.resume} " }
# => 0 1 1 2 3 5 8 13 21 34

Fibers Power Enumerator

Copy# Ruby's Enumerator uses Fibers internally
enum = Enumerator.new do |yielder|
  yielder << "first"
  yielder << "second"
  yielder << "third"
end

enum.next  # => "first"
enum.next  # => "second"
enum.next  # => "third"

Thread vs Fiber Comparison

Queue is Ruby's built-in, thread-safe FIFO (first-in, first-out) data structure. It's the safest way to pass data between threads without needing a Mutex yourself.

Queue API

Copyq = Queue.new

# Add items (non-blocking)
q.push("item1")       # alias: q << "item1", q.enq("item1")

# Remove items — BLOCKS if empty (waits for producer to add something)
item = q.pop           # alias: q.deq, q.shift

# Non-blocking pop (raises ThreadError if empty)
item = q.pop(non_block = true)

# Inspection
q.size     # => number of items
q.empty?   # => true/false
q.length   # alias for size
q.clear    # remove all items

# Signal "no more work" by closing
q.close
q.closed?  # => true
# After closing, pop returns nil once queue drains

Producer-Consumer Pattern

Copyqueue = Queue.new

# Producer thread: generates work items
producer = Thread.new do
  10.times do |i|
    queue.push("job_#{i}")
    puts "Produced job_#{i}"
    sleep 0.1
  end
  queue.close  # signal: no more jobs coming
end

# Consumer threads: process work items
consumers = 3.times.map do |id|
  Thread.new do
    while (job = queue.pop)  # returns nil when queue closed + empty
      puts "Worker #{id} processing #{job}"
      sleep 0.2  # simulate work
    end
    puts "Worker #{id} done"
  end
end

producer.join
consumers.each(&:join)
puts "All done!"

SizedQueue — Bounded Buffer

A SizedQueue has a maximum capacity. Producers block when the queue is full, preventing unbounded memory growth.

Copysized_q = SizedQueue.new(5)  # max 5 items

# Same API as Queue, but push blocks when full:
producer = Thread.new do
  20.times do |i|
    sized_q.push(i)           # blocks here if queue has 5 items
    puts "Pushed #{i}"
  end
  sized_q.close
end

consumer = Thread.new do
  while (item = sized_q.pop)
    puts "Processing #{item}"
    sleep 0.1
  end
end

[producer, consumer].each(&:join)

Queue vs SizedQueue vs Array (don't use Array!)

A thread pool pre-creates N threads and reuses them. Creating threads is expensive (time + memory). A pool caps resource usage and handles bursts gracefully.

Simple Thread Pool from Scratch

Copyclass ThreadPool
  def initialize(size)
    @size = size
    @queue = Queue.new
    @workers = size.times.map { spawn_worker }
  end

  def submit(&task)
    @queue.push(task)
  end

  def shutdown
    @size.times { @queue.push(nil) }  # nil = signal to stop
    @workers.each(&:join)
  end

  private

  def spawn_worker
    Thread.new do
      loop do
        task = @queue.pop
        break if task.nil?    # nil is shutdown signal
        task.call
      end
    end
  end
end

pool = ThreadPool.new(4)

20.times do |i|
  pool.submit { puts "Job #{i} on #{Thread.current.object_id}" }
end

pool.shutdown
puts "All jobs complete"

concurrent-ruby Gem (Production-Ready)

Copy# gem 'concurrent-ruby'
require 'concurrent'

# Fixed thread pool (exactly N threads always running)
pool = Concurrent::FixedThreadPool.new(10)

50.times do |i|
  pool.post { puts "Task #{i} on thread #{Thread.current.object_id}" }
end

pool.shutdown
pool.wait_for_termination

# Cached pool (grows as needed, shrinks when idle)
pool = Concurrent::CachedThreadPool.new

# Future — async result with promise-like API
future = Concurrent::Future.execute { expensive_computation }
future.value   # blocks until result is ready
future.value!  # blocks and re-raises exception if one occurred

# Async — fire and forget
Concurrent::Future.execute { send_email }  # runs in background

When to Use a Thread Pool

• Processing many short I/O tasks (API calls, DB queries)
• Background job workers (like Sidekiq's internal model)
• Parallelizing batch operations (import files, send emails)
• Any place you'd otherwise call Thread.new in a loop

Visual: Classic Two-Lock Deadlock

Thread A:  [has Lock1]──[waiting for Lock2]──FOREVER
Thread B:  [has Lock2]──[waiting for Lock1]──FOREVER
                ↑ Circular wait = DEADLOCK

Deadlock in Code

Copylock_a = Mutex.new
lock_b = Mutex.new

thread_a = Thread.new do
  lock_a.synchronize do       # Grabs Lock A
    sleep 0.01                # Let Thread B grab Lock B
    lock_b.synchronize do     # Waits for Lock B... forever
      puts "Thread A done"
    end
  end
end

thread_b = Thread.new do
  lock_b.synchronize do       # Grabs Lock B
    sleep 0.01
    lock_a.synchronize do     # Waits for Lock A... forever
      puts "Thread B done"
    end
  end
end

thread_a.join
thread_b.join
# => fatal: No live threads left. Deadlock? (RuntimeError)

Ruby detects deadlocks automatically and raises a fatal error: "No live threads left. Deadlock?"

Prevention Strategy 1: Consistent Lock Ordering

Copy# ALWAYS acquire locks in the same order everywhere
# If every thread grabs A then B (never B then A), deadlock is impossible.

def transfer(from_account, to_account, amount)
  # Sort by object_id to ensure consistent order
  first, second = [from_account, to_account].sort_by(&:object_id)

  first.mutex.synchronize do
    second.mutex.synchronize do
      from_account.withdraw(amount)
      to_account.deposit(amount)
    end
  end
end

Prevention Strategy 2: Timeout with try_lock

Copydef try_transfer(lock_a, lock_b)
  # Try to acquire both locks with a timeout
  deadline = Time.now + 1.0  # 1 second max

  loop do
    if lock_a.try_lock
      if lock_b.try_lock
        begin
          yield  # do work
          return true
        ensure
          lock_b.unlock
          lock_a.unlock
        end
      else
        lock_a.unlock
      end
    end

    if Time.now > deadline
      raise "Could not acquire locks — possible deadlock"
    end
    Thread.pass  # let other threads run
  end
end

Deadlock vs Livelock vs Starvation

Ractors (Ruby 3.0+) are Ruby's answer to true parallelism. Each Ractor has its own GIL, meaning Ractors can run genuinely parallel on multiple CPU cores. The catch: they communicate only via message passing, not shared memory.

Visual: Ractors vs Threads

Threads (shared memory, GIL):
  Thread A ──┐
  Thread B ──┼── Shared heap (GIL: one at a time)
  Thread C ──┘

Ractors (isolated, no GIL between them):
  Ractor A [its own memory] ──message──▶ Ractor B [its own memory]
  Ractor C [its own memory] ══ runs on Core 2 simultaneously! ═══▶

Basic Ractor API

Copy# Create a Ractor and send it work
r = Ractor.new do
  number = Ractor.receive   # Wait for a message
  number * number            # Return value
end

r.send(7)          # Send a message to the ractor
result = r.take    # Wait and receive the result
puts result        # => 49

Parallel CPU Work (beats threads!)

Copy# CPU-bound task in parallel using Ractors
def is_prime?(n)
  return false if n < 2
  (2..Math.sqrt(n)).none? { |i| n % i == 0 }
end

numbers = [999_999_937, 1_000_000_007, 999_999_893, 1_000_000_033]

ractors = numbers.map do |n|
  Ractor.new(n) { |num| [num, is_prime?(num)] }
end

results = ractors.map(&:take)
results.each { |n, prime| puts "#{n}: #{prime ? 'prime' : 'not prime'}" }
# These run on multiple CPU cores simultaneously!

Shareable Objects (What You Can Share)

Copy# Ractors can ONLY share "shareable" objects:
# - Frozen (immutable) objects
# - Integers, Symbols, true/false/nil (always shareable)
# - Ractor.make_shareable(obj)

CONST = "shared string".freeze  # frozen strings are shareable

r = Ractor.new do
  Ractor.receive  # receive unshareable objects via message (they get MOVED)
end

# move: true — transfers ownership (original can no longer use it)
data = { key: "value" }
r.send(data, move: true)
# data is now unusable in the main Ractor

Ractor Pipeline

Copy# Multi-stage pipeline: generator → processor → printer
generator = Ractor.new do
  5.times { |i| Ractor.yield i }
end

processor = Ractor.new(generator) do |gen|
  loop { Ractor.yield gen.take * 10 }
end

5.times { puts processor.take }  # => 0, 10, 20, 30, 40

Ractor Limitations (Experimental in Ruby 3.x)

• Most stdlib classes are NOT Ractor-safe yet (ActiveRecord, etc.)
• Accessing global variables raises Ractor::IsolationError
• Complex objects must be frozen or moved, not shared
• Still experimental — API may change

Ruby 3.0 introduced the Fiber Scheduler interface — a hook that lets gems replace Ruby's blocking I/O with non-blocking I/O, all while keeping synchronous-looking code. The async gem implements this scheduler.

Traditional Threads vs Async Fibers

1000 concurrent HTTP requests:

Threads: 1000 threads × ~1MB stack = ~1GB memory!
         Slow to create, expensive context switching

Async Fibers: 1000 fibers × ~4KB stack = ~4MB memory!
              No OS context switch — pure Ruby scheduling

Fiber Scheduler (Ruby 3.0+)

Copy# Ruby 3.0+ built-in: Fiber scheduler interface
# Set a scheduler to make I/O non-blocking for fibers
# The 'async' gem provides a production scheduler

require 'async'

Async do
  # Each 'Async { }' block is a Fiber managed by the scheduler
  task1 = Async { sleep 1; "task1 done" }  # non-blocking sleep!
  task2 = Async { sleep 1; "task2 done" }  # runs concurrently

  puts task1.wait  # => "task1 done" (after ~1s, not 2s!)
  puts task2.wait  # => "task2 done" (both ran at the same time!)
end

Async HTTP Requests

Copy# gem 'async-http'
require 'async'
require 'async/http/internet'

Async do
  internet = Async::HTTP::Internet.new

  # Fire all requests concurrently — none blocks the others
  tasks = ["https://api.a.com", "https://api.b.com", "https://api.c.com"].map do |url|
    Async { internet.get(url) }
  end

  responses = tasks.map(&:wait)
  puts "Got #{responses.size} responses"

  internet.close
end

How the Fiber Scheduler Works

Event Loop (single thread):

Fiber A: START──[io: wait for HTTP]──────────────────[resume: got data]──END
Fiber B:        [io: wait for DB]──────────[resume: got rows]──END
Fiber C:               [io: file read]──[resume: file ready]──END
         ↑ Event loop detects I/O readiness and resumes the right fiber

Built-in Non-blocking Support (Ruby 3.x)

Copy# With a scheduler set, these become non-blocking automatically:
# - IO#read, IO#write
# - Socket operations
# - Process.wait
# - Kernel#sleep
# - Mutex#lock (when waiting)

# Ruby 3 exposes the interface:
class MyScheduler
  def io_wait(io, events, timeout)
    # Your event-loop logic here (usually handled by 'async' gem)
  end
  # + fiber_schedule, block, unblock, kernel_sleep, etc.
end

Fiber.set_scheduler(MyScheduler.new)

When to Use Async

Puma: The Multi-Process × Multi-Thread Server

Puma Architecture:

  ┌─────────────────────────────────────────────┐
  │  Master Process                             │
  │  ┌───────────┐  ┌───────────┐  ┌─────────┐ │
  │  │ Worker 1  │  │ Worker 2  │  │Worker 3 │ │
  │  │ (process) │  │ (process) │  │(process)│ │
  │  │ T1 T2 T3  │  │ T1 T2 T3  │  │T1 T2 T3 │ │
  │  └───────────┘  └───────────┘  └─────────┘ │
  └─────────────────────────────────────────────┘
  workers × threads = max concurrent requests
  e.g. 3 workers × 5 threads = 15 concurrent requests

Copy# config/puma.rb
workers ENV.fetch("WEB_CONCURRENCY") { 2 }   # processes (forked)
threads_count = ENV.fetch("RAILS_MAX_THREADS") { 5 }
threads threads_count, threads_count          # min, max threads per worker

preload_app!  # load app before forking (copy-on-write friendly)

on_worker_boot do
  ActiveRecord::Base.establish_connection  # each worker needs its own DB pool
end

Sidekiq: Thread Pool of Workers

Copy# Sidekiq runs a configurable thread pool (default: 10 threads)
# Each thread picks a job from Redis and processes it

# config/sidekiq.yml
# concurrency: 10   ← 10 threads, 10 jobs at once

class OrderMailerJob
  include Sidekiq::Job

  def perform(order_id)
    order = Order.find(order_id)  # Each thread uses its own DB connection
    OrderMailer.shipped(order).deliver_now
  end
end

# Enqueue from anywhere:
OrderMailerJob.perform_async(order.id)

Thread Safety in Rails

Copy# Rails itself is thread-safe since Rails 4.
# But YOUR code must be too. Common mistakes:

# ❌ UNSAFE: class-level mutable state
class ReportGenerator
  @@current_user = nil  # shared across all threads!
  def generate(user)
    @@current_user = user  # Thread A sets this...
    build_report           # Thread B changes it before we use it!
  end
end

# ✅ SAFE: use thread-local or pass as argument
class ReportGenerator
  def generate(user)
    Thread.current[:report_user] = user  # thread-local
    build_report
  ensure
    Thread.current[:report_user] = nil
  end
end

# ✅ SAFE: Rails' built-in CurrentAttributes (thread-local under the hood)
class Current < ActiveSupport::CurrentAttributes
  attribute :user  # automatically thread-local and reset per request
end

Current.user = User.find(session[:user_id])
Current.user  # accessible anywhere in this request

ActiveRecord Connection Pool

Copy# Each thread needs its own DB connection
# ActiveRecord manages a connection pool automatically

# config/database.yml
# pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
# pool size should match your thread count!

# Rails checks out connections per-thread automatically
# If pool is exhausted, threads wait (or raise ActiveRecord::ConnectionTimeoutError)

# Manual checkout (rare):
ActiveRecord::Base.connection_pool.with_connection do |conn|
  conn.execute("SELECT 1")
end

Web Server Comparison