The main thread is special: the Ruby interpreter stops running when the main thread is done. It does this even if the main thread has created other threads that are still running. You must ensure, therefore, that your main thread does not end while other threads are still running. One way to do this is to write your main thread in the form of an infinite loop. Another way is to explicitly wait for the threads you care about to complete. We’ve already mentioned that you can call the value method of a thread to wait for it to finish. If you don’t care about the value of your threads, you can wait with the join method instead.

The following method waits until all threads, other than the main thread and the current thread (which may be the same thing), have exited:

# Wait for all threads (other than the current thread and
# main thread) to stop running.
# Assumes that no new threads are started while waiting.
def join_all
  main = Thread.main        # The main thread
  current = Thread.current  # The current thread
  all = Thread.list         # All threads still running
  # Now call join on each thread
  all.each {|t| t.join unless t == current or t == main }
end

If an exception is raised in the main thread, and is not handled anywhere, the Ruby interpreter prints a message and exits. In threads other than the main thread, unhandled exceptions cause the thread to stop running. By default, however, this does not cause the interpreter to print a message or exit. If a thread t exits because of an unhandled exception, and another thread s calls t.join or t.value, then the exception that occurred in t is raised in the thread s.

If you would like any unhandled exception in any thread to cause the interpreter to exit, use the class method Thread.abort_on_exception=:

Thread.abort_on_exception = true

If you want an unhandled exception in one particular thread to cause the interpreter to exit, use the instance method by the same name:

t = Thread.new { ... }
t.abort_on_exception = true

Variables defined within the block of a thread are private to that thread and are not visible to any other thread. This is simply a consequence of Ruby’s variable scoping rules.

We often want a thread to have its own private copy of a variable so that its behavior does not change if the value of that variable changes. Consider the following code, which attempts to create three threads that print (respectively) the numbers 1, 2, and 3:

n = 1
while n <= 3
  Thread.new { puts n }
  n += 1
end 

In some circumstances, in some implementations, this code might work as expected and print the numbers 1, 2, and 3. In other circumstances or in other implementations, it might not. It is perfectly possible (if newly created threads do not run right away) for the code to print 4, 4, and 4, for example. Each thread reads a shared copy of the variable n, and the value of that variable changes as the loop executes. The value printed by the thread depends on when that thread runs in relation to the parent thread.

To solve this problem, we pass the current value of n to the Thread.new method, and assign the current value of that variable to a block parameter. Block parameters are private to the block (but see Blocks and Variable Scope for cautions), and this private value is not shared between threads:

n = 1
while n <= 3
  # Get a private copy of the current value of n in x
  Thread.new(n) {|x| puts x }
  n += 1
end 

Note that another way to solve this problem is to use an iterator instead of a while loop. In this case, the value of n is private to the outer block and never changes during the execution of that block:

1.upto(3) {|n| Thread.new { puts n }}

Certain of Ruby’s special global variables are thread-local: they may have different values in different threads. $SAFE (see Security) and $~ (see Table 9-3) are examples. This means that if two threads are performing regular expression matching concurrently, they will see different values of $~, and performing a match in one thread will not interfere with the results of a match performed in another thread.

The Thread class provides hash-like behavior. It defines [] and []= instance methods that allow you to associate arbitrary values with any symbol. (If you use a string instead, it will be converted to a symbol. Unlike true hashes, the Thread class only allows symbols as keys.) The values associated with these symbols behave like thread-local variables. They are not private like block-local variables because any thread can look up a value in any other thread. But they are not shared variables either, since each thread can have its own copy.

As an example, suppose that we’ve created threads to download files from a web server. The main thread might want to monitor the progress of the download. To enable this, each thread might do the following:

Thread.current[:progress] = bytes_received

The main thread could then determine the total bytes downloaded with code like this:

total = 0
download_threads.each {|t| total += t[:progress] }

Along with [] and []=, Thread also defines a key? method to test whether a given key exists for a thread. The keys method returns an array of symbols representing the defined keys for the thread. This code could be better written as follows, so that it works for threads that have not yet started running and have not defined the :progress key yet:

total = 0
download_threads.each {|t| total += t[:progress] if t.key?(:progress)}

The first factor that affects thread scheduling is thread priority: high-priority threads are scheduled before low-priority threads. More precisely, a thread will only get CPU time if there are no higher-priority threads waiting to run.

