Skip to content
Tutorials Center
My learning

Topics

Lesson 95 of 134 ยท Concurrency

Mutex, Queue and ConditionVariable

Learn how Ruby threads share data safely with Mutex, Queue, SizedQueue, ConditionVariable and Monitor, with producer-consumer examples and deadlock fixes.

Starting threads is the easy part. The hard part is letting them work on the same data without stepping on each other, and letting them hand work to one another without waiting in a busy loop. Ruby gives you three small tools for this, all part of the core library (no require needed): a Mutex for protecting shared data, a Queue for passing work between threads, and a ConditionVariable for waiting until something becomes true.

If you have not met threads yet, start with Threads. There you saw a counter lose updates and a mutex fix it. This lesson goes deeper: how a mutex works and fails, how to build producer-consumer programs with queues, what back-pressure is, and how deadlocks happen and how to avoid them.

Mutex: one thread at a time

A mutex (mutual exclusion lock) is an object that at most one thread can hold at any moment. A thread that wants the lock while another holds it waits. The code between taking and releasing the lock is the critical section.

You almost always use synchronize. It takes the lock, runs the block, returns the block's value and releases the lock, even if the block raises an error.

Ruby synchronize returns the block value and always unlocks

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.

locked? tells whether anybody holds the lock, owned? whether the current thread does. After the exception the lock is free again, which is the main reason to prefer synchronize over calling lock and unlock yourself. If you do call them by hand, put unlock in an ensure block.

A thread-safe object

The usual pattern is to keep the data and its lock together inside one object. Every method that reads or changes the shared state takes the lock, so callers never need to know about it.

Ruby A bank account that protects its balance

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 check "is there enough money" and the subtraction happen inside the same critical section. If the check were outside the lock, another thread could drain the account between the check and the subtraction. Rule of thumb: whatever must be true together must be locked together.

A mutex is not reentrant

If a thread that already holds a mutex tries to take it again, Ruby does not let it through; the thread would wait for itself forever. Ruby detects that and raises an error instead. This happens easily when one locked method calls another locked method of the same object.

Ruby Locking twice in one thread (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:7:in 'Thread::Mutex#synchronize': deadlock; recursive locking (ThreadError). The increment_twice method holds the lock and then calls increment, which asks for the same lock. There are two fixes: split the logic into a private method that assumes the lock is held, or use a Monitor, which allows re-entry:

Ruby Monitor is a reentrant lock

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.

Monitor counts how many times the owner took the lock and releases it when the count is back to zero. It is a default library; require "monitor" is enough. The module MonitorMixin adds synchronize to your own class directly. Prefer a plain Mutex and a clean design when you can, since reentrancy can hide a design where locks are taken too broadly.

Two other errors worth knowing: unlocking a mutex that is not locked raises ThreadError (Attempt to unlock a mutex which is not locked), and unlocking one held by a different thread raises it with the text Attempt to unlock a mutex which is locked by another thread/fiber. And a thread that dies while holding a plain lock releases the mutex automatically.

Queue: passing work between threads

A mutex protects data that several threads share. Often a better design is for threads to pass data instead. A Queue is a first-in, first-out line that is already thread-safe. One thread pushes items; another pops them. If the queue is empty, pop makes the thread wait (sleep) until something arrives, with no busy loop and no lock for you to manage.

Ruby Queue basics

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.

<<, push and enq do the same; pop, shift and deq also do the same. pop(true) is the non-blocking form and raises ThreadError (queue empty) when there is nothing to take. pop(timeout: seconds) waits at most that long and returns nil on a timeout. A plain pop on an empty queue waits forever, which is just what a worker thread wants.

Producer and consumer

A producer creates work, a consumer processes it. The queue decouples them: the producer does not wait for the consumer, and the consumer sleeps when there is nothing to do.

How does the consumer know the work is over? Close the queue. close tells everybody that no more items will arrive; the consumers still receive the items already inside, and after the last one pop returns nil instead of waiting.

Ruby Producer and consumer with close

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 loop while (job = queue.pop) ends when pop returns nil, so the consumer needs no special end marker. Pushing onto a closed queue is an error: it raises ClosedQueueError (a subclass of StopIteration) with the message queue closed. If nil itself can be a legitimate item, push a special marker object (a "poison pill") instead of closing.

Several consumers

Many consumers can pop from the same queue. Each item is handed to exactly one of them, so the work is shared. This is the base of a thread pool, covered in Thread Pools and Parallel Work.

Ruby Three workers share one queue

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.

Which worker handles which number differs from run to run, and the order in which results arrive varies too, so the program sorts the results before printing. That is a good habit in all threaded code: never print or depend on arrival order unless the order is part of the design.

SizedQueue and back-pressure

A plain Queue can grow without limit. If the producer is faster than the consumer, memory fills up with waiting items. A SizedQueue has a maximum size. When it is full, push waits until a consumer has taken something. The producer is slowed down to the speed of the consumer; this is called back-pressure.

Ruby SizedQueue limits the backlog

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.

Pushing a third item without waiting raises ThreadError with the text queue full, and push(3, timeout: 0.05) returns nil when the queue stays full. In the producer-consumer part the fast producer is held back by the slow consumer, and the consumer still receives all ten numbers in order. Choose the maximum deliberately: small enough to bound memory, large enough to smooth out bursts.

ConditionVariable: wait until something is true

Sometimes the thing to wait for is not an item but a condition: "the file is ready", "the pool has a free slot", "the flag is set". Polling with sleep in a loop wastes time and reacts slowly. A ConditionVariable lets a thread sleep until another thread signals that something changed. It always works together with a mutex that guards the condition.

The pattern has three rules:

  1. Check the condition inside mutex.synchronize.
  2. Wait with condition.wait(mutex), which releases the mutex while sleeping and takes it back before returning.
  3. Wait in a loop (until condition), because a thread can wake up when the condition is still false (a spurious wake-up, or another thread got there first).
Ruby Waiting for a flag with signal

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.

signal wakes up one waiting thread; broadcast wakes them all. Use broadcast when several threads may be waiting on the same condition, for example when a "start" flag is set.

Ruby broadcast releases every waiting 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.

Because the waiting loop re-checks go, it does not matter whether a runner reaches wait before or after the broadcast. A runner that arrives late sees go == true and never waits at all. That is also why the flag, not the signal, is the real information: a signal that nobody is waiting for is simply lost.

In practice, a Queue is often the simpler tool: it already contains a mutex and a condition variable. Reach for ConditionVariable when you have a more unusual condition than "an item arrived".

Deadlock

A deadlock happens when threads wait for each other in a circle, so none can ever continue. The classic recipe uses two locks taken in opposite order: thread 1 holds A and wants B, while thread 2 holds B and wants A.

When every thread is asleep and nothing can wake them up, Ruby notices and raises a fatal error in the main thread. It is a special exception class, so it is caught by rescue Exception only.

Ruby Two locks in opposite order

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.

Left alone, such a program stops with main.rb:...:in 'Thread::Mutex#synchronize': No live threads left. Deadlock? (fatal), followed by a dump of every thread and where it waits. We rescued the fatal here only to show its class and first line. Never rescue it in real code to carry on: the program is in an unrecoverable state.

Ruby can only detect the case where all threads are blocked. If one thread is still running (a timer, a sleeping loop), the others can wait forever without any error, so a hanging program is a typical symptom of a deadlock.

How to avoid deadlocks

  • Take locks in the same order everywhere. Give every lock a rank and always acquire the lower one first. The deadlock above disappears when both threads lock lock_a before lock_b.
  • Hold locks briefly and never call unknown code (callbacks, I/O, blocks from callers) while holding one.
  • Prefer one lock for a related set of data over many small ones.
  • Prefer messages to shared state: with queues there are no locks for you to order.
  • Use try_lock when you can do something else if the lock is busy.
Ruby The fix: a consistent lock order

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 threads now lock A first, so whichever arrives second simply waits for the first to finish.

Which tool should I use?

Situation Tool
Several threads update one shared value or object Mutex#synchronize
A method with a lock calls another method with the same lock Monitor, or restructure the code
Hand work from producers to consumers Queue (with close to finish)
The producer must not run far ahead SizedQueue
Wait for a flag or a custom condition ConditionVariable with a mutex and a until loop

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does Mutex#synchronize do when the block raises an error?

    synchronize releases the lock in an ensure-like way, so a failing block never leaves the mutex locked.
  2. 2. A method holds @lock.synchronize and calls another method that also calls @lock.synchronize. What happens with a plain Mutex?

    A Mutex is not reentrant. Restructure the code or use Monitor, which counts nested locks.
  3. 3. A consumer runs while (item = queue.pop). How can the producer end the loop cleanly?

    A closed queue still delivers its remaining items, and then pop returns nil, which ends the while loop.
  4. 4. What is the purpose of a SizedQueue?

    The maximum size creates back-pressure and bounds memory use.
  5. 5. Why must ConditionVariable#wait be placed in a loop such as cv.wait(mutex) until ready?

    The flag is the real information. Re-checking it after each wake-up handles spurious wake-ups, other threads taking the work first, and threads that arrive after the signal.

Summary

  • Mutex#synchronize lets one thread at a time run a critical section, returns the block's value and always unlocks, even after an error. Keep the data and its lock together in one object.
  • A mutex is not reentrant (deadlock; recursive locking); use a Monitor or restructure the code.
  • Queue is a thread-safe FIFO: pop waits when empty, pop(true) and pop(timeout:) do not wait forever, and close ends consumers cleanly (pop returns nil).
  • SizedQueue adds a maximum size and thus back-pressure.
  • ConditionVariable waits for a condition: always use it with a mutex, wait in a loop, and use broadcast to wake everybody.
  • Deadlocks come from circular waiting; take locks in one global order and hold them briefly. Ruby reports total deadlock as fatal ("No live threads left").

Next: Thread Pools and Parallel Work