Class

Thread

Inheritance
< Object

Thread encapsulates the behavior of a thread of execution, including the main thread of the Ruby script.

In the descriptions of the methods in this class, the parameter sym refers to a symbol, which is either a quoted string or a Symbol (such as :name).

Methods

Class

Visibility Signature
public abort_on_exception ()
public abort_on_exception= (p1)
public critical ()
public critical= (p1)
public current ()
public exclusive () {|| ...}
public exit ()
public fork (...)
public kill (p1)
public list ()
public main ()
public new (...)
public new (...)
public pass ()
public start (...)
public stop ()

Instance

Visibility Signature
public [] (p1)
public []= (p1, p2)
public abort_on_exception ()
public abort_on_exception= (p1)
public alive? ()
public exit ()
public exit! ()
public group ()
public inspect ()
public join (...)
public key? (p1)
public keys ()
public kill ()
public kill! ()
public priority ()
public priority= (p1)
public raise (...)
public run ()
public safe_level ()
public status ()
public stop? ()
public terminate ()
public terminate! ()
public value ()
public wakeup ()

Class Method Detail

Thread.abort_on_exception => true or false

Returns the status of the global ``abort on exception’’ condition. The default is false. When set to true, or if the global $DEBUG flag is true (perhaps because the command line option -d was specified) all threads will abort (the process will exit(0)) if an exception is raised in any thread. See also Thread::abort_on_exception=.

Thread.abort_on_exception= boolean => true or false

When set to true, all threads will abort if an exception is raised. Returns the new state.

   Thread.abort_on_exception = true
   t1 = Thread.new do
     puts  "In new thread"
     raise "Exception from thread"
   end
   sleep(1)
   puts "not reached"

produces:

   In new thread
   prog.rb:4: Exception from thread (RuntimeError)
    from prog.rb:2:in `initialize'
    from prog.rb:2:in `new'
    from prog.rb:2

Thread.critical => true or false

Returns the status of the global ``thread critical’’ condition.

Thread.critical= boolean => true or false

Sets the status of the global ``thread critical’’ condition and returns it. When set to true, 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. Thread::critical is not intended for daily use: it is primarily there to support folks writing threading libraries.

Thread.current => thread

Returns the currently executing thread.

   Thread.current   #=> #<Thread:0x401bdf4c run>

exclusive() {|| ...}

Wraps a block in Thread.critical, restoring the original value upon exit from the critical section.

Thread.exit => thread

Terminates the currently running thread and schedules another thread to be run. If this thread is already marked to be killed, exit returns the Thread. If this is the main thread, or the last thread, exit the process.

Thread.start([args]*) {|args| block } => thread
Thread.fork([args]*) {|args| block } => thread

Basically the same as Thread::new. However, if class Thread is subclassed, then calling start in that subclass will not invoke the subclass‘s initialize method.

Thread.kill(thread) => thread

Causes the given thread to exit (see Thread::exit).

   count = 0
   a = Thread.new { loop { count += 1 } }
   sleep(0.1)       #=> 0
   Thread.kill(a)   #=> #<Thread:0x401b3d30 dead>
   count            #=> 93947
   a.alive?         #=> false

Thread.list => array

Returns an array of Thread objects for all threads that are either runnable or stopped.

   Thread.new { sleep(200) }
   Thread.new { 1000000.times {|i| i*i } }
   Thread.new { Thread.stop }
   Thread.list.each {|t| p t}

produces:

   #<Thread:0x401b3e84 sleep>
   #<Thread:0x401b3f38 run>
   #<Thread:0x401b3fb0 sleep>
   #<Thread:0x401bdf4c run>

Thread.main => thread

Returns the main thread for the process.

   Thread.main   #=> #<Thread:0x401bdf4c run>

Thread.new([arg]*) {|args| block } => thread

Creates and runs a new thread to execute the instructions given in block. Any arguments passed to Thread::new are passed into the block.

   x = Thread.new { sleep 0.1; print "x"; print "y"; print "z" }
   a = Thread.new { print "a"; print "b"; sleep 0.2; print "c" }
   x.join # Let the threads finish before
   a.join # main thread exits...

produces:

   abxyzc

Thread.new([arg]*) {|args| block } => thread

Creates and runs a new thread to execute the instructions given in block. Any arguments passed to Thread::new are passed into the block.

   x = Thread.new { sleep 0.1; print "x"; print "y"; print "z" }
   a = Thread.new { print "a"; print "b"; sleep 0.2; print "c" }
   x.join # Let the threads finish before
   a.join # main thread exits...

produces:

   abxyzc

Thread.pass => nil

Invokes the thread scheduler to pass execution to another thread.

   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

produces:

   axbycz

Thread.start([args]*) {|args| block } => thread
Thread.fork([args]*) {|args| block } => thread

Basically the same as Thread::new. However, if class Thread is subclassed, then calling start in that subclass will not invoke the subclass‘s initialize method.

Thread.stop => nil

Stops execution of the current thread, putting it into a ``sleep’’ state, and schedules execution of another thread. Resets the ``critical’’ condition to false.

   a = Thread.new { print "a"; Thread.stop; print "c" }
   Thread.pass
   print "b"
   a.run
   a.join

produces:

   abc

Instance Method Detail

thr[sym] => obj or nil

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 nil.

   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| puts "#{x.inspect}: #{x[:name]}" }

produces:

   #<Thread:0x401b3b3c sleep>: C
   #<Thread:0x401b3bc8 sleep>: B
   #<Thread:0x401b3c68 sleep>: A
   #<Thread:0x401bdf4c run>:

thr[sym] = obj => obj

Attribute Assignment—Sets or creates the value of a thread-local variable, using either a symbol or a string. See also Thread#[].

thr.abort_on_exception => true or false

Returns the status of the thread-local ``abort on exception’’ condition for thr. The default is false. See also Thread::abort_on_exception=.

thr.abort_on_exception= boolean => true or false

When set to true, causes all threads (including the main program) to abort if an exception is raised in thr. The process will effectively exit(0).

thr.alive? => true or false

Returns true if thr is running or sleeping.

   thr = Thread.new { }
   thr.join                #=> #<Thread:0x401b3fb0 dead>
   Thread.current.alive?   #=> true
   thr.alive?              #=> false

thr.exit => thr
thr.kill => thr
thr.terminate => thr

Terminates thr and schedules another thread to be run, returning the terminated Thread. If this is the main thread, or the last thread, exits the process.

thr.exit! => thr
thr.kill! => thr
thr.terminate! => thr

Terminates thr without calling ensure clauses and schedules another thread to be run, returning the terminated Thread. If this is the main thread, or the last thread, exits the process.

See Thread#exit for the safer version.

thr.group => thgrp or nil

Returns the ThreadGroup which contains thr, or nil if the thread is not a member of any group.

   Thread.main.group   #=> #<ThreadGroup:0x4029d914>

thr.inspect => string

Dump the name, id, and status of thr to a string.

thr.join => thr
thr.join(limit) => thr

The calling thread will suspend execution and run thr. Does not return until thr exits or until limit seconds have passed. If the time limit expires, nil will be returned, otherwise thr is returned.

Any threads not joined will be killed when the main program exits. If thr had previously raised an exception and the abort_on_exception and $DEBUG flags are not set (so the exception has not yet been processed) it will be processed at this time.

   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.

produces:

   axyz

The following example illustrates the limit parameter.

   y = Thread.new { 4.times { sleep 0.1; puts 'tick... ' }}
   puts "Waiting" until y.join(0.15)

produces:

   tick...
   Waiting
   tick...
   Waitingtick...

   tick...

thr.key?(sym) => true or false

Returns true if the given string (or symbol) exists as a thread-local variable.

   me = Thread.current
   me[:oliver] = "a"
   me.key?(:oliver)    #=> true
   me.key?(:stanley)   #=> false

thr.keys => array

Returns an an array of the names of the thread-local variables (as Symbols).

   thr = Thread.new do
     Thread.current[:cat] = 'meow'
     Thread.current["dog"] = 'woof'
   end
   thr.join   #=> #<Thread:0x401b3f10 dead>
   thr.keys   #=> [:dog, :cat]

thr.exit => thr
thr.kill => thr
thr.terminate => thr

Terminates thr and schedules another thread to be run, returning the terminated Thread. If this is the main thread, or the last thread, exits the process.

thr.exit! => thr
thr.kill! => thr
thr.terminate! => thr

Terminates thr without calling ensure clauses and schedules another thread to be run, returning the terminated Thread. If this is the main thread, or the last thread, exits the process.

See Thread#exit for the safer version.

thr.priority => integer

Returns the priority of thr. Default is inherited from the current thread which creating the new thread, or zero for the initial main thread; higher-priority threads will run before lower-priority threads.

   Thread.current.priority   #=> 0

thr.priority= integer => thr

Sets the priority of thr to integer. Higher-priority threads will run before lower-priority threads.

   count1 = 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   #=> 1
   Thread.critical = 1
   count1    #=> 622504
   count2    #=> 5832

thr.raise(exception)

Raises an exception (see Kernel::raise) from thr. The caller does not have to be thr.

   Thread.abort_on_exception = true
   a = Thread.new { sleep(200) }
   a.raise("Gotcha")

produces:

   prog.rb:3: Gotcha (RuntimeError)
    from prog.rb:2:in `initialize'
    from prog.rb:2:in `new'
    from prog.rb:2

thr.run => thr

Wakes up thr, making it eligible for scheduling. If not in a critical section, then invokes the scheduler.

   a = Thread.new { puts "a"; Thread.stop; puts "c" }
   Thread.pass
   puts "Got here"
   a.run
   a.join

produces:

   a
   Got here
   c

thr.safe_level => integer

Returns the safe level in effect for thr. Setting thread-local safe levels can help when implementing sandboxes which run insecure code.

   thr = Thread.new { $SAFE = 3; sleep }
   Thread.current.safe_level   #=> 0
   thr.safe_level              #=> 3

thr.status => string, false or nil

Returns the status of thr: ``sleep’’ if thr is sleeping or waiting on I/O, ``run’’ if thr is executing, ``aborting’’ if thr is aborting, false if thr terminated normally, and nil if thr terminated with an exception.

   a = Thread.new { raise("die now") }
   b = Thread.new { Thread.stop }
   c = Thread.new { Thread.exit }
   d = Thread.new { sleep }
   Thread.critical = true
   d.kill                  #=> #<Thread:0x401b3678 aborting>
   a.status                #=> nil
   b.status                #=> "sleep"
   c.status                #=> false
   d.status                #=> "aborting"
   Thread.current.status   #=> "run"

thr.stop? => true or false

Returns true if thr is dead or sleeping.

   a = Thread.new { Thread.stop }
   b = Thread.current
   a.stop?   #=> true
   b.stop?   #=> false

thr.exit => thr
thr.kill => thr
thr.terminate => thr

Terminates thr and schedules another thread to be run, returning the terminated Thread. If this is the main thread, or the last thread, exits the process.

thr.exit! => thr
thr.kill! => thr
thr.terminate! => thr

Terminates thr without calling ensure clauses and schedules another thread to be run, returning the terminated Thread. If this is the main thread, or the last thread, exits the process.

See Thread#exit for the safer version.

thr.value => obj

Waits for thr to complete (via Thread#join) and returns its value.

   a = Thread.new { 2 + 2 }
   a.value   #=> 4

thr.wakeup => thr

Marks thr as eligible for scheduling (it may still remain blocked on I/O, however). Does not invoke the scheduler (see Thread#run).

   c = Thread.new { Thread.stop; puts "hey!" }
   c.wakeup

produces:

   hey!