Set and query the priority of a Ruby Thread object with priority= and priority. Note that there is no way to set the priority of a thread before it starts running. A thread can, however, raise or lower its own priority as the first action it takes.

A newly created thread starts at the same priority as the thread that created it. The main thread starts off at priority 0.

Like many aspects of threading, thread priorities are dependent on the implementation of Ruby and on the underlying operating system. Under Linux, for example, nonprivileged threads cannot have their priorities raised or lowered. So in Ruby 1.9 (which uses native threads) on Linux, the thread priority setting is ignored.

When multiple threads of the same priority need to share the CPU, it is up to the thread scheduler to decide when, and for how long, each thread runs. Some schedulers are preempting, which means that they allow a thread to run only for a fixed amount of time before allowing another thread of the same priority to run. Other schedulers are not preempting: once a thread starts running, it keeps running unless it sleeps, blocks for I/O, or a higher-priority thread wakes up.

If a long-running compute-bound thread (i.e., one that does not ever block for I/O) is running on a nonpreempting scheduler, it will “starve” other threads of the same priority, and they will never get a chance to run. To avoid this issue, long-running compute-bound threads should periodically call Thread.pass to ask the scheduler to yield the CPU to another thread.

The Thread class defines several instance methods for testing the status of a thread. alive? returns true if a thread is runnable or sleeping. stop? returns true if a thread is in any state other than runnable. Finally, the status method returns the state of the thread. There are five possible return values corresponding to the five possible states as shown in the following table.

Threads are created in the runnable state, and are eligible to run right away. A thread can pause itself—enter the sleeping state—by calling Thread.stop. This is a class method that operates on the current thread—there is no equivalent instance method, so one thread cannot force another thread to pause. Calling Thread.stop is effectively the same thing as calling Kernel.sleep with no argument: the thread pauses forever (or until woken up, as explained below).

Threads also temporarily enter the sleeping state if they call Kernel.sleep with an argument. In this case, they automatically wake up and reenter the runnable state after (approximately) the specified number of seconds pass. Calling blocking IO methods may also cause a thread to sleep until the IO operation completes—in fact, it is the inherent latency of IO operations that makes threading worthwhile even on single-CPU systems.

A thread that has paused itself with Thread.stop or Kernel.sleep can be started again (even if the sleep time has not expired yet) with the instance methods wakeup and run. Both methods switch the thread from the sleeping state to the runnable state. The run method also invokes the thread scheduler. This causes the current thread to yield the CPU, and may cause the newly awoken thread to start running right away. The wakeup method wakes the specified thread without yielding the CPU.

A thread can switch itself from the runnable state to one of the terminated states simply by exiting its block or by raising an exception. Another way for a thread to terminate normally is by calling Thread.exit. Note that any ensure clauses are processed before a thread exits in this way.

A thread can forcibly terminate another thread by invoking the instance method kill on the thread to be terminated. terminate and exit are synonyms for kill. These methods put the killed thread into the terminated normally state. The killed thread runs any ensure clauses before it actually dies. The kill! method (and its synonyms terminate! and exit!) terminate a thread but do not allow any ensure clauses to run.

The thread termination methods described so far all force a thread to the terminated normally state. You can raise an exception within another thread with the instance method raise. If the thread cannot handle the exception you have imposed on it, it will enter the terminated with exception state. The threads ensure clauses are processed as they would normally be during the course of exception propagation.

Killing a thread is a dangerous thing to do unless you have some way of knowing that the thread is not in the middle of altering the shared state of your system. Killing a thread with one of the ! methods is even more dangerous because the killed thread may leave files, sockets, or other resources open. If a thread must be able to exit upon command, it is better to have it periodically check the state of a flag variable and terminate itself safely and gracefully if or when the flag becomes set.

The most common use of Ruby’s threads is in programs that are IO-bound. They allow programs to keep busy even while waiting for input from the user, the filesystem, or the network. The following code, for example, defines a method conread (for concurrent read) that takes an array of filenames and returns a hash mapping those names to the contents of those files. It uses threads to read those files concurrently, and is really intended for use with the open-uri module, which allows HTTP and FTP URLs to be opened with Kernel.open and read as if they were files:

