Skip to content
Tutorials Center
My learning

Topics

Lesson 97 of 134 ยท Concurrency

Fibers and the Fiber Scheduler

Learn how the Ruby Fiber scheduler works: non-blocking fibers, Fiber.schedule, a hand-written scheduler you can run, and what the async gem adds in projects.

A thread is a heavy way to wait. Each one needs its own stack and operating-system bookkeeping, so a program that holds ten thousand idle connections open with ten thousand threads is in trouble. A fiber is a pausable block of code that costs only a few kilobytes, and fibers can pause themselves exactly when they would wait, giving the CPU to another fiber. If that switching happened automatically on every sleep, queue wait and socket read, you could write plain, top-to-bottom code and still serve thousands of waits at once.

That is the idea of the Fiber scheduler, added in Ruby 3.0. It is not a ready-made feature but a small interface: you (or a gem) install a scheduler object, and Ruby calls its methods whenever a non-blocking fiber is about to wait. In this lesson you learn the vocabulary, see the errors you get without a scheduler, then write and run a working scheduler of about thirty lines so the mechanism stops being magic. Finally you see how real projects use the async gem, which is read-only here.

Blocking and non-blocking fibers

Every fiber is either blocking or non-blocking. The main fiber of every thread is blocking. A fiber made with Fiber.new is non-blocking by default, and you can ask for a blocking one with blocking: true.

Ruby Which fibers are blocking?

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.

Fiber.scheduler is nil because we never installed one. blocking? on a fiber answers true or false. The class method Fiber.blocking? is a little odd: it returns false when the current fiber is non-blocking and otherwise a number, the depth of blocking nesting (1 here). Treat any number as "true". The practical rule:

  • With no scheduler installed, nothing changes. sleep blocks the thread, whatever kind of fiber you are in.
  • With a scheduler installed, sleep, Queue#pop, Mutex#lock, socket reads and similar calls inside a non-blocking fiber ask the scheduler to handle the wait. Inside a blocking fiber they block as usual.

Fiber.schedule needs a scheduler

Fiber.schedule { ... } creates a non-blocking fiber, hands it to the scheduler and starts it. Without a scheduler there is no one to hand it to:

