<ppdoc>
<copyright>
Copyright (c) 2001 by Addison Wesley Longman, Inc. 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/).
<p/>
Distribution of substantively modified versions of this document is
prohibited without the explicit permission of the copyright holder.
<p/>
Distribution of the work or derivative of the work in any standard
(paper) book form is prohibited unless prior permission is obtained
from the copyright holder.
</copyright>
<class name="Thread" super="Object" type="class" ref="xref-000001">
<p/>
  <classname>Thread</classname> encapsulates the behavior of a thread of execution,
  including the main thread of the Ruby script. See the tutorial in
  Chapter 11, beginning on page 111.
<p/>
  In the descriptions that follow, the
  parameter <obj>aSymbol</obj> refers to a symbol, which is either a
  quoted string or a <classname>Symbol</classname> (such as <tt>:name</tt>).<methods type="class">
<p/>
        <method name="abort_on_exception" ref="abort_on_exception">
      <callseq>
        Thread.abort_on_exception
        <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
              Returns the status of the global ``abort on exception''
      condition.  The default is <const>false</const>.      
      When set to <const>true</const>, will cause all threads to abort (the
      process will <tt>exit(0)</tt>) if an
      exception is raised in any thread. See also <ccm><file>thread</file><front>Thread</front><back>abort_on_exception=</back><mref>abort_on_exception_eq</mref></ccm>.
<p/>
      </desc>
    </method>
<p/>
        <method name="abort_on_exception=" ref="abort_on_exception_eq">
      <callseq>
        Thread.abort_on_exception= 
        <obj>aBoolean</obj><returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
      When set to <const>true</const>, all threads will abort if an
      exception is raised. Returns the new state.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        Thread.abort_on_exception = true
        t1 = Thread.new do
          puts  "In second thread"
          raise "Raise exception"
        end
        t1.join
        print "not reached\n"
]]></fullcode>
Thread.abort_on_exception<nbsp/>=<nbsp/>true
t1<nbsp/>=<nbsp/>Thread.new<nbsp/>do
<nbsp/><nbsp/>puts<nbsp/><nbsp/>"In<nbsp/>second<nbsp/>thread"
<nbsp/><nbsp/>raise<nbsp/>"Raise<nbsp/>exception"
end
t1.join
print<nbsp/>"not<nbsp/>reached\n"
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
In<nbsp/>second<nbsp/>thread
prog.rb:4:<nbsp/>Raise<nbsp/>exception<nbsp/>(RuntimeError)
	from<nbsp/>prog.rb:2:in<nbsp/>`initialize'
	from<nbsp/>prog.rb:2:in<nbsp/>`new'
	from<nbsp/>prog.rb:2
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="critical" ref="critical">
      <callseq>
        Thread.critical
        <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
      Returns the status of the global ``thread critical''
      condition. 
<p/>
      </desc>
    </method>
<p/>
        <method name="critical=" ref="critical_eq">
      <callseq>
        Thread.critical= <obj>aBoolean</obj>
        <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
      Sets the status of the global ``thread critical''
      condition and returns it.
      When set to <const>true</const>, prohibits scheduling of any existing
      thread.  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, and raising an exception) may
      cause a thread to be scheduled even when in a critical section.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        count=0
        Thread.new { while true; sleep(1); print "a "; count+=1; end }
        while count < 3 do end # no-op wait
        Thread.critical = true 
        puts "no more a's will come out."
]]></fullcode>
count=0
Thread.new<nbsp/>{<nbsp/>while<nbsp/>true;<nbsp/>sleep(1);<nbsp/>print<nbsp/>"a<nbsp/>";<nbsp/>count+=1;<nbsp/>end<nbsp/>}
while<nbsp/>count<nbsp/>&lt;<nbsp/>3<nbsp/>do<nbsp/>end<nbsp/>#<nbsp/>no-op<nbsp/>wait
Thread.critical<nbsp/>=<nbsp/>true
puts<nbsp/>"no<nbsp/>more<nbsp/>a's<nbsp/>will<nbsp/>come<nbsp/>out."
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
a<nbsp/>a<nbsp/>a<nbsp/>no<nbsp/>more<nbsp/>a's<nbsp/>will<nbsp/>come<nbsp/>out.
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="current" ref="current">
      <callseq>
        Thread.current
        <returns><obj>aThread</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the currently executing thread.
<p/>
<codefragment>
<fullcode><![CDATA[        Thread.current
]]></fullcode><rubycode>
<tr>
  <td><tt>Thread.current</tt></td>
  <td>&#187;</td>
  <td><tt>#&lt;Thread:0x401be5c8<nbsp/>run&gt;</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="exit" ref="exit">
      <callseq>
        Thread.exit
      </callseq>
      <desc>
<p/>
      Terminates the currently running thread and schedules another
      thread to be run.  If this thread is already marked to be
      killed, <meth>exit</meth> returns the <classname>Thread</classname>.  If this is the main thread, or
      the last thread, exit the process.
<p/>
      </desc>
    </method>
<p/>
        <method name="fork" ref="fork">
      <callseq>
        Thread.fork <block>{ <blockbody>block</blockbody> }</block>
<returns><obj>aThread</obj></returns>
      </callseq>
      <desc>
<p/>
      Synonym for <ccm><file>thread</file><front>Thread</front><back>new</back><mref>new</mref></ccm>.
<p/>
      </desc>
    </method>
<p/>
        <method name="kill" ref="kill">
      <callseq>
        Thread.kill( <obj>aThread</obj> )
      </callseq>
      <desc>
<p/>
      Causes the given thread to exit (see <ccm><file>thread</file><front>Thread</front><back>exit</back><mref>exit</mref></ccm>).
<p/>
<codefragment>
<fullcode><![CDATA[        count = 0
        a = Thread.new { while true do  count += 1 end }
        sleep(1)
        Thread.kill(a)
        count
        a.alive?
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>count<nbsp/>=<nbsp/>0</tt></td>
</tr>
<tr>
<td colspan="3"><tt>a<nbsp/>=<nbsp/>Thread.new<nbsp/>{<nbsp/>while<nbsp/>true<nbsp/>do<nbsp/><nbsp/>count<nbsp/>+=<nbsp/>1<nbsp/>end<nbsp/>}</tt></td>
</tr>
<tr>
  <td><tt>sleep(1)</tt></td>
  <td>&#187;</td>
  <td><tt>1</tt></td>
</tr>
<tr>
  <td><tt>Thread.kill(a)</tt></td>
  <td>&#187;</td>
  <td><tt>#&lt;Thread:0x401b5cac<nbsp/>dead&gt;</tt></td>
</tr>
<tr>
  <td><tt>count</tt></td>
  <td>&#187;</td>
  <td><tt>903877</tt></td>
</tr>
<tr>
  <td><tt>a.alive?</tt></td>
  <td>&#187;</td>
  <td><tt>false</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="list" ref="list">
      <callseq>
        Thread.list <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns an array of <classname>Thread</classname> objects for all threads that are
      either runnable or stopped.
<p/>
<codefragment>
<fullcode><![CDATA[        Thread.new { sleep(200) }               #!sh!
        Thread.new { 1000000.times {|i| i*i } } #!sh!
        Thread.new { Thread.stop }              #!sh!
        l = Thread.list
        l
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>Thread.new<nbsp/>{<nbsp/>sleep(200)<nbsp/>}</tt></td>
</tr>
<tr>
<td colspan="3"><tt>Thread.new<nbsp/>{<nbsp/>1000000.times<nbsp/>{|i|<nbsp/>i*i<nbsp/>}<nbsp/>}</tt></td>
</tr>
<tr>
<td colspan="3"><tt>Thread.new<nbsp/>{<nbsp/>Thread.stop<nbsp/>}</tt></td>
</tr>
<tr>
<td colspan="3"><tt>l<nbsp/>=<nbsp/>Thread.list</tt></td>
</tr>
<tr>
  <td><tt>l</tt></td>
  <td>&#187;</td>
  <td><tt>[#&lt;Thread:0x401b5644<nbsp/>sleep&gt;,<nbsp/>#&lt;Thread:0x401b59f0<nbsp/>run&gt;,<nbsp/>#&lt;Thread:0x401b5cac<nbsp/>sleep&gt;,<nbsp/>#&lt;Thread:0x401be5c8<nbsp/>run&gt;]</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="main" ref="main">
      <callseq>
        Thread.main
        <returns><obj>aThread</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the main thread for the process.
<p/>
<codefragment>
<fullcode><![CDATA[        Thread.main
]]></fullcode><rubycode>
<tr>
  <td><tt>Thread.main</tt></td>
  <td>&#187;</td>
  <td><tt>#&lt;Thread:0x401be5c8<nbsp/>run&gt;</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="new" ref="new">
      <callseq>
        Thread.new( <optz><obj>arg</obj></optz> ) <block>{| args | <blockbody>block</blockbody> }</block>
<p/>
        <returns><obj>aThread</obj></returns>
      </callseq>
      <desc>
<p/>
      Creates a new thread to execute the instructions given in
      <obj>block</obj>, and begins running it. Any arguments passed to
      <ccm><file>thread</file><front>Thread</front><back>new</back><mref>new</mref></ccm> are passed into the block.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        x = Thread.new { sleep .1; print "x"; print "y"; print "z" }
        a = Thread.new { print "a"; print "b"; sleep .2; print "c" }
        x.join # Let the threads finish before
        a.join # main thread exits...
!-        print "\n"
]]></fullcode>
x<nbsp/>=<nbsp/>Thread.new<nbsp/>{<nbsp/>sleep<nbsp/>.1;<nbsp/>print<nbsp/>"x";<nbsp/>print<nbsp/>"y";<nbsp/>print<nbsp/>"z"<nbsp/>}
a<nbsp/>=<nbsp/>Thread.new<nbsp/>{<nbsp/>print<nbsp/>"a";<nbsp/>print<nbsp/>"b";<nbsp/>sleep<nbsp/>.2;<nbsp/>print<nbsp/>"c"<nbsp/>}
x.join<nbsp/>#<nbsp/>Let<nbsp/>the<nbsp/>threads<nbsp/>finish<nbsp/>before
a.join<nbsp/>#<nbsp/>main<nbsp/>thread<nbsp/>exits...
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
abxyzc
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="pass" ref="pass">
      <callseq>
        Thread.pass
      </callseq>
      <desc>
<p/>
      Invokes the thread scheduler to pass execution to another
      thread.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        a = Thread.new { print "a"; Thread.pass; 
                         print "b"; Thread.pass;
                         print "c" }
        b = Thread.new { print "x"; Thread.pass; 
                         print "y"; Thread.pass;
                         print "z" }
        a.join
        b.join
!-        print "\n"
]]></fullcode>
a<nbsp/>=<nbsp/>Thread.new<nbsp/>{<nbsp/>print<nbsp/>"a";<nbsp/>Thread.pass;
<nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/>print<nbsp/>"b";<nbsp/>Thread.pass;
<nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/>print<nbsp/>"c"<nbsp/>}
b<nbsp/>=<nbsp/>Thread.new<nbsp/>{<nbsp/>print<nbsp/>"x";<nbsp/>Thread.pass;
<nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/>print<nbsp/>"y";<nbsp/>Thread.pass;
<nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/>print<nbsp/>"z"<nbsp/>}
a.join
b.join
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
axbycz
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="start" ref="start">
      <callseq>
        Thread.start( <optz><obj>args</obj></optz> ) <block>{| args | <blockbody>block</blockbody> }</block>
<p/>
        <returns><obj>aThread</obj></returns>
      </callseq>
      <desc>
<p/>
      Basically the same as <ccm><file>thread</file><front>Thread</front><back>new</back><mref>new</mref></ccm>. However, if class
      <classname>Thread</classname> is subclassed, then calling <meth>start</meth> in that
      subclass will not invoke the subclass's <meth>initialize</meth> method.
<p/>
      </desc>
    </method>
<p/>
        <method name="stop" ref="stop">
      <callseq>
        Thread.stop
      </callseq>
      <desc>
<p/>
      Stops execution of the current thread, putting it into a
      ``sleep'' state, and schedules execution of another thread.
      Resets the ``critical'' condition to <const>false</const>.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        a = Thread.new { print "a"; Thread.stop; print "c" }
        Thread.pass
        print "b"
        a.run
        a.join
!- puts        
]]></fullcode>
a<nbsp/>=<nbsp/>Thread.new<nbsp/>{<nbsp/>print<nbsp/>"a";<nbsp/>Thread.stop;<nbsp/>print<nbsp/>"c"<nbsp/>}
Thread.pass
print<nbsp/>"b"
a.run
a.join
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
abc
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
  <methods type="instance">
<p/>
        <method name="[ ]" ref="_ob_cb">
      <callseq>
<p/>
        <obj>thr</obj>[ <obj>aSymbol</obj> ] <returns><obj>anObject</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Attribute Reference---Returns the value of a thread-local
      variable, using either a symbol or a string name.  If the
      specified variable does not exist, returns <tt>nil</tt>.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[         a = Thread.new { Thread.current["name"] = "A"; Thread.stop }
         b = Thread.new { Thread.current[:name]  = "B"; Thread.stop }
         c = Thread.new { Thread.current["name"] = "C"; Thread.stop }
         Thread.list.each {|x| print x.inspect, x[:name], "\n" }
]]></fullcode>
a<nbsp/>=<nbsp/>Thread.new<nbsp/>{<nbsp/>Thread.current["name"]<nbsp/>=<nbsp/>"A";<nbsp/>Thread.stop<nbsp/>}
b<nbsp/>=<nbsp/>Thread.new<nbsp/>{<nbsp/>Thread.current[:name]<nbsp/><nbsp/>=<nbsp/>"B";<nbsp/>Thread.stop<nbsp/>}
c<nbsp/>=<nbsp/>Thread.new<nbsp/>{<nbsp/>Thread.current["name"]<nbsp/>=<nbsp/>"C";<nbsp/>Thread.stop<nbsp/>}
Thread.list.each<nbsp/>{|x|<nbsp/>print<nbsp/>x.inspect,<nbsp/>x[:name],<nbsp/>"\n"<nbsp/>}
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
#&lt;Thread:0x401b53c4<nbsp/>sleep&gt;C
#&lt;Thread:0x401b5734<nbsp/>sleep&gt;B
#&lt;Thread:0x401b5cac<nbsp/>sleep&gt;A
#&lt;Thread:0x401be5c8<nbsp/>run&gt;nil
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="[ ]=" ref="_ob_cb_eq">
      <callseq>
<p/>
        <obj>thr</obj>[ <obj>aSymbol</obj> ]  = <obj>anObject</obj><returns><obj>anObject</obj></returns>
<p/>
      </callseq>
      <desc>
              Attribute Assignment---Sets or creates the value of a thread-local
      variable, using either a symbol or a string. See also
      <cim><file>thread</file><front>Thread</front><back>[]</back><mref>_ob_cb</mref></cim>.
<p/>
      </desc>
    </method>
<p/>
        <method name="abort_on_exception" ref="abort_on_exception">
      <callseq>
        <obj>thr</obj>.abort_on_exception
        <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
              Returns the status of the ``abort on exception''
      condition for <obj>thr</obj>.  The default is <const>false</const>.
      See also <ccm><file>thread</file><front>Thread</front><back>abort_on_exception=</back><mref>abort_on_exception_eq</mref></ccm>.
<p/>
      </desc>
    </method>
<p/>
        <method name="abort_on_exception=" ref="abort_on_exception_eq">
      <callseq>
        <obj>thr</obj>.abort_on_exception= 
        <const>true</const> or <const>false</const><returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
            When set to <const>true</const>, causes all threads (including the main
      program) to abort if an exception is raised in <obj>thr</obj>.
      The process will effectively <tt>exit(0)</tt>.
<p/>
      </desc>
    </method>
<p/>
        <method name="alive?" ref="alive_qm">
      <callseq>
        <obj>thr</obj>.alive?
        <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
      Returns <const>true</const> if <obj>thr</obj> is running or sleeping.
<p/>
<codefragment>
<fullcode><![CDATA[        Thread.current.alive?
]]></fullcode><rubycode>
<tr>
  <td><tt>Thread.current.alive?</tt></td>
  <td>&#187;</td>
  <td><tt>true</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="exit" ref="exit">
      <callseq>
        <obj>thr</obj>.exit <returns><obj>thr</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Terminates <obj>thr</obj> and schedules another
      thread to be run.  If this thread is already marked to be
      killed, <meth>exit</meth> returns the <classname>Thread</classname>.  If this is the main thread, or
      the last thread, exits the process.
<p/>
      </desc>
    </method>
<p/>
        <method name="join" ref="join">
      <callseq>
        <obj>thr</obj>.join
        <returns><obj>thr</obj></returns>
      </callseq>
      <desc>
<p/>
      The calling thread will suspend execution and run <obj>thr</obj>. Does
      not return until
      <obj>thr</obj> exits.  Any threads not joined will be killed when the
      main program exits.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        a = Thread.new { print "a"; sleep(10); print "b"; print "c" }
        x = Thread.new { print "x"; Thread.pass; print "y"; print "z" }
        x.join # Let x thread finish, a will be killed on exit.
!-      puts
]]></fullcode>
a<nbsp/>=<nbsp/>Thread.new<nbsp/>{<nbsp/>print<nbsp/>"a";<nbsp/>sleep(10);<nbsp/>print<nbsp/>"b";<nbsp/>print<nbsp/>"c"<nbsp/>}
x<nbsp/>=<nbsp/>Thread.new<nbsp/>{<nbsp/>print<nbsp/>"x";<nbsp/>Thread.pass;<nbsp/>print<nbsp/>"y";<nbsp/>print<nbsp/>"z"<nbsp/>}
x.join<nbsp/>#<nbsp/>Let<nbsp/>x<nbsp/>thread<nbsp/>finish,<nbsp/>a<nbsp/>will<nbsp/>be<nbsp/>killed<nbsp/>on<nbsp/>exit.
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
axyz
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="key?" ref="key_qm">
      <callseq>
                <obj>thr</obj>.key?( <obj>aSymbol</obj> ) <returns><const>true</const> or <const>false</const></returns><br/>
      </callseq>
      <desc>
<p/>
      Returns <const>true</const> if the given string (or symbol) exists as a 
      thread-local variable.
<p/>
<codefragment>
<fullcode><![CDATA[        me = Thread.current
        me[:oliver] = "a"
        me.key?(:oliver)
        me.key?(:stanley)
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>me<nbsp/>=<nbsp/>Thread.current</tt></td>
</tr>
<tr>
<td colspan="3"><tt>me[:oliver]<nbsp/>=<nbsp/>"a"</tt></td>
</tr>
<tr>
  <td><tt>me.key?(:oliver)</tt></td>
  <td>&#187;</td>
  <td><tt>true</tt></td>
</tr>
<tr>
  <td><tt>me.key?(:stanley)</tt></td>
  <td>&#187;</td>
  <td><tt>false</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="kill" ref="kill">
      <callseq>
        <obj>thr</obj>.kill
      </callseq>
      <desc>
<p/>
      Synonym for <cim><file>thread</file><front>Thread</front><back>exit</back><mref>exit</mref></cim>.
<p/>
      </desc>
    </method>
<p/>
        <method name="priority" ref="priority">
      <callseq>
        <obj>thr</obj>.priority
        <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
            Returns the priority of <obj>thr</obj>.  Default is zero; 
      higher-priority threads will run before lower-priority threads.
<p/>
<codefragment>
<fullcode><![CDATA[        Thread.current.priority
]]></fullcode><rubycode>
<tr>
  <td><tt>Thread.current.priority</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="priority=" ref="priority_eq">
      <callseq>
        <obj>thr</obj>.priority= <obj>anInteger</obj>
        <returns><obj>thr</obj></returns>
      </callseq>
      <desc>
<p/>
            Sets the priority of <obj>thr</obj> to <obj>anInteger</obj>.
      Higher-priority threads will run before lower-priority threads.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        count1 = count2 = 0
        a = Thread.new do
              loop { count1 += 1 }
            end
        a.priority = -1
]]></fullcode>
count1<nbsp/>=<nbsp/>count2<nbsp/>=<nbsp/>0
a<nbsp/>=<nbsp/>Thread.new<nbsp/>do
<nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/>loop<nbsp/>{<nbsp/>count1<nbsp/>+=<nbsp/>1<nbsp/>}
<nbsp/><nbsp/><nbsp/><nbsp/>end
a.priority<nbsp/>=<nbsp/>-1
</alltt>
</codefragment>
<p/>
<codefragment>
<fullcode><![CDATA[!-        count1 = 0
!-        count2 = 0
!-        a = Thread.new do
!-              loop { count1 += 1 }
!-            end
!-        a.priority = -1
        b = Thread.new do
              loop { count2 += 1 }
            end
        b.priority = -2
        sleep 1
        Thread.critical = 1
        count1
        count2
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>b<nbsp/>=<nbsp/>Thread.new<nbsp/>do</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/>loop<nbsp/>{<nbsp/>count2<nbsp/>+=<nbsp/>1<nbsp/>}</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/><nbsp/><nbsp/>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt>b.priority<nbsp/>=<nbsp/>-2</tt></td>
</tr>
<tr>
  <td><tt>sleep<nbsp/>1</tt></td>
  <td>&#187;</td>
  <td><tt>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>577581</tt></td>
</tr>
<tr>
  <td><tt>count2</tt></td>
  <td>&#187;</td>
  <td><tt>5751</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="raise" ref="raise">
      <callseq>
        <obj>thr</obj>.raise( <obj>anException</obj> )
      </callseq>
      <desc>
<p/>
      Raises an exception (see <mmm><file>kernel</file><front>Kernel</front><back>raise</back><mref>raise</mref></mmm>
      on page 420 for details) from <obj>thr</obj>.
      The caller does not have to be <obj>thr</obj>.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        Thread.abort_on_exception = true
        a = Thread.new { sleep(200) }
        a.raise("Gotcha")
]]></fullcode>
Thread.abort_on_exception<nbsp/>=<nbsp/>true
a<nbsp/>=<nbsp/>Thread.new<nbsp/>{<nbsp/>sleep(200)<nbsp/>}
a.raise("Gotcha")
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
prog.rb:3:<nbsp/>Gotcha<nbsp/>(RuntimeError)
	from<nbsp/>prog.rb:2:in<nbsp/>`initialize'
	from<nbsp/>prog.rb:2:in<nbsp/>`new'
	from<nbsp/>prog.rb:2
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="run" ref="run">
      <callseq>
        <obj>thr</obj>.run <returns><obj>thr</obj></returns>
      </callseq>
      <desc>
<p/>
      Wakes up <obj>thr</obj>, making it eligible for scheduling. If not
      in a critical section, then invokes the scheduler.  
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        a = Thread.new { puts "a"; Thread.stop; puts "c" }
        Thread.pass
        puts "Got here"
        a.run
        a.join
]]></fullcode>
a<nbsp/>=<nbsp/>Thread.new<nbsp/>{<nbsp/>puts<nbsp/>"a";<nbsp/>Thread.stop;<nbsp/>puts<nbsp/>"c"<nbsp/>}
Thread.pass
puts<nbsp/>"Got<nbsp/>here"
a.run
a.join
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
a
Got<nbsp/>here
c
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="safe_level" ref="safe_level">
      <callseq>
        <obj>thr</obj>.safe_level
        <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the safe level in effect for <obj>thr</obj>.
<p/>
<codefragment>
<fullcode><![CDATA[        Thread.current.safe_level
]]></fullcode><rubycode>
<tr>
  <td><tt>Thread.current.safe_level</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="status" ref="status">
      <callseq>
        <obj>thr</obj>.status
        <returns><obj>aString</obj>, <const>false</const> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Returns the status of <obj>thr</obj>: ``<tt>sleep</tt>'' if <obj>thr</obj> is sleeping 
      or waiting on I/O, ``<tt>run</tt>'' if <obj>thr</obj> is executing,
      <const>false</const> if <obj>thr</obj> terminated normally, and <tt>nil</tt> if
      <obj>thr</obj> terminated with an exception.
<p/>
<codefragment>
<fullcode><![CDATA[        a = Thread.new { raise("die now") }
        b = Thread.new { Thread.stop }
        c = Thread.new { Thread.exit }
!-      c.join
        a.status
        b.status
        c.status
        Thread.current.status
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>a<nbsp/>=<nbsp/>Thread.new<nbsp/>{<nbsp/>raise("die<nbsp/>now")<nbsp/>}</tt></td>
</tr>
<tr>
<td colspan="3"><tt>b<nbsp/>=<nbsp/>Thread.new<nbsp/>{<nbsp/>Thread.stop<nbsp/>}</tt></td>
</tr>
<tr>
<td colspan="3"><tt>c<nbsp/>=<nbsp/>Thread.new<nbsp/>{<nbsp/>Thread.exit<nbsp/>}</tt></td>
</tr>
<tr>
  <td><tt>a.status</tt></td>
  <td>&#187;</td>
  <td><tt>nil</tt></td>
</tr>
<tr>
  <td><tt>b.status</tt></td>
  <td>&#187;</td>
  <td><tt>"sleep"</tt></td>
</tr>
<tr>
  <td><tt>c.status</tt></td>
  <td>&#187;</td>
  <td><tt>false</tt></td>
</tr>
<tr>
  <td><tt>Thread.current.status</tt></td>
  <td>&#187;</td>
  <td><tt>"run"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="stop?" ref="stop_qm">
      <callseq>
        <obj>thr</obj>.stop?
        <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
      Returns <const>true</const> if <obj>thr</obj> is dead or sleeping.
<p/>
<codefragment>
<fullcode><![CDATA[        a = Thread.new { Thread.stop }
        b = Thread.current
        a.stop?
        b.stop?
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>a<nbsp/>=<nbsp/>Thread.new<nbsp/>{<nbsp/>Thread.stop<nbsp/>}</tt></td>
</tr>
<tr>
<td colspan="3"><tt>b<nbsp/>=<nbsp/>Thread.current</tt></td>
</tr>
<tr>
  <td><tt>a.stop?</tt></td>
  <td>&#187;</td>
  <td><tt>true</tt></td>
</tr>
<tr>
  <td><tt>b.stop?</tt></td>
  <td>&#187;</td>
  <td><tt>false</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="value" ref="value">
      <callseq>
        <obj>thr</obj>.value
        <returns><obj>anObject</obj></returns>
      </callseq>
      <desc>
<p/>
      Waits for <obj>thr</obj> to complete (via <cim><file>thread</file><front>Thread</front><back>join</back><mref>join</mref></cim>) and
      returns its value.
<p/>
<codefragment>
<fullcode><![CDATA[        a = Thread.new { 2+2 }
        a.value
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>a<nbsp/>=<nbsp/>Thread.new<nbsp/>{<nbsp/>2+2<nbsp/>}</tt></td>
</tr>
<tr>
  <td><tt>a.value</tt></td>
  <td>&#187;</td>
  <td><tt>4</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="wakeup" ref="wakeup">
      <callseq>
        <obj>thr</obj>.wakeup
        <returns><obj>thr</obj></returns>
      </callseq>
      <desc>
<p/>
      Marks <obj>thr</obj> as eligible for scheduling (it may still remain
      blocked on I/O, however). Does not invoke the scheduler (see
      <cim><file>thread</file><front>Thread</front><back>run</back><mref>run</mref></cim>).
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        c = Thread.new { Thread.stop; puts "hey!" }
        c.wakeup
!-          c.join
]]></fullcode>
c<nbsp/>=<nbsp/>Thread.new<nbsp/>{<nbsp/>Thread.stop;<nbsp/>puts<nbsp/>"hey!"<nbsp/>}
c.wakeup
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
hey!
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
</class>
</ppdoc>