# Read files concurrently. Use with the "open-uri" module to fetch URLs.
# Pass an array of filenames. Returns a hash mapping filenames to content.
def conread(filenames)
  h = {}                            # Empty hash of results

  # Create one thread for each file
  filenames.each do |filename|      # For each named file
    h[filename] = Thread.new do     # Create a thread, map to filename
      open(filename) {|f| f.read }  # Open and read the file
    end                             # Thread value is file contents
  end

  # Iterate through the hash, waiting for each thread to complete.
  # Replace the thread in the hash with its value (the file contents)
  h.each_pair do |filename, thread| 
    begin
      h[filename] = thread.value    # Map filename to file contents
    rescue
      h[filename] = $!              # Or to the exception raised
    end
  end
end

Another, almost canonical, use case for threads is for writing servers that can communicate with more than one client at a time. We saw how to do this using multiplexing with Kernel.select, but a somewhat simpler (though possibly less scalable) solution uses threads:

require 'socket'

# This method expects a socket connected to a client.
# It reads lines from the client, reverses them and sends them back.
# Multiple threads may run this method at the same time.
def handle_client(c)
  while true
    input = c.gets.chop     # Read a line of input from the client
    break if !input         # Exit if no more input
    break if input=="quit"  # or if the client asks to.
    c.puts(input.reverse)   # Otherwise, respond to client.
    c.flush                 # Force our output out
  end
  c.close                   # Close the client socket
end


server = TCPServer.open(2000) # Listen on port 2000

while true                    # Servers loop forever
  client = server.accept      # Wait for a client to connect
  Thread.start(client) do |c| # Start a new thread 
    handle_client(c)          # And handle the client on that thread
  end
end

Although IO-bound tasks are the typical use case for Ruby’s threads, they are not restricted to that use. The following code adds a method conmap (for concurrent map) to the Enumerable module. It works like map but processes each element of the input array using a separate thread:

module Enumerable           # Open the Enumerable module
  def conmap(&block)        # Define a new method that expects a block
    threads = []            # Start with an empty array of threads
    self.each do |item|     # For each enumerable item
      # Invoke the block in a new thread, and remember the thread
      threads << Thread.new { block.call(item) }
    end
    # Now map the array of threads to their values 
    threads.map {|t| t.value } # And return the array of values
  end
end

And here’s a similar concurrent version of the each iterator:

module Enumerable
  def concurrently
    map {|item| Thread.new { yield item }}.each {|t| t.join }
  end
end

The code is succinct and challenging: if you can make sense of it, you are well on your way to mastery of Ruby syntax and Ruby iterators.

Recall that in Ruby 1.9, standard iterators that are not passed a block return an enumerator object. This means that given the concurrently method defined earlier and a Hash object h, we can write:

h.each_pair.concurrently {|*pair| process(pair)}

When we start using Mutex objects for thread exclusion we must be careful to avoid deadlock. Deadlock is the condition that occurs when all threads are waiting to acquire a resource held by another thread. Because all threads are blocked, they cannot release the locks they hold. And because they cannot release the locks, no other thread can acquire those locks.

A classic deadlock scenario involves two threads and two Mutex objects. Thread 1 locks Mutex 1 and then attempts to lock Mutex 2. Meanwhile, thread 2 locks Mutex 2 and then attempts to lock Mutex 1. Neither thread can acquire the lock it needs, and neither thread can release the lock the other one needs, so both threads block forever:

# Classic deadlock: two threads and two locks
require 'thread'

m,n = Mutex.new, Mutex.new

t = Thread.new {
  m.lock
  puts "Thread t locked Mutex m"
  sleep 1
  puts "Thread t waiting to lock Mutex n"
  n.lock
}

s = Thread.new {
  n.lock
  puts "Thread s locked Mutex n"
  sleep 1
  puts "Thread s waiting to lock Mutex m"
  m.lock
}

t.join
s.join

The way to avoid this kind of deadlock is to always lock resources in the same order. If the second thread locked m before locking n, then deadlock would not occur.

Note that deadlock is possible even without using Mutex objects. Calling join on a thread that calls Thread.stop will deadlock both threads, unless there is a third thread that can awaken the stopped thread.

Bear in mind that some Ruby implementations can detect simple deadlocks like these and abort with an error, but this is not guaranteed.