Ruby Fiber.schedule with no scheduler (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 program ends with main.rb:1:in 'Fiber.schedule': No scheduler is available! (RuntimeError). Before you can schedule fibers, you must install a scheduler for the current thread with Fiber.set_scheduler. Each thread has its own, and the scheduler is per thread, not global.

What a scheduler must implement

A scheduler is any object that responds to a handful of methods. Ruby checks the essential ones when you install it:

Ruby An object that is not a scheduler

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 answer is ArgumentError: Scheduler must implement #block. The full list for a useful scheduler:

Method When Ruby calls it
fiber(&block) for Fiber.schedule: create a non-blocking fiber, start it, return it
kernel_sleep(duration) the fiber called sleep
block(blocker, timeout) the fiber must wait for something else (a Queue, a Mutex, Thread#join)
unblock(blocker, fiber) the thing it waited for happened, possibly from another thread; the fiber can run again
io_wait(io, events, timeout) the fiber waits for a file or socket to be readable or writable
fiber_interrupt(fiber, exception) a fiber must be woken with an exception, for example during shutdown
close the thread is ending: run everything that is still pending

Others exist (process_wait, timeout_after, address_resolve, io_read...), and they are optional. If a method is missing, the matching call simply blocks the thread as it would without a scheduler.

The key trick is the last row. When a thread whose scheduler is set reaches its end, Ruby calls scheduler.close, and the scheduler's job is to keep running fibers until all are done. That is why you do not write a "main loop" by hand.

A scheduler you can run

Here is a complete scheduler that supports sleep and waiting on queues. It keeps a list of fibers that are ready to run and a list of sleepers with their wake-up times. Read the comments in your head as you go through it: kernel_sleep does not sleep at all, it records "wake me at time T" and yields to whoever resumed the fiber.

Ruby A tiny working Fiber scheduler

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 output shows the pattern: a: start, b: start and c: start appear right away, then the body message, then, about 0.2 seconds later, the three end lines. The three sleeps overlapped inside one thread, with no locks and no extra stacks. If you remove the scheduler, the same code takes 0.6 seconds, because each sleep blocks.

Look at how the pieces fit together:

  1. Fiber.schedule calls fiber, which creates the fiber and resumes it immediately (so a: start prints at once).
  2. The fiber runs until sleep 0.2. Ruby sees a non-blocking fiber with a scheduler and calls kernel_sleep, which stores [wake time, fiber] and does Fiber.yield. Control returns to the code that resumed the fiber, i.e. the schedule call.
  3. The thread's block ends and Ruby calls close, which calls run.
  4. run repeatedly takes the sleeper with the earliest wake time, really sleeps until then (we are back in the thread's blocking main fiber, so this sleep is the real one), and resumes the fiber.

A production scheduler does the same with the operating system's event API (epoll, kqueue, io_uring) instead of a sorted array, and handles thousands of file descriptors in io_wait.

Queues and locks work too

The block and unblock methods are what make Queue#pop, Mutex and Thread#join fiber-friendly. A fiber that calls queue.pop on an empty queue asks the scheduler to block it. Later, when somebody pushes, Ruby calls unblock with that fiber and the scheduler puts it back on the ready list.

The next program uses the same scheduler (repeated so that the example runs on its own, with the details squeezed) and tries three situations: a queue handing a value to a waiting fiber, an exception inside a scheduled fiber, and a fiber that never yields.

Ruby Queues, errors and a greedy fiber

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.

In part 1 the consumer waits (block), the producer sleeps and pushes (unblock), and the consumer then wakes with the value. In part 2, an error raised before the first pause surfaces right at the Fiber.schedule call, because the fiber ran synchronously inside it. An error raised after a pause happens inside the scheduler's run, so it ends the whole thread, and any other fiber still pending is abandoned. Real schedulers wrap each fiber so that one failing task does not kill its neighbours. In part 3 the second fiber had to wait until the first one was completely done, since only a sleep, a queue wait or I/O gives the turn away.

Fibers are cooperative. A scheduler cannot interrupt a fiber that is busy computing. One CPU-heavy task freezes every other fiber on that thread, including your web server's health check. Keep fiber code mostly "waiting" code, and push computation to threads or processes (Processes and Subprocesses).

What the scheduler gives you

Compared with threads:

  • Cheap: a fiber needs a small stack. Programs with tens of thousands of concurrent fibers are realistic; the same number of threads is not.
  • No data races between fibers on one thread: a switch happens only where code waits, so count += 1 cannot be torn in two. You still need to think about invariants across a wait: any state you checked before a sleep or a read may have changed when you come back.
  • Sequential code: no callbacks and no async/await keywords; a method that does I/O looks like a normal blocking method. Libraries that use sleep, sockets or queues work without being rewritten, as long as they do their waiting through Ruby.

Limits:

  • Blocking calls outside Ruby's reach (a C extension that waits on its own, a database driver that blocks a thread inside native code) stall every fiber on the thread. Check that your database library cooperates with the scheduler.
  • One thread by default. For more cores you run a scheduler per thread, or several processes.
  • The ecosystem is a choice you make: the interface is in Ruby, the implementation comes from a gem.

The async gem (read-only)

Nobody writes a scheduler for production; they install one. The best known is the async gem, which supplies a scheduler, a nice task API, timeouts, semaphores, HTTP clients and servers (Falcon). The gem is not available in the browser runner, so the following is a read-only example: it shows what you would write in a normal project with gem "async" in the Gemfile.

Ruby
# read-only example: needs the async gem
require "async"

Async do |task|
  jobs = 3.times.map do |i|
    task.async do
      sleep 1
      "result #{i}"
    end
  end

  puts jobs.map(&:wait).inspect
end
# prints ["result 0", "result 1", "result 2"] after about one second, not three

Async do ... end installs the scheduler for you and runs until the block and all child tasks finish; task.async is the friendlier cousin of Fiber.schedule. The shape is exactly what our tiny scheduler did, plus I/O, timeouts, error propagation between tasks, and many details we skipped.

A second read-only snippet shows what io_wait is for. A real scheduler registers the file descriptor with the operating system and sleeps until it is ready:

Ruby
# read-only example: needs the async gem and network access
require "async"
require "net/http"

Async do
  pages = %w[https://example.com/a https://example.com/b].map do |url|
    Async { Net::HTTP.get(URI(url)).bytesize }
  end
  p pages.map(&:wait)
end

Inside Net::HTTP.get, Ruby calls io_wait whenever the socket would block, so both downloads progress in one thread.

Threads, fibers or processes: a rule of thumb

Situation Choose
A few background jobs, simple code Threads
Thousands of concurrent waits (sockets, HTTP calls) Fibers with a scheduler
CPU-bound work on several cores Processes or Ractors
A lazy sequence you consume yourself Enumerators

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does a call to Fiber.schedule do when no scheduler has been installed in the current thread?

    Ruby ships only the scheduler interface. You must call Fiber.set_scheduler (or let a library such as async do it) first.
  2. 2. Which kind of fiber hands its waiting to the scheduler?

    A blocking fiber waits like ordinary Ruby code. A non-blocking fiber (the default for Fiber.new and the kind Fiber.schedule creates) asks the scheduler to handle sleep, queue waits and I/O.
  3. 3. In the tiny scheduler, what does kernel_sleep do?

    It does not sleep. The scheduler's run loop later resumes the fiber when its time has come.
  4. 4. Why can a single CPU-heavy fiber ruin a scheduler-based program?

    Fibers on one thread take turns only when one of them waits. A busy loop keeps the turn and every other fiber is delayed.
  5. 5. When does Ruby call scheduler.close?

    The scheduler's close method typically contains its main loop. That is why you do not write the loop in your program.

Summary

  • The Fiber scheduler is an interface Ruby calls when a non-blocking fiber would wait; you install an implementation per thread with Fiber.set_scheduler, and Fiber.schedule { ... } starts a fiber on it.
  • Without a scheduler, Fiber.schedule raises No scheduler is available!, and sleep blocks as always.
  • A scheduler implements methods such as fiber, kernel_sleep, block, unblock, io_wait, fiber_interrupt and close; close runs the pending fibers when the thread ends.
  • Fibers share one thread, so they need no locks between waits, but one fiber that never waits delays all the others.
  • In real projects use a library scheduler such as async; the mechanics are the same as in the tiny scheduler.

Next: Processes and Subprocesses