Skip to content
Tutorials Center
My learning

Topics

Lesson 94 of 134 ยท Concurrency

Threads

Learn Ruby threads: Thread.new, join, value, thread-local variables, error handling, the GVL and race conditions, with runnable examples and real errors.

A program that does one thing at a time wastes a lot of time waiting: for a network answer, a disk, a slow API, a timer. A thread lets the program do something else while one part waits. Each thread is its own line of execution with its own call stack, but all threads live in the same process and see the same objects.

Ruby threads are real operating-system threads, yet they come with an important rule: the Global VM Lock (GVL) lets only one thread run Ruby code at a time. That sounds like a deal breaker, but it is not, because a thread that waits for input or output releases the lock. In this lesson you start threads, collect their results, handle their errors, give them private variables, and watch a race condition happen and then see why it needs a lock. The next lessons build on this: Mutex, Queue and ConditionVariable and Thread Pools and Parallel Work.

Starting a thread

Thread.new takes a block and starts running it immediately in a new thread. The call returns a Thread object at once; the block runs alongside the code that follows. Two methods connect the new thread back to its creator:

  • join waits until the thread has finished.
  • value waits (like join) and then returns the value of the block, which is the last expression, exactly like a method.
Ruby Your first thread

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 two messages can appear in either order, because both threads run at the same time. The last two always come after the worker has finished, since value blocks the main thread until there is a result. After that, alive? is false.

Always keep the thread object and call join or value on it. When the main thread reaches the end of the program, Ruby stops all other threads immediately, even if they are halfway through their work.

Ruby Forgetting to join

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 right after the first message; the worker is killed while it sleeps. Add .join to the end of the Thread.new block call and the line appears.

Passing data in and getting results out

Arguments given to Thread.new are passed to the block. Passing them this way, instead of capturing outer variables, avoids a classic bug that the next example shows.

Ruby Arguments and results

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 pattern threads = items.map { Thread.new { ... } } followed by threads.map(&:value) is the shortest way to run several jobs and collect the results in the original order, no matter which thread finished first.

The loop variable trap

A for loop does not create a new variable per round. Every thread created in the loop sees the same variable, which by the time the threads run holds its final value.

Ruby The shared loop variable

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 line prints [2, 2, 2], the second [0, 1, 2]. Blocks given to each and map create a fresh variable on every round (see Closures and Binding). Prefer them over for, and pass the value as an argument when in doubt.

Threads and waiting: where the speed-up comes from

The GVL is released whenever a thread blocks: in sleep, reading a socket or a file, waiting for a subprocess, or waiting on a queue. While thread A waits for the network, thread B can run Ruby code. That is why threads speed up programs that spend their time waiting, which describes most web requests, API calls and database queries.

The example below waits 0.2 seconds three times. Done one after another it takes at least 0.6 seconds; in three threads the waits overlap.

Ruby Waiting in parallel

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.

Both true results are what you should see. We print comparisons and not the raw times, since clocks differ from machine to machine.

What the GVL does not give you

CPU-bound code, such as hashing, number crunching or parsing a big string in pure Ruby, keeps the lock all the time. Two threads doing arithmetic take roughly as long as running the work one after another. With the standard Ruby interpreter you get concurrency (overlapping waits), but not parallel speed-up for Ruby code. If you need real parallelism, use several processes (Processes and Subprocesses) or Ractors.

The GVL belongs to the CRuby interpreter (the default ruby). Other implementations such as JRuby and TruffleRuby run threads in parallel. Code that is only "accidentally safe" because of the GVL breaks there, which is one more reason to protect shared data with a lock.

Also, the GVL protects the interpreter, not your program's logic. It can switch threads in the middle of your method (Ruby asks a thread to give way after a short time slice), so a sequence of steps such as "read the counter, add one, write it back" can be interrupted between two steps.

Errors inside threads

An exception that is not rescued inside a thread does not crash the main thread right away. The thread simply ends with that exception stored in it. Two things then happen:

  1. By default Ruby prints a report to standard error, starting with a line of the form #<Thread:0x... main.rb:10 run> terminated with exception (report_on_exception is true):, followed by the error and a backtrace. You can turn that report off with Thread.report_on_exception = false or per thread with thread.report_on_exception = false.
  2. The exception is raised again in whichever thread calls join or value on the dead thread.
Ruby The exception travels to join

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.

A thread that ended with an exception has the status nil; one that finished normally has false; a running thread has "run" and a waiting one "sleep". The stored exception is raised again on every call to join or value.

If you never call join or value, the error only shows up as that stderr report and is easy to miss. There is also a stronger setting, Thread.abort_on_exception = true, which makes an error in any thread immediately re-raise in the main thread:

Ruby abort_on_exception

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.

Use it while developing so that failures cannot hide. In long-running programs it is usually better to handle errors inside each thread, or to collect them with value as shown above.

Never write rescue Exception inside a thread to "keep it alive". It also swallows SystemExit and interrupts, which makes programs impossible to stop. Rescue StandardError (what a bare rescue does) or something narrower.

Thread-local variables

Sometimes each thread needs its own copy of a value: a request ID, a database connection, a log prefix. Ruby offers two kinds of storage with confusingly similar names.

  • Thread.current[:key] is fiber-local: each thread (and each fiber inside it) has its own table.
  • Thread.current.thread_variable_get(:key) and thread_variable_set are truly thread-local: shared by all fibers of one thread.

For ordinary code without fibers they behave alike. The difference shows when a fiber runs inside the thread (see Fibers).

Ruby Thread-local 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.

A new thread starts with an empty table (nil for every key). The fiber cannot see Thread.current[:user] (because it is fiber-local), but it can read the real thread variable :level. Use thread variables when you really mean "per thread". Be careful with both: thread-local data is hidden global state, and it does not follow the work if your code later moves to a thread pool or to fibers.

Controlling a thread from outside

You rarely need these, but you will see them in the code of libraries.

  • thread.kill stops a thread. Its ensure blocks still run, so resources get cleaned up.
  • thread.raise("message") raises an exception inside the thread at the point where it is currently running or waiting. A rescue in the thread can handle it.
  • Thread.stop puts the current thread to sleep until another thread calls run or wakeup on it.
  • thread.join(seconds) waits at most that long and returns nil if the thread was still running.
Ruby Kill, raise and join with a time limit

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.

kill runs the ensure block (cleanup ran) and leaves the status false. raise wakes the sleeping thread with an exception its own rescue turns into a value. join(0.05) returns nil because the slow thread needs a full second. A thread that called Thread.stop reports the status "sleep" until it is run again.

Killing and raising from the outside is rough: the target may be in the middle of a state change. Prefer cooperative shutdown, for instance a flag the thread checks, or a special value on a queue (Mutex, Queue and ConditionVariable).

Race conditions

Whenever two threads change the same data without coordination, the result depends on timing. That bug is called a race condition. The classic example is a counter. count += 1 looks like one step, but it really is "read count, add one, write count". If another thread slips in between the read and the write, one of the updates is lost.

On CRuby a plain count += 1 loop often gives the right answer by luck, because the thread rarely gets interrupted at that exact spot. That is the worst kind of bug: it works on your machine and fails in production. To make the problem visible, the next example splits the update into its steps and lets the thread give way (Thread.pass) between them, which is what an unlucky time slice does.

Ruby A lost update

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.

Five threads each added one thousand times, but count ends far below 5,000, since many threads read the same old value before any of them wrote the new one. The exact number is different from run to run, so we print only that updates were lost.

The cure is a mutex (mutual exclusion lock). Only one thread at a time may run the code inside synchronize, so the read-modify-write steps cannot interleave. This is the short version; the full story is in Mutex, Queue and ConditionVariable.

Ruby The same counter with a mutex

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.

Now the answer is exactly 5000 every time. The price of a lock is a little speed and the chance of deadlock, so keep the locked section short and lock only what is shared.

Good habits with threads

  • Prefer returning values with value over writing into shared variables.
  • Share as little as possible. Data that only one thread touches needs no lock. Frozen (immutable) objects are always safe to share.
  • Always join (or otherwise wait for) the threads you start, so that errors surface and work finishes.
  • Do not start unlimited threads. Each thread uses memory, and thousands of them slow a program down. Use a pool of workers with a queue for large job lists.
  • Name threads in long-running programs (thread.name = "uploader") so logs and debuggers are readable.
  • Know your tool. For waiting, threads are great. For CPU parallelism, use processes or Ractors. For huge numbers of concurrent waits, look at fibers and the Fiber scheduler.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does Thread#value do?

    value works like join and then returns the block's result. If the thread ended with an exception, value raises it again.
  2. 2. Three threads each sleep 0.2. About how long does threads.each(&:join) take in CRuby?

    The GVL is released while a thread waits, so the three sleeps run at the same time. Only Ruby code itself is serialized.
  3. 3. Why might count += 1 in several threads still lose updates?

    The GVL protects the interpreter, not your multi-step logic. Wrap shared updates in Mutex#synchronize.
  4. 4. A thread raises an error and nobody calls join or value on it. What happens by default?

    report_on_exception is true by default. The report is only a message; the exception is stored and would be raised again by join or value.
  5. 5. What is the difference between Thread.current[:x] and Thread.current.thread_variable_get(:x)?

    Thread#[] is stored per fiber. thread_variable_get is stored per thread, so fibers running in that thread can all read it.

Summary

  • Thread.new { ... } starts a thread; join waits for it and value also returns its result. The program ends when the main thread ends, killing all other threads.
  • Pass data as block arguments and prefer map/each over for loops so every thread gets its own variable.
  • The GVL lets only one thread run Ruby code at a time, but it is released while a thread waits, so threads help with I/O and sleeping, not with CPU-bound work.
  • An unhandled exception ends the thread, prints a report, and is raised again by join or value; abort_on_exception re-raises it in the main thread at once.
  • Thread.current[:key] is fiber-local, thread_variable_get/set is thread-local; thread-local data is hidden global state.
  • Unsynchronized updates to shared data are race conditions; protect them with a Mutex.

Next: Mutex, Queue and ConditionVariable