Class: Thread

Inherits:
Object show all
Defined in:
eval.c

Overview

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

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#new([arg]) {|args| ... } ⇒ Object

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

Yields:

  • (args) 


12376
12377
12378
 
# File 'eval.c', line 12376

static VALUE
rb_thread_initialize(thread, args)
VALUE thread, args;

Class Method Details

.abort_on_exception ⇒ Boolean

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

Returns:

  • (Boolean) 


11908
11909
11910
11911
11912
 
# File 'eval.c', line 11908

static VALUE
rb_thread_s_abort_exc()
{
    return ruby_thread_abort?Qtrue:Qfalse;
}

.abort_on_exception=(boolean) ⇒ Boolean

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

Returns:

  • (Boolean) 


11939
11940
11941
 
# File 'eval.c', line 11939

static VALUE
rb_thread_s_abort_exc_set(self, val)
VALUE self, val;

.critical ⇒ Boolean

Returns the status of the global “thread critical” condition.

Returns:

  • (Boolean) 


12582
12583
12584
12585
12586
 
# File 'eval.c', line 12582

static VALUE
rb_thread_critical_get()
{
    return rb_thread_critical?Qtrue:Qfalse;
}

.critical=(boolean) ⇒ Boolean

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.

Returns:

  • (Boolean) 


12603
12604
12605
 
# File 'eval.c', line 12603

static VALUE
rb_thread_critical_set(obj, val)
VALUE obj, val;

.current ⇒ Object

Returns the currently executing thread.

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



11461
11462
11463
11464
11465
 
# File 'eval.c', line 11461

VALUE
rb_thread_current()
{
    return curr_thread->thread;
}

.exit ⇒ Object

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.



11690
11691
11692
11693
11694
 
# File 'eval.c', line 11690

static VALUE
rb_thread_exit()
{
    return rb_thread_kill(curr_thread->thread);
}

.start([args]) {|args| ... } ⇒ Object .fork([args]) {|args| ... } ⇒ Object

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.

Overloads:

  • .start([args]) {|args| ... } ⇒ Object

    Yields:

    • (args)
  • .fork([args]) {|args| ... } ⇒ Object

    Yields:

    • (args) 


12408
12409
12410
 
# File 'eval.c', line 12408

static VALUE
rb_thread_start(klass, args)
VALUE klass, args;

.kill(thread) ⇒ Object

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



11672
11673
11674
 
# File 'eval.c', line 11672

static VALUE
rb_thread_s_kill(obj, th)
VALUE obj, th;

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

Returns:



11504
11505
11506
11507
11508
11509
11510
11511
11512
11513
11514
11515
11516
11517
11518
11519
11520
11521
11522
11523
 
# File 'eval.c', line 11504

VALUE
rb_thread_list()
{
    rb_thread_t th;
    VALUE ary = rb_ary_new();

    FOREACH_THREAD(th) {
  switch (th->status) {
    case THREAD_RUNNABLE:
    case THREAD_STOPPED:
    case THREAD_TO_KILL:
      rb_ary_push(ary, th->thread);
    default:
      break;
  }
    }
    END_FOREACH(th);

    return ary;
}

.main ⇒ Object

Returns the main thread for the process.

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



11477
11478
11479
11480
11481
 
# File 'eval.c', line 11477

VALUE
rb_thread_main()
{
    return main_thread->thread;
}

.new([arg]) {|args| ... } ⇒ Object

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

Yields:

  • (args) 


12338
12339
12340
 
# File 'eval.c', line 12338

static VALUE
rb_thread_s_new(argc, argv, klass)
int argc;

.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

Returns:

  • (nil) 


11717
11718
11719
11720
11721
11722
 
# File 'eval.c', line 11717

static VALUE
rb_thread_pass()
{
    rb_thread_schedule();
    return Qnil;
}

.start([args]) {|args| ... } ⇒ Object .fork([args]) {|args| ... } ⇒ Object

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.

Overloads:

  • .start([args]) {|args| ... } ⇒ Object

    Yields:

    • (args)
  • .fork([args]) {|args| ... } ⇒ Object

    Yields:

    • (args) 


12408
12409
12410
 
# File 'eval.c', line 12408

static VALUE
rb_thread_start(klass, args)
VALUE klass, args;

.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

Returns:

  • (nil) 


11744
11745
11746
11747
11748
11749
11750
11751
11752
11753
11754
11755
11756
11757
11758
11759
11760
 
# File 'eval.c', line 11744

VALUE
rb_thread_stop()
{
    enum rb_thread_status last_status = THREAD_RUNNABLE;

    rb_thread_critical = 0;
    if (curr_thread == curr_thread->next) {
  rb_raise(rb_eThreadError, "stopping only thread\n\tnote: use sleep to stop forever");
    }
    if (curr_thread->status == THREAD_TO_KILL)
  last_status = THREAD_TO_KILL;
    curr_thread->status = THREAD_STOPPED;
    rb_thread_schedule();
    curr_thread->status = last_status;

    return Qnil;
}

Instance Method Details

#[](sym) ⇒ Object?

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>:

Returns:



12804
12805
12806
 
# File 'eval.c', line 12804

static VALUE
rb_thread_aref(thread, id)
VALUE thread, id;

#[]=(sym) ⇒ Object

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

Returns:



12845
12846
12847
 
# File 'eval.c', line 12845

static VALUE
rb_thread_aset(thread, id, val)
VALUE thread, id, val;

#abort_on_exception ⇒ Boolean

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

Returns:

  • (Boolean) 


11958
11959
11960
 
# File 'eval.c', line 11958

static VALUE
rb_thread_abort_exc(thread)
VALUE thread;

#abort_on_exception=(boolean) ⇒ Boolean

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

Returns:

  • (Boolean) 


11975
11976
11977
 
# File 'eval.c', line 11975

static VALUE
rb_thread_abort_exc_set(thread, val)
VALUE thread, val;

#alive? ⇒ Boolean

Returns true if thr is running or sleeping.

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

Returns:

  • (Boolean) 


12493
12494
12495
 
# File 'eval.c', line 12493

VALUE
rb_thread_alive_p(thread)
VALUE thread;

#exit ⇒ Object #kill ⇒ Object #terminate ⇒ Object

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.



11625
11626
11627
 
# File 'eval.c', line 11625

VALUE
rb_thread_kill(thread)
VALUE thread;

#exit! ⇒ Object #kill! ⇒ Object #terminate! ⇒ Object

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.



11649
11650
11651
 
# File 'eval.c', line 11649

static VALUE
rb_thread_kill_bang(thread)
VALUE thread;

#group ⇒ nil

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

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

Returns:

  • (nil) 


11995
11996
11997
 
# File 'eval.c', line 11995

VALUE
rb_thread_group(thread)
VALUE thread;

#inspect ⇒ String

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

Returns:



12922
12923
12924
 
# File 'eval.c', line 12922

static VALUE
rb_thread_inspect(thread)
VALUE thread;

#join ⇒ Object #join(limit) ⇒ Object

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



11434
11435
11436
 
# File 'eval.c', line 11434

static VALUE
rb_thread_join_m(argc, argv, thread)
int argc;

#key?(sym) ⇒ Boolean

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

Returns:

  • (Boolean) 


12866
12867
12868
 
# File 'eval.c', line 12866

static VALUE
rb_thread_key_p(thread, id)
VALUE thread, id;

#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]

Returns:



12902
12903
12904
 
# File 'eval.c', line 12902

static VALUE
rb_thread_keys(thread)
VALUE thread;

#exit ⇒ Object #kill ⇒ Object #terminate ⇒ Object

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.



11625
11626
11627
 
# File 'eval.c', line 11625

VALUE
rb_thread_kill(thread)
VALUE thread;

#exit! ⇒ Object #kill! ⇒ Object #terminate! ⇒ Object

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.



11649
11650
11651
 
# File 'eval.c', line 11649

static VALUE
rb_thread_kill_bang(thread)
VALUE thread;

#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

Returns:



11821
11822
11823
 
# File 'eval.c', line 11821

static VALUE
rb_thread_priority(thread)
VALUE thread;

#priority=(integer) ⇒ Object

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



11852
11853
11854
 
# File 'eval.c', line 11852

static VALUE
rb_thread_priority_set(thread, prio)
VALUE thread, prio;

#raise(exception) ⇒ Object

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



12748
12749
12750
 
# File 'eval.c', line 12748

static VALUE
rb_thread_raise_m(argc, argv, thread)
int argc;

#run ⇒ Object

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



11584
11585
11586
 
# File 'eval.c', line 11584

VALUE
rb_thread_run(thread)
VALUE thread;

#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

Returns:



11879
11880
11881
 
# File 'eval.c', line 11879

static VALUE
rb_thread_safe_level(thread)
VALUE thread;

#status ⇒ String, ...

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"

Returns:



12465
12466
12467
 
# File 'eval.c', line 12465

static VALUE
rb_thread_status(thread)
VALUE thread;

#stop? ⇒ Boolean

Returns true if thr is dead or sleeping.

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

Returns:

  • (Boolean) 


12516
12517
12518
 
# File 'eval.c', line 12516

static VALUE
rb_thread_stop_p(thread)
VALUE thread;

#exit ⇒ Object #kill ⇒ Object #terminate ⇒ Object

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.



11625
11626
11627
 
# File 'eval.c', line 11625

VALUE
rb_thread_kill(thread)
VALUE thread;

#exit! ⇒ Object #kill! ⇒ Object #terminate! ⇒ Object

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.



11649
11650
11651
 
# File 'eval.c', line 11649

static VALUE
rb_thread_kill_bang(thread)
VALUE thread;

#value ⇒ Object

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

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

Returns:



12430
12431
12432
 
# File 'eval.c', line 12430

static VALUE
rb_thread_value(thread)
VALUE thread;

#wakeup ⇒ Object

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!



11541
11542
11543
 
# File 'eval.c', line 11541

VALUE
rb_thread_wakeup(thread)
VALUE thread;