Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 134 ยท Methods and Blocks

Fibers

Learn Ruby Fibers - lightweight, pausable code blocks with resume and Fiber.yield, generators, passing values, round-robin scheduling and the Fiber scheduler idea.

A normal method runs from start to finish before control goes back to its caller. A Fiber is a piece of code that can pause itself in the middle, hand control back, and later continue exactly where it stopped, with all its local variables intact. Think of it as a bookmark in a running function.

Fibers are small (much lighter than threads), and they never run in parallel: only one fiber runs at a time, and a switch happens only when the code asks for it. That is called cooperative multitasking. In this lesson you build generators with Fiber, pass values in both directions, write a tiny round-robin scheduler, and then see how Ruby's Fiber scheduler uses the same mechanism to make waiting for the network cheap. You have already used fibers without knowing: stepping an enumerator with next (see Enumerators and Lazy Enumerators) runs the iteration inside one.

Resume and yield

You create a fiber with Fiber.new and a block. Nothing runs until somebody calls resume. Inside the fiber, Fiber.yield pauses it and returns control to whoever called resume.

Ruby The first 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.

The output interleaves the fiber's lines with the caller's, which shows exactly how control moves. The value of the last resume is the value of the block (:finished), after which the fiber is finished and alive? is false. Resuming a finished fiber is an error:

Ruby Resuming a finished fiber (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 first resume prints :done; the second ends the program with main.rb:3:in 'Fiber#resume': attempt to resume a terminated fiber (FiberError). Check alive? first if you do not know whether the fiber has finished.

Passing values in both directions

Fiber.yield(x) makes resume return x. And resume(y) makes the paused Fiber.yield expression evaluate to y. That turns a fiber into a two-way channel, like a tiny coroutine.

Ruby Values travel both ways

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 argument of the first resume becomes the block's parameter (first), because there is no earlier Fiber.yield waiting to receive it. Every later resume argument becomes the value of the pending Fiber.yield.

Generators

Many sequences are easier to write as "produce one value, pause, continue" than as a class with state. A fiber holds its own state in local variables, so no instance variables or counters are needed.

Ruby A generator for squares and an ID source

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 generator has its own locals, and they interleave freely. The loop never ends, and that is fine: an unfinished fiber that nobody resumes is simply garbage collected. In everyday Ruby you would reach for an Enumerator for this job (Enumerator.new is built on fibers when you use next), which gives you take, lazy and friends for free. Raw fibers are the right tool when you need two-way communication or want to build the scheduling yourself.

A pipeline of fibers

Fibers compose. A producer yields values, a filter consumes and re-yields them, and the main program pulls the final results.

Ruby Producer and filter fibers

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 main program pulls from numbers_only, which pulls from producer. Control goes down the chain and values flow back up. No intermediate array is built. The sentinel value nil marks the end of the stream, so while (x = fiber.resume) stops. In real code use a different sentinel if nil can be a legitimate value, or check alive?.

A round-robin scheduler by hand

Cooperative multitasking is easiest to understand by building it. Each task is a fiber that does a bit of work, then voluntarily yields; the scheduler resumes them in turn until all are done.

Ruby A tiny cooperative 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 tasks take turns: downloader, parser, logger, then downloader again, and so on. The logger finishes in its first slice and is not rescheduled. There are no locks and no race conditions, because only one fiber runs at a time and a switch happens only at Fiber.yield. The price is that one task that never yields blocks everybody. This is the central trade-off of cooperative scheduling, and the opposite of threads, where the system interrupts you whenever it likes.

Errors inside fibers

An exception that is not rescued inside a fiber travels out through the resume call that was running it, and the fiber is dead afterwards. You can also push an exception into a paused fiber with raise.

Ruby Exceptions and fibers

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#raise raises the exception at the point where the fiber is paused, so the fiber's own rescue can handle it. That is how a scheduler can deliver a timeout or a cancellation to a fiber that is waiting.

Fiber-local storage

Threads have thread-local variables; fibers have fiber storage (Ruby 3.2+): an inheritable set of key-value pairs read with Fiber[:key]. A fiber created later copies the storage of its creator, which is handy for request IDs and log context.

Ruby Fiber storage

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 child starts with a copy, and its change does not leak back to the parent. (Compare Thread#[], which is per fiber, and Thread#thread_variable_get, which is per thread.)

The Fiber scheduler

Waiting is the main cost in many programs: waiting for a socket, a file, a sleep, a database. A thread that waits still costs memory and operating-system resources, and a program with 10,000 waiting threads is in trouble. A fiber that waits costs very little.

Ruby 3.0 added a hook called the Fiber scheduler. You install an object implementing a documented interface (methods such as io_wait, kernel_sleep, block, unblock and fiber). Afterwards, ordinary blocking calls such as sleep, Queue#pop and socket reads in non-blocking fibers tell the scheduler "I would wait now" instead of blocking the thread. The scheduler parks that fiber and runs another one. You start such fibers with Fiber.schedule { ... }.

A scheduler is not built into Ruby, only the hook is. Real programs install one from a gem, usually async (or libev_scheduler). The sandbox on this page has no extra gems and no network, so the following example is read-only. It shows what the code looks like in a normal project. The next lessons, Fibers and the Fiber Scheduler and Threads, go further.

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

Async do
  tasks = 3.times.map do |i|
    Async do
      sleep 1                 # does not block the others
      puts "task #{i} done"
    end
  end
  tasks.each(&:wait)
end
# Total time is about one second, not three.

Even without a scheduler, the idea is useful: a fiber-based design keeps state in locals instead of callbacks. Languages with async/await (JavaScript, Python, C#) compile to similar state machines, but the Ruby version looks like plain sequential code.

Fibers versus threads versus enumerators

Fiber Thread Enumerator
Switching You decide (resume / Fiber.yield) The runtime decides (preemptive) Driven by next
Runs in parallel? No Not for Ruby code (GVL), yes while waiting for I/O No
Needs locks? No Often, for shared data No
Typical use Coroutines, schedulers, generators Background work, waiting on I/O Sequences, lazy pipelines

Pick the simplest tool: an Enumerator for sequences, a Fiber when you need to control the interleaving or pass values both ways, a Thread when work should proceed in the background.

Pitfalls

  • A fiber must Fiber.yield to give control back. A busy loop inside a fiber freezes everything else.
  • Fiber.yield outside a fiber (in the main program) raises FiberError with the message attempt to yield on a not resumed fiber.
  • Keep fibers with the code that owns them. Passing fibers between threads makes the control flow hard to follow, even where Ruby allows it.
  • Do not hide the end: decide how a generator signals "no more values" (sentinel, alive? or StopIteration).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does Fiber.yield do?

    Fiber.yield suspends the fiber and makes the pending resume return. The next resume continues right after it.
  2. 2. In f = Fiber.new { |x| y = Fiber.yield(x + 1); y * 2 }, what is the value of f.resume(1) and then of f.resume(10)?

    The first resume passes 1 as x and returns the yielded x + 1 = 2. The second resume makes Fiber.yield evaluate to 10, so y is 10 and the block returns 20.
  3. 3. What happens when you call resume on a fiber whose block already finished?

    A finished fiber cannot be restarted. Use alive? to check before resuming.
  4. 4. Why do fibers need no locks for data shared between them?

    Cooperative scheduling means a fiber is never interrupted in the middle of an operation unless it yields or waits, so there are no data races between fibers on one thread.
  5. 5. What is the Fiber scheduler?

    Ruby only provides the hooks. A gem such as async supplies the scheduler, which makes sleep and I/O non-blocking inside fibers.

Summary

  • A Fiber is a pausable block: resume runs it, Fiber.yield pauses it and the next resume continues.
  • Values pass both ways; the first resume argument becomes the block parameter, the final resume returns the block's value.
  • A finished fiber raises FiberError if resumed; check alive?.
  • Fibers make generators, pipelines and hand-written schedulers easy, with no locks because switching is cooperative.
  • Exceptions escape through resume, and Fiber#raise injects one at the pause point.
  • Fiber[:key] is inheritable fiber storage; the Fiber scheduler (from a gem such as async) lets blocking calls in fibers hand over to other fibers.

Next: method_missing and respond_to_missing?