<ppdoc>
<copyright>
    Copyright (c) 2001 by Addison Wesley Longman.  This
    material may be distributed only subject to the terms and
    conditions set forth in the Open Publication License, v1.0 or
    later (the latest version is presently available at
    http://www.opencontent.org/openpub/).
</copyright>
<chapter name="Threads and Processes">
<p/>
Ruby gives you two basic ways to organize your program so that you can
run different parts of it ``at the same time.''  You can split
up cooperating tasks <em>within</em> the program, using multiple
threads, or you can split up tasks between different programs, using
multiple processes.  Let's look at each in turn.
<section>Multithreading</section>
<p/>
Often the simplest way to do two things at once is by using <em>Ruby
  threads</em>. These are totally in-process, implemented within the Ruby
interpreter.  That makes the Ruby threads completely portable---there
is no reliance on the operating system---but you don't get certain
benefits from having native threads.  You may experience thread
starvation (that's where a low-priority thread doesn't get a chance to
run).  If you manage to get your threads deadlocked, the whole process
may grind to a halt. And if some thread happens to make a call to the
operating system that takes a long time to complete, all threads will
hang until the interpreter gets control back. However, don't let these
potential problems put you off---Ruby threads are a lightweight and
efficient way to achieve parallelism in your code.
<subsection>Creating Ruby Threads</subsection>
<p/>
Creating a new thread is pretty straightforward.
Here's a simple code
fragment that downloads a set of Web pages in parallel. For each
request it's given, the code creates a separate thread that handles
the HTTP transaction.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[  require 'net/http'

  pages = %w( www.rubycentral.com
              www.awl.com
              www.pragmaticprogrammer.com
             )

  threads = []

  for page in pages
    threads << Thread.new(page) { |myPage|
    
      h = Net::HTTP.new(myPage, 80)
      puts "Fetching: #{myPage}"
      resp, data = h.get('/', nil )
      puts "Got #{myPage}:  #{resp.message}"
    }
  end

  threads.each { |aThread|  aThread.join }
]]></fullcode>
require<nbsp/>'net/http'
<p/>
pages<nbsp/>=<nbsp/>%w(<nbsp/>www.rubycentral.com
<nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/>www.awl.com
<nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/>www.pragmaticprogrammer.com
<nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/>)
<p/>
threads<nbsp/>=<nbsp/>[]
<p/>
for<nbsp/>page<nbsp/>in<nbsp/>pages
<nbsp/><nbsp/>threads<nbsp/>&lt;&lt;<nbsp/>Thread.new(page)<nbsp/>{<nbsp/>|myPage|
<p/>
<nbsp/><nbsp/><nbsp/><nbsp/>h<nbsp/>=<nbsp/>Net::HTTP.new(myPage,<nbsp/>80)
<nbsp/><nbsp/><nbsp/><nbsp/>puts<nbsp/>"Fetching:<nbsp/>#{myPage}"
<nbsp/><nbsp/><nbsp/><nbsp/>resp,<nbsp/>data<nbsp/>=<nbsp/>h.get('/',<nbsp/>nil<nbsp/>)
<nbsp/><nbsp/><nbsp/><nbsp/>puts<nbsp/>"Got<nbsp/>#{myPage}:<nbsp/><nbsp/>#{resp.message}"
<nbsp/><nbsp/>}
end
<p/>
threads.each<nbsp/>{<nbsp/>|aThread|<nbsp/><nbsp/>aThread.join<nbsp/>}
</alltt>
</codefragment>
<p/>
<codefragment>
<alltt><fullcode><![CDATA[!-puts "Fetching: www.rubycentral.com"
!-puts "Fetching: www.awl.com"
!-puts "Fetching: www.pragmaticprogrammer.com"
!-puts "Got www.rubycentral.com:  OK"
!-puts "Got www.pragmaticprogrammer.com:  OK"
!-puts "Got www.awl.com:  OK"
]]></fullcode>
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
Fetching:<nbsp/>www.rubycentral.com
Fetching:<nbsp/>www.awl.com
Fetching:<nbsp/>www.pragmaticprogrammer.com
Got<nbsp/>www.rubycentral.com:<nbsp/><nbsp/>OK
Got<nbsp/>www.pragmaticprogrammer.com:<nbsp/><nbsp/>OK
Got<nbsp/>www.awl.com:<nbsp/><nbsp/>OK
</alltt>
</codefragment>
<p/>
Let's look at this code in more detail, as there are a few subtle
things going on.
<p/>
New threads are created with the <ccm><file>thread</file><front>Thread</front><back>new</back><mref>new</mref></ccm> call. It is given a 
block that contains the code to be run in a new thread. In our case,
the block uses the <tt>net/http</tt> library to fetch the top page from
each of our nominated sites. Our tracing clearly shows that these
fetches are going on in parallel.
<p/>
When we create the thread, we pass the required HTML page in as a
parameter. This parameter is passed on to the block as <var>myPage</var>.
Why do we do this, rather than simply using the value of the variable
<var>page</var> within the block?
<p/>
A thread shares all global, instance, and local variables that are in
existence at the time the thread starts.
As anyone with a kid brother
can tell you, sharing isn't always a good thing.  In this case, all
three threads would share the variable <var>page</var>. The first thread
gets started, and <var>page</var> is set to <url>http://www.rubycentral.com</url>. In
the meantime, the loop creating the threads is still running. The
second time around, <var>page</var> gets set to <url>http://www.awl.com</url>. If the
first thread has not yet finished using the <var>page</var> variable, it
will suddenly start using its new value. These bugs are difficult to
track down.
<p/>
However, local variables created within a thread's block are truly
local to that thread---each thread will have its own copy of these
variables. In our case, the variable <var>myPage</var> will be set at the
time the thread is created, and each thread will have its own copy of
the page address.
<subsubsection>Manipulating Threads</subsubsection>
<p/>
Another subtlety occurs on the last line in the program. Why do we call
<meth>join</meth> on each of the threads we created?
<p/>
When a Ruby program terminates, all running threads are killed,
regardless of their states.  However, you can wait for a particular
thread to finish by calling that thread's <cim><file>thread</file><front>Thread</front><back>join</back><mref>join</mref></cim> method.
The calling thread will block until the given thread is finished.  By
calling <meth>join</meth> on each of the requestor threads, you can make
sure that all three requests have completed before you terminate the
main program.
<p/>
In addition to <meth>join</meth>, there are a few other handy routines that are
used to manipulate threads.  First of all, the current thread is
always accessible using <ccm><file>thread</file><front>Thread</front><back>current</back><mref>current</mref></ccm>.  You can obtain a list
of all threads using <ccm><file>thread</file><front>Thread</front><back>list</back><mref>list</mref></ccm>, which returns a list of
all <classname>Thread</classname> objects that are runnable or stopped.  To determine the 
status of a particular thread, you can use <cim><file>thread</file><front>Thread</front><back>status</back><mref>status</mref></cim> and
<cim><file>thread</file><front>Thread</front><back>alive?</back><mref>alive_qm</mref></cim>.
<p/>
Also, you can adjust the priority of a thread using
<cim><file>thread</file><front>Thread</front><back>priority=</back><mref>priority_eq</mref></cim>. Higher-priority threads will run before
lower-priority threads.  We'll talk more about thread scheduling, and
stopping and starting threads, in just a bit.
<subsubsection>Thread Variables</subsubsection>
<p/>
As we described in the previous section, a thread can normally access
any variables that are in scope when the thread is created.  Variables
local to the block of a thread are local to the thread, and are not
shared.
<p/>
But what if you need per-thread variables that can be accessed by
other threads---including the main thread?  <classname>Thread</classname> features a
special facility that allows thread-local variables to be created and
accessed by name. You simply treat the thread object as if it were a
<classname>Hash</classname>, writing to elements using <meth>[]=</meth> and reading them back
using <meth>[]</meth>. In this example, each thread records the current
value of the variable <var>count</var> in a thread-local variable with the
key <tt>mycount</tt>. (There's a race condition in this code, but we haven't 
talked about synchronization yet, so we'll just quietly ignore it for now.)
<p/>
<codefragment>
<alltt><fullcode><![CDATA[!-  srand 2
  count = 0
  arr = []
  10.times do |i|
    arr[i] = Thread.new {
      sleep(rand(0)/10.0)
      Thread.current["mycount"] = count 
      count += 1
    } 
  end
  arr.each {|t| t.join; print t["mycount"], ", " }
  puts "count = #{count}"
]]></fullcode>
count<nbsp/>=<nbsp/>0
arr<nbsp/>=<nbsp/>[]
10.times<nbsp/>do<nbsp/>|i|
<nbsp/><nbsp/>arr[i]<nbsp/>=<nbsp/>Thread.new<nbsp/>{
<nbsp/><nbsp/><nbsp/><nbsp/>sleep(rand(0)/10.0)
<nbsp/><nbsp/><nbsp/><nbsp/>Thread.current["mycount"]<nbsp/>=<nbsp/>count
<nbsp/><nbsp/><nbsp/><nbsp/>count<nbsp/>+=<nbsp/>1
<nbsp/><nbsp/>}
end
arr.each<nbsp/>{|t|<nbsp/>t.join;<nbsp/>print<nbsp/>t["mycount"],<nbsp/>",<nbsp/>"<nbsp/>}
puts<nbsp/>"count<nbsp/>=<nbsp/>#{count}"
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
8,<nbsp/>0,<nbsp/>3,<nbsp/>7,<nbsp/>2,<nbsp/>1,<nbsp/>6,<nbsp/>5,<nbsp/>4,<nbsp/>9,<nbsp/>count<nbsp/>=<nbsp/>10
</alltt>
</codefragment>
<p/>
The main thread waits for the subthreads to finish and then prints
out the value of <var>count</var> captured by each. Just to make it more
interesting, we have each thread wait a random time before recording
the value.
<subsection>Threads and Exceptions</subsection>
<p/>
What happens if a thread raises an unhandled exception? It depends on
the setting of the
<url>http://abort_on_exception</url>
flag, documented on pages 389 and
392.
<p/>
If <meth>abort_on_exception</meth> is <const>false</const>, the default
condition, an unhandled exception simply kills the current
thread---all the rest continue to run. In the following example,
thread number 3 blows up and fails to produce any output. However,
you can still see the trace from the other threads.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[!-$stderr.sync = $stdout.sync = true
  threads = []
  6.times { |i|
    threads << Thread.new(i) {
      raise "Boom!" if i == 3
      puts i
    }
  }
  threads.each {|t| t.join }
]]></fullcode>
threads<nbsp/>=<nbsp/>[]
6.times<nbsp/>{<nbsp/>|i|
<nbsp/><nbsp/>threads<nbsp/>&lt;&lt;<nbsp/>Thread.new(i)<nbsp/>{
<nbsp/><nbsp/><nbsp/><nbsp/>raise<nbsp/>"Boom!"<nbsp/>if<nbsp/>i<nbsp/>==<nbsp/>3
<nbsp/><nbsp/><nbsp/><nbsp/>puts<nbsp/>i
<nbsp/><nbsp/>}
}
threads.each<nbsp/>{|t|<nbsp/>t.join<nbsp/>}
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
01
2
4
5
<p/>
prog.rb:4:<nbsp/>Boom!<nbsp/>(RuntimeError)
	from<nbsp/>prog.rb:8:in<nbsp/>`join'
	from<nbsp/>prog.rb:8
	from<nbsp/>prog.rb:8:in<nbsp/>`each'
	from<nbsp/>prog.rb:8
</alltt>
</codefragment>
<p/>
However, set <var>abort_on_exception</var> to <const>true</const>, and an
unhandled exception kills all running threads. Once thread 3 dies, 
no more output is produced.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[!-$stderr.sync = $stdout.sync = true
  Thread.abort_on_exception = true
  threads = []
  6.times { |i|
    threads << Thread.new(i) {
      raise "Boom!" if i == 3
      puts i
    }
  }
  threads.each {|t| t.join }
]]></fullcode>
Thread.abort_on_exception<nbsp/>=<nbsp/>true
threads<nbsp/>=<nbsp/>[]
6.times<nbsp/>{<nbsp/>|i|
<nbsp/><nbsp/>threads<nbsp/>&lt;&lt;<nbsp/>Thread.new(i)<nbsp/>{
<nbsp/><nbsp/><nbsp/><nbsp/>raise<nbsp/>"Boom!"<nbsp/>if<nbsp/>i<nbsp/>==<nbsp/>3
<nbsp/><nbsp/><nbsp/><nbsp/>puts<nbsp/>i
<nbsp/><nbsp/>}
}
threads.each<nbsp/>{|t|<nbsp/>t.join<nbsp/>}
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
01
2
prog.rb:5:<nbsp/>Boom!<nbsp/>(RuntimeError)
	from<nbsp/>prog.rb:7:in<nbsp/>`initialize'
	from<nbsp/>prog.rb:7:in<nbsp/>`new'
	from<nbsp/>prog.rb:7
	from<nbsp/>prog.rb:3:in<nbsp/>`times'
	from<nbsp/>prog.rb:3
</alltt>
</codefragment>
<section>Controlling the Thread Scheduler</section>
<p/>
In a well-designed application, you'll normally just let threads do
their thing; building timing dependencies into a multithreaded
application is generally considered to be bad form.
<p/>
However, there are times when you need to control threads. Perhaps the 
jukebox has a thread that displays a light show. We might need to stop 
it temporarily when the music stops. You might have two threads in a
classic producer-consumer relationship, where the consumer has to
pause if the producer gets backlogged.
<p/>
Class <classname>Thread</classname> provides a number of methods to control the thread
scheduler. Invoking <ccm><file>thread</file><front>Thread</front><back>stop</back><mref>stop</mref></ccm> stops the current thread, while
<cim><file>thread</file><front>Thread</front><back>run</back><mref>run</mref></cim> arranges for a particular thread to be
run. <ccm><file>thread</file><front>Thread</front><back>pass</back><mref>pass</mref></ccm> deschedules the current thread, allowing others
to run, and <cim><file>thread</file><front>Thread</front><back>join</back><mref>join</mref></cim> and <cim><file>thread</file><front>Thread</front><back>value</back><mref>value</mref></cim> suspend the
calling thread until a given thread finishes.
<p/>
We can demonstrate these features in the following, totally pointless
program.
<p/>
<codefragment>
<fullcode><![CDATA[  t = Thread.new { sleep .1; Thread.pass; Thread.stop; }
  t.status
  t.run  #!sh!
  t.status
  t.run  #!sh!
  t.status
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>t<nbsp/>=<nbsp/>Thread.new<nbsp/>{<nbsp/>sleep<nbsp/>.1;<nbsp/>Thread.pass;<nbsp/>Thread.stop;<nbsp/>}</tt></td>
</tr>
<tr>
  <td><tt>t.status</tt></td>
  <td>&#187;</td>
  <td><tt>"sleep"</tt></td>
</tr>
<tr>
<td colspan="3"><tt>t.run</tt></td>
</tr>
<tr>
  <td><tt>t.status</tt></td>
  <td>&#187;</td>
  <td><tt>"run"</tt></td>
</tr>
<tr>
<td colspan="3"><tt>t.run</tt></td>
</tr>
<tr>
  <td><tt>t.status</tt></td>
  <td>&#187;</td>
  <td><tt>false</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
However, using these primitives to achieve any kind of real
synchronization is, at best, hit or miss; there will always be race
conditions waiting to bite you. And when you're working with shared
data, race conditions pretty much guarantee long and frustrating
debugging sessions.  Fortunately, threads have one additional
facility---the idea of a critical section. Using this, we can build a
number of secure synchronization schemes.
<section>Mutual Exclusion</section>
<p/>
The lowest-level method of blocking other threads from running uses
a global ``thread critical''
condition.
When the condition is set to <tt>true</tt> (using the
<ccm><file>thread</file><front>Thread</front><back>critical=</back><mref>critical_eq</mref></ccm> method),
the scheduler will not schedule any
existing thread to run.
However, this does not block new threads from
being created and run. Certain thread operations (such as stopping or
killing a thread, sleeping in the current thread, or raising an
exception) may cause a thread to be scheduled even when in a critical
section.
<p/>
Using <ccm><file>thread</file><front>Thread</front><back>critical=</back><mref>critical_eq</mref></ccm> directly is certainly possible, but it
isn't terribly convenient. Fortunately, Ruby comes packaged with
several alternatives. Of these, two of the best, class <classname>Mutex</classname> and
class <classname>ConditionVariable</classname>, are available in the <tt>thread</tt> library 
module; see the documentation beginning on page 462.
<subsubsection>The Mutex Class</subsubsection>
<p/>
<classname>Mutex</classname> is a class that implements a simple
semaphore lock for mutually exclusive access to some shared resource.
That is, only one thread may hold the lock at a given time.  Other
threads may choose to wait in line for the lock to become available,
or may simply choose to get an immediate error indicating that the
lock is not available.
<p/>
A mutex is often used when updates to shared data need to be atomic.
Say we need to update two variables as part of a transaction. We can
simulate this in a trivial program by incrementing some counters. The
updates are supposed to be atomic---the outside world should never see
the counters with different values. Without any kind of mutex control,
this just doesn't work.
<p/>
<codefragment>
<fullcode><![CDATA[  count1 = count2 = 0
  difference = 0
  counter = Thread.new do
    loop do
      count1 += 1
      count2 += 1
    end
  end
  spy = Thread.new do
    loop do
      difference += (count1 - count2).abs
    end
  end
  sleep 1   #!sh!
  Thread.critical = 1
  count1
  count2
  difference
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>count1<nbsp/>=<nbsp/>count2<nbsp/>=<nbsp/>0</tt></td>
</tr>
<tr>
<td colspan="3"><tt>difference<nbsp/>=<nbsp/>0</tt></td>
</tr>
<tr>
<td colspan="3"><tt>counter<nbsp/>=<nbsp/>Thread.new<nbsp/>do</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>loop<nbsp/>do</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/><nbsp/><nbsp/>count1<nbsp/>+=<nbsp/>1</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/><nbsp/><nbsp/>count2<nbsp/>+=<nbsp/>1</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt>spy<nbsp/>=<nbsp/>Thread.new<nbsp/>do</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>loop<nbsp/>do</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/><nbsp/><nbsp/>difference<nbsp/>+=<nbsp/>(count1<nbsp/>-<nbsp/>count2).abs</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt>sleep<nbsp/>1</tt></td>
</tr>
<tr>
<td colspan="3"><tt>Thread.critical<nbsp/>=<nbsp/>1</tt></td>
</tr>
<tr>
  <td><tt>count1</tt></td>
  <td>&#187;</td>
  <td><tt>187651</tt></td>
</tr>
<tr>
  <td><tt>count2</tt></td>
  <td>&#187;</td>
  <td><tt>187650</tt></td>
</tr>
<tr>
  <td><tt>difference</tt></td>
  <td>&#187;</td>
  <td><tt>77442</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
This example shows that the ``spy'' thread woke up a large number of
times and found the values of <var>count1</var> and <var>count2</var> inconsistent.
<p/>
Fortunately we can fix this using a mutex.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[  require 'thread'
  mutex = Mutex.new
  
  count1 = count2 = 0
  difference = 0
  counter = Thread.new do
    loop do
      mutex.synchronize do
        count1 += 1
        count2 += 1
      end
    end
  end
  spy = Thread.new do
    loop do
      mutex.synchronize do
        difference += (count1 - count2).abs
      end
    end
  end
]]></fullcode>
require<nbsp/>'thread'
mutex<nbsp/>=<nbsp/>Mutex.new
<p/>
count1<nbsp/>=<nbsp/>count2<nbsp/>=<nbsp/>0
difference<nbsp/>=<nbsp/>0
counter<nbsp/>=<nbsp/>Thread.new<nbsp/>do
<nbsp/><nbsp/>loop<nbsp/>do
<nbsp/><nbsp/><nbsp/><nbsp/>mutex.synchronize<nbsp/>do
<nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/>count1<nbsp/>+=<nbsp/>1
<nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/>count2<nbsp/>+=<nbsp/>1
<nbsp/><nbsp/><nbsp/><nbsp/>end
<nbsp/><nbsp/>end
end
spy<nbsp/>=<nbsp/>Thread.new<nbsp/>do
<nbsp/><nbsp/>loop<nbsp/>do
<nbsp/><nbsp/><nbsp/><nbsp/>mutex.synchronize<nbsp/>do
<nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/>difference<nbsp/>+=<nbsp/>(count1<nbsp/>-<nbsp/>count2).abs
<nbsp/><nbsp/><nbsp/><nbsp/>end
<nbsp/><nbsp/>end
end
</alltt>
</codefragment>
<p/>
<codefragment>
<fullcode><![CDATA[!-  require 'thread'
!-  mutex = Mutex.new
!-  
!-  count1 = count2 = 0
!-  difference = 0
!-  counter = Thread.new do
!-    loop do
!-      mutex.synchronize do
!-        count1 += 1
!-        count2 += 1
!-      end
!-    end
!-  end
!-  spy = Thread.new do
!-    loop do
!-      mutex.synchronize do
!-        difference += (count1 - count2).abs
!-      end
!-    end
!-  end
  sleep 1      #!sh!
  mutex.lock   #!sh!
  count1
  count2
  difference
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>sleep<nbsp/>1</tt></td>
</tr>
<tr>
<td colspan="3"><tt>mutex.lock</tt></td>
</tr>
<tr>
  <td><tt>count1</tt></td>
  <td>&#187;</td>
  <td><tt>21636</tt></td>
</tr>
<tr>
  <td><tt>count2</tt></td>
  <td>&#187;</td>
  <td><tt>21636</tt></td>
</tr>
<tr>
  <td><tt>difference</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
By placing all accesses to the shared data under control of a mutex,
we ensure consistency. Unfortunately, as you can see from the numbers,
we also suffer quite a performance penalty. 
<subsubsection>Condition Variables</subsubsection>
<p/>
Using a mutex to protect critical data is sometimes not enough.
Suppose you are in a critical section, but you need to wait for some
particular resource.  If your thread goes to sleep waiting for this
resource, it is possible that no other thread will be able to release
the resource because it cannot enter the critical section---the original
process still has it locked. You need to be able to give up temporarily
your exclusive use of the critical region and simultaneously tell
people that you're waiting for a resource. When the resource becomes
available, you need to be able to grab it <em>and</em> reobtain the
lock on the critical region, all in one step.
<p/>
This is where condition variables come in. A condition variable is
simply a semaphore that is associated with a resource and is
used within the protection of a particular mutex. When you need a
resource that's unavailable, you wait on
a condition variable. That action releases the lock on the
corresponding mutex. When some other thread signals that the resource
is available, the original thread comes off the wait and
simultaneously regains the lock on the critical region.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[  require 'thread'
  mutex = Mutex.new
  cv = ConditionVariable.new

  a = Thread.new {
    mutex.synchronize {
      puts "A: I have critical section, but will wait for cv"
      cv.wait(mutex)
      puts "A: I have critical section again! I rule!"
    }
  }

  puts "(Later, back at the ranch...)"

  b = Thread.new {
    mutex.synchronize {
      puts "B: Now I am critical, but am done with cv"
      cv.signal
      puts "B: I am still critical, finishing up"
    }
  }
  a.join
  b.join
]]></fullcode>
require<nbsp/>'thread'
mutex<nbsp/>=<nbsp/>Mutex.new
cv<nbsp/>=<nbsp/>ConditionVariable.new
<p/>
a<nbsp/>=<nbsp/>Thread.new<nbsp/>{
<nbsp/><nbsp/>mutex.synchronize<nbsp/>{
<nbsp/><nbsp/><nbsp/><nbsp/>puts<nbsp/>"A:<nbsp/>I<nbsp/>have<nbsp/>critical<nbsp/>section,<nbsp/>but<nbsp/>will<nbsp/>wait<nbsp/>for<nbsp/>cv"
<nbsp/><nbsp/><nbsp/><nbsp/>cv.wait(mutex)
<nbsp/><nbsp/><nbsp/><nbsp/>puts<nbsp/>"A:<nbsp/>I<nbsp/>have<nbsp/>critical<nbsp/>section<nbsp/>again!<nbsp/>I<nbsp/>rule!"
<nbsp/><nbsp/>}
}
<p/>
puts<nbsp/>"(Later,<nbsp/>back<nbsp/>at<nbsp/>the<nbsp/>ranch...)"
<p/>
b<nbsp/>=<nbsp/>Thread.new<nbsp/>{
<nbsp/><nbsp/>mutex.synchronize<nbsp/>{
<nbsp/><nbsp/><nbsp/><nbsp/>puts<nbsp/>"B:<nbsp/>Now<nbsp/>I<nbsp/>am<nbsp/>critical,<nbsp/>but<nbsp/>am<nbsp/>done<nbsp/>with<nbsp/>cv"
<nbsp/><nbsp/><nbsp/><nbsp/>cv.signal
<nbsp/><nbsp/><nbsp/><nbsp/>puts<nbsp/>"B:<nbsp/>I<nbsp/>am<nbsp/>still<nbsp/>critical,<nbsp/>finishing<nbsp/>up"
<nbsp/><nbsp/>}
}
a.join
b.join
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
A:<nbsp/>I<nbsp/>have<nbsp/>critical<nbsp/>section,<nbsp/>but<nbsp/>will<nbsp/>wait<nbsp/>for<nbsp/>cv(Later,<nbsp/>back<nbsp/>at<nbsp/>the<nbsp/>ranch...)
<p/>
B:<nbsp/>Now<nbsp/>I<nbsp/>am<nbsp/>critical,<nbsp/>but<nbsp/>am<nbsp/>done<nbsp/>with<nbsp/>cv
B:<nbsp/>I<nbsp/>am<nbsp/>still<nbsp/>critical,<nbsp/>finishing<nbsp/>up
A:<nbsp/>I<nbsp/>have<nbsp/>critical<nbsp/>section<nbsp/>again!<nbsp/>I<nbsp/>rule!
</alltt>
</codefragment>
<p/>
For alternative implementations of synchronization mechanisms, see
<tt>monitor.rb</tt> and <tt>sync.rb</tt> in the <tt>lib</tt> subdirectory of the
distribution.
<section>Running Multiple Processes</section>
<p/>
Sometimes
you may want to split a task into several process-sized
chunks---or perhaps you need to run a separate process that was not
written in Ruby.  Not a problem: Ruby has a number of methods by which 
you may spawn and manage separate processes.
<subsection>Spawning New Processes</subsection>
<p/>
There are several ways to spawn a separate process; the easiest is to
run some command and wait for it to complete.  You might find yourself
doing this to run some separate command or retrieve data from the host
system. Ruby does this for you with the <meth>system</meth> and backquote
methods.
<p/>
<codefragment>
<fullcode><![CDATA[  system("tar xzf test.tgz")
  result = `date`
  result
]]></fullcode><rubycode>
<tr>
  <td><tt>system("tar<nbsp/>xzf<nbsp/>test.tgz")</tt></td>
  <td>&#187;</td>
  <td><tt>tar<nbsp/>(child):<nbsp/>Cannot<nbsp/>open<nbsp/>archive<nbsp/>test.tgz:<nbsp/>No<nbsp/>such<nbsp/>file<nbsp/>or<nbsp/>directory\ntar<nbsp/>(child):<nbsp/>Error<nbsp/>is<nbsp/>not<nbsp/>recoverable:<nbsp/>exiting<nbsp/>now\ntar:<nbsp/>Child<nbsp/>returned<nbsp/>status<nbsp/>2\ntar:<nbsp/>Error<nbsp/>exit<nbsp/>delayed<nbsp/>from<nbsp/>previous<nbsp/>errors\nfalse</tt></td>
</tr>
<tr>
<td colspan="3"><tt>result<nbsp/>=<nbsp/>`date`</tt></td>
</tr>
<tr>
  <td><tt>result</tt></td>
  <td>&#187;</td>
  <td><tt>"Sun<nbsp/>Mar<nbsp/><nbsp/>4<nbsp/>23:24:12<nbsp/>CST<nbsp/>2001\n"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
The method <mmm><file>kernel</file><front>Kernel</front><back>system</back><mref>system</mref></mmm> executes the given command in a
subprocess; it returns <const>true</const> if the command was
found and executed properly, <const>false</const> otherwise. In case of
failure, you'll find the subprocess's exit code in the global variable 
<var>$?</var>.
<p/>
One problem with <meth>system</meth> is that the command's output will
simply go to the same destination as your program's output, which may
not be what you want.  To capture the standard output of a
subprocess, you can use the backquotes, as with <tt>`date`</tt> in
the previous example.  Remember that you may need to use
<cim><file>string</file><front>String</front><back>chomp</back><mref>chomp</mref></cim> to remove the line-ending characters from the
result.
<p/>
Okay, this is fine for simple cases---we can run some other process
and get the return status.  But many times we need a bit more control
than that. We'd like to carry on a conversation with the subprocess,
possibly sending it data and possibly getting some back.
The method <ccm><file>io</file><front>IO</front><back>popen</back><mref>popen</mref></ccm> does just this. The <meth>popen</meth> method
runs a command as a subprocess and connects that subprocess's
standard input and standard output to a Ruby <classname>IO</classname> object. Write to
the <classname>IO</classname> object, and the subprocess can read it on standard
input. Whatever the subprocess writes is available in the Ruby program 
by reading from the <classname>IO</classname> object.
<p/>
For example, on our systems one of the more useful utilities is
<tt>pig</tt>, a program that reads words from standard input and prints
them in pig Latin (or igpay atinlay). We can use this when our Ruby
programs need to send us output that our 5-year-olds shouldn't be able to
understand.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[  pig = IO.popen("pig", "w+")
  pig.puts "ice cream after they go to bed"
  pig.close_write
  puts pig.gets
]]></fullcode>
pig<nbsp/>=<nbsp/>IO.popen("pig",<nbsp/>"w+")
pig.puts<nbsp/>"ice<nbsp/>cream<nbsp/>after<nbsp/>they<nbsp/>go<nbsp/>to<nbsp/>bed"
pig.close_write
puts<nbsp/>pig.gets
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
iceway<nbsp/>eamcray<nbsp/>afterway<nbsp/>eythay<nbsp/>ogay<nbsp/>otay<nbsp/>edbay
</alltt>
</codefragment>
<p/>
This example illustrates both the apparent simplicity and the real-world
complexities involved in driving subprocesses through pipes. The code
certainly looks simple enough: open the pipe, write a phrase, and read
back the response. But it turns out that the <tt>pig</tt> program doesn't
flush the output it writes. Our original attempt at this example,
which had a <tt>pig.puts</tt> followed by a <tt>pig.gets</tt>, hung forever.
The <tt>pig</tt> program processed our input, but its response was never
written to the pipe. We had to insert the <tt>pig.close_write</tt> line.
This sends an end-of-file to <tt>pig</tt>'s standard input, and the output
we're looking for gets flushed as <tt>pig</tt> terminates.
<p/>
There's one more twist to <meth>popen</meth>. If the command you pass it
is a single minus sign (``--''), <meth>popen</meth> will fork a new Ruby
interpreter.
Both this and the original interpreter will continue
running by returning from the <meth>popen</meth>. The original process
will receive an <classname>IO</classname> object back, while the child will receive <tt>nil</tt>.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[  pipe = IO.popen("-","w+")
  if pipe
    pipe.puts "Get a job!"
    $stderr.puts "Child says '#{pipe.gets.chomp}'"
  else
    $stderr.puts "Dad says '#{gets.chomp}'"
    puts "OK"
  end
]]></fullcode>
pipe<nbsp/>=<nbsp/>IO.popen("-","w+")
if<nbsp/>pipe
<nbsp/><nbsp/>pipe.puts<nbsp/>"Get<nbsp/>a<nbsp/>job!"
<nbsp/><nbsp/>$stderr.puts<nbsp/>"Child<nbsp/>says<nbsp/>'#{pipe.gets.chomp}'"
else
<nbsp/><nbsp/>$stderr.puts<nbsp/>"Dad<nbsp/>says<nbsp/>'#{gets.chomp}'"
<nbsp/><nbsp/>puts<nbsp/>"OK"
end
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
Dad<nbsp/>says<nbsp/>'Get<nbsp/>a<nbsp/>job!'
Child<nbsp/>says<nbsp/>'OK'
</alltt>
</codefragment>
<p/>
In addition to <tt>popen</tt>, the traditional Unix calls
<mmm><file>kernel</file><front>Kernel</front><back>fork</back><mref>fork</mref></mmm>, <mmm><file>kernel</file><front>Kernel</front><back>exec</back><mref>exec</mref></mmm>, and <ccm><file>io</file><front>IO</front><back>pipe</back><mref>pipe</mref></ccm> are
available on platforms that support them.  The file-naming convention
of many <classname>IO</classname> methods and <mmm><file>kernel</file><front>Kernel</front><back>open</back><mref>open</mref></mmm> will also spawn
subprocesses if you put a ``<tt>|</tt>''
as the first character of the
filename (see the introduction to class <classname>IO</classname> on page 329 for
details).  Note that you <em>cannot</em> create pipes using
<ccm><file>file</file><front>File</front><back>new</back><mref>new</mref></ccm>; it's just for files.
<subsection>Independent Children</subsection>
<p/>
Sometimes we don't need to be quite so hands-on: we'd like to give
the subprocess its assignment and then go on about our business. Some
time later, we'll check in with it to see if it has finished. For 
instance, we might want to kick off a long-running external sort.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[  exec("sort testfile > output.txt") if fork == nil
  # The sort is now running in a child process
  # carry on processing in the main program
  
  # then wait for the sort to finish
  Process.wait
!- File.delete('output.txt')
]]></fullcode>
exec("sort<nbsp/>testfile<nbsp/>&gt;<nbsp/>output.txt")<nbsp/>if<nbsp/>fork<nbsp/>==<nbsp/>nil
#<nbsp/>The<nbsp/>sort<nbsp/>is<nbsp/>now<nbsp/>running<nbsp/>in<nbsp/>a<nbsp/>child<nbsp/>process
#<nbsp/>carry<nbsp/>on<nbsp/>processing<nbsp/>in<nbsp/>the<nbsp/>main<nbsp/>program
<p/>
#<nbsp/>then<nbsp/>wait<nbsp/>for<nbsp/>the<nbsp/>sort<nbsp/>to<nbsp/>finish
Process.wait
</alltt>
</codefragment>
<p/>
The call to <mmm><file>kernel</file><front>Kernel</front><back>fork</back><mref>fork</mref></mmm> returns a process id in the parent, and 
<tt>nil</tt> in the child, so the child process will perform the
<mmm><file>kernel</file><front>Kernel</front><back>exec</back><mref>exec</mref></mmm> call and run sort. Sometime later, we issue a
<mmm><file>process</file><front>Process</front><back>wait</back><mref>wait</mref></mmm> call, which waits for the sort to complete (and
returns its process id).
<p/>
If you'd rather be notified when a child exits (instead of just
waiting around), you can set up a signal handler using
<mmm><file>kernel</file><front>Kernel</front><back>trap</back><mref>trap</mref></mmm> (described on page 431).  Here we set
up a trap on <tt>SIGCLD</tt>, which is the signal sent on ``death of child
process.''
<p/>
<codefragment>
<alltt><fullcode><![CDATA[  trap("CLD") {
    pid = Process.wait
    puts "Child pid #{pid}: terminated"
!- File.delete('output.txt')
    exit
  }

  exec("sort testfile > output.txt") if fork == nil

  # do other stuff...
!-  sleep 30
  
]]></fullcode>
trap("CLD")<nbsp/>{
<nbsp/><nbsp/>pid<nbsp/>=<nbsp/>Process.wait
<nbsp/><nbsp/>puts<nbsp/>"Child<nbsp/>pid<nbsp/>#{pid}:<nbsp/>terminated"
<nbsp/><nbsp/>exit
}
<p/>
exec("sort<nbsp/>testfile<nbsp/>&gt;<nbsp/>output.txt")<nbsp/>if<nbsp/>fork<nbsp/>==<nbsp/>nil
<p/>
#<nbsp/>do<nbsp/>other<nbsp/>stuff...
<p/>
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
Child<nbsp/>pid<nbsp/>14481:<nbsp/>terminated
</alltt>
</codefragment>
<subsection>Blocks and Subprocesses</subsection>
<p/>
<ccm><file>io</file><front>IO</front><back>popen</back><mref>popen</mref></ccm> works with a block in pretty much the same way as
<ccm><file>file</file><front>File</front><back>open</back><mref>open</mref></ccm> does.
Pass <meth>popen</meth> a command, such as <tt>date</tt>, and the
block will be passed an <classname>IO</classname> object as a parameter.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[  IO.popen ("date") { |f| puts "Date is #{f.gets}" }
]]></fullcode>
IO.popen<nbsp/>("date")<nbsp/>{<nbsp/>|f|<nbsp/>puts<nbsp/>"Date<nbsp/>is<nbsp/>#{f.gets}"<nbsp/>}
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
Date<nbsp/>is<nbsp/>Sun<nbsp/>Mar<nbsp/><nbsp/>4<nbsp/>23:24:12<nbsp/>CST<nbsp/>2001
</alltt>
</codefragment>
<p/>
The <classname>IO</classname> object will be closed automatically when the code block
exits, just as it is with <ccm><file>file</file><front>File</front><back>open</back><mref>open</mref></ccm>.
<p/>
If you associate a block with <mmm><file>kernel</file><front>Kernel</front><back>fork</back><mref>fork</mref></mmm>, the code in the
block will be run in a Ruby subprocess, and the parent will continue
after the block.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[  fork do
    puts "In child, pid = #$$"
    exit 99
  end
  pid = Process.wait
  puts "Child terminated, pid = #{pid}, exit code = #{$? >> 8}"
]]></fullcode>
fork<nbsp/>do
<nbsp/><nbsp/>puts<nbsp/>"In<nbsp/>child,<nbsp/>pid<nbsp/>=<nbsp/>#$$"
<nbsp/><nbsp/>exit<nbsp/>99
end
pid<nbsp/>=<nbsp/>Process.wait
puts<nbsp/>"Child<nbsp/>terminated,<nbsp/>pid<nbsp/>=<nbsp/>#{pid},<nbsp/>exit<nbsp/>code<nbsp/>=<nbsp/>#{$?<nbsp/>&gt;&gt;<nbsp/>8}"
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
In<nbsp/>child,<nbsp/>pid<nbsp/>=<nbsp/>14488
Child<nbsp/>terminated,<nbsp/>pid<nbsp/>=<nbsp/>14488,<nbsp/>exit<nbsp/>code<nbsp/>=<nbsp/>99
</alltt>
</codefragment>
<p/>
One last thing. Why do we shift the exit code in <var>$?</var> 8 bits to
the right before displaying it? This is a ``feature'' of Posix
systems: the bottom 8 bits of an exit code contain the reason the
program terminated, while the higher-order 8 bits hold the actual
exit
code.
</chapter>
</ppdoc>