Class: Thread

Inherits:
Object show all
Defined in:
vm.c,
vm.c

Overview

Threads are the Ruby implementation for a concurrent programming model.

Programs that require multiple threads of execution are a perfect candidate for Ruby’s Thread class.

For example, we can create a new thread separate from the main thread’s execution using ::new.

thr = Thread.new { puts "Whats the big deal" }

Then we are able to pause the execution of the main thread and allow our new thread to finish, using #join:

thr.join #=> "Whats the big deal"

If we don’t call thr.join before the main thread terminates, then all other threads including thr will be killed.

Alternatively, you can use an array for handling multiple threads at once, like in the following example:

threads = []
threads << Thread.new { puts "Whats the big deal" }
threads << Thread.new { 3.times { puts "Threads are fun!" } }

After creating a few threads we wait for them all to finish consecutively.

threads.each { |thr| thr.join }

Thread initialization

In order to create new threads, Ruby provides ::new, ::start, and ::fork. A block must be provided with each of these methods, otherwise a ThreadError will be raised.

When subclassing the Thread class, the initialize method of your subclass will be ignored by ::start and ::fork. Otherwise, be sure to call super in your initialize method.

=== Thread termination

For terminating threads, Ruby provides a variety of ways to do this.

The class method ::kill, is meant to exit a given thread:

thr = Thread.new { ... }
Thread.kill(thr) # sends exit() to thr

Alternatively, you can use the instance method #exit, or any of its aliases #kill or #terminate.

thr.exit

=== Thread status

Ruby provides a few instance methods for querying the state of a given thread. To get a string with the current thread’s state use #status

thr = Thread.new { sleep }
thr.status # => "sleep"
thr.exit
thr.status # => false

You can also use #alive? to tell if the thread is running or sleeping, and #stop? if the thread is dead or sleeping.

=== Thread variables and scope

Since threads are created with blocks, the same rules apply to other Ruby blocks for variable scope. Any local variables created within this block are accessible to only this thread.

==== Fiber-local vs. Thread-local

Each fiber has its own bucket for Thread#[] storage. When you set a new fiber-local it is only accessible within this Fiber. To illustrate:

Thread.new {
  Thread.current[:foo] = "bar"
  Fiber.new {
    p Thread.current[:foo] # => nil
  }.resume
}.join

This example uses #[] for getting and #[]= for setting fiber-locals, you can also use #keys to list the fiber-locals for a given thread and #key? to check if a fiber-local exists.

When it comes to thread-locals, they are accessible within the entire scope of the thread. Given the following example:

Thread.new{
  Thread.current.thread_variable_set(:foo, 1)
  p Thread.current.thread_variable_get(:foo) # => 1
  Fiber.new{

Thread.current.thread_variable_set(:foo, 2) p Thread.current.thread_variable_get(:foo) # => 2

     }.resume
     p Thread.current.thread_variable_get(:foo)   # => 2
   }.join

You can see that the thread-local +:foo+ carried over into the fiber
and was changed to +2+ by the end of the thread.

This example makes use of #thread_variable_set to create new
thread-locals, and #thread_variable_get to reference them.

There is also #thread_variables to list all thread-locals, and
#thread_variable? to check if a given thread-local exists.

=== Exception handling

Any thread can raise an exception using the #raise instance method, which operates similarly to Kernel#raise.

However, it’s important to note that an exception that occurs in any thread except the main thread depends on #abort_on_exception. This option is false by default, meaning that any unhandled exception will cause the thread to terminate silently when waited on by either #join or #value. You can change this default by either #abort_on_exception= true or setting $DEBUG to true.

With the addition of the class method ::handle_interrupt, you can now handle exceptions asynchronously with threads.

=== Scheduling

Ruby provides a few ways to support scheduling threads in your program.

The first way is by using the class method ::stop, to put the current running thread to sleep and schedule the execution of another thread.

Once a thread is asleep, you can use the instance method #wakeup to mark your thread as eligible for scheduling.

You can also try ::pass, which attempts to pass execution to another thread but is dependent on the OS whether a running thread will switch or not. The same goes for #priority, which lets you hint to the thread scheduler which threads you want to take precedence when passing execution. This method is also dependent on the OS and may be ignored on some platforms.

Defined Under Namespace

Classes: Backtrace

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Object

:nodoc:



719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
 
# File 'thread.c', line 719

static VALUE
thread_initialize(VALUE thread, VALUE args)
{
    rb_thread_t *th;
    if (!rb_block_given_p()) {
	rb_raise(rb_eThreadError, "must be called with a block");
    }
    GetThreadPtr(thread, th);
    if (th->first_args) {
	VALUE proc = th->first_proc, line, loc;
	const char *file;
        if (!proc || !RTEST(loc = rb_proc_location(proc))) {
            rb_raise(rb_eThreadError, "already initialized thread");
        }
	file = RSTRING_PTR(RARRAY_AREF(loc, 0));
	if (NIL_P(line = RARRAY_AREF(loc, 1))) {
	    rb_raise(rb_eThreadError, "already initialized thread - %s",
		     file);
	}
        rb_raise(rb_eThreadError, "already initialized thread - %s:%d",
                 file, NUM2INT(line));
    }
    return thread_create_core(thread, args, 0);
}

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, all threads will abort (the process will exit(0)) if an exception is raised in any thread.

Can also be specified by the global $DEBUG flag or command line option -d.

See also ::abort_on_exception=.

There is also an instance level method to set this for a specific thread, see #abort_on_exception.

Returns:

  • (Boolean) 


2465
2466
2467
2468
2469
 
# File 'thread.c', line 2465

static VALUE
rb_thread_s_abort_exc(void)
{
    return GET_THREAD()->vm->thread_abort_on_exception ? 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"

This will produce:

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

See also ::abort_on_exception.

There is also an instance level method to set this for a specific thread, see #abort_on_exception=.

Returns:

  • (Boolean) 


2501
2502
2503
2504
2505
2506
 
# File 'thread.c', line 2501

static VALUE
rb_thread_s_abort_exc_set(VALUE self, VALUE val)
{
    GET_THREAD()->vm->thread_abort_on_exception = RTEST(val);
    return val;
}

.current ⇒ Object

Returns the currently executing thread.

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



2419
2420
2421
2422
2423
 
# File 'thread.c', line 2419

static VALUE
thread_s_current(VALUE klass)
{
    return rb_thread_current();
}

.DEBUG ⇒ Numeric

Returns the thread debug level. Available only if compiled with THREAD_DEBUG=-1.

Returns:



186
187
188
189
190
 
# File 'thread.c', line 186

static VALUE
rb_thread_s_debug(void)
{
    return INT2NUM(rb_thread_debug_enabled);
}

.DEBUG=(num) ⇒ Object

Sets the thread debug level. Available only if compiled with THREAD_DEBUG=-1.



200
201
202
203
204
205
 
# File 'thread.c', line 200

static VALUE
rb_thread_s_debug_set(VALUE self, VALUE val)
{
    rb_thread_debug_enabled = RTEST(val) ? NUM2INT(val) : 0;
    return val;
}

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



2251
2252
2253
2254
2255
2256
 
# File 'thread.c', line 2251

static VALUE
rb_thread_exit(void)
{
    rb_thread_t *th = GET_THREAD();
    return rb_thread_kill(th->self);
}

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

Basically the same as ::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) 


712
713
714
715
716
 
# File 'thread.c', line 712

static VALUE
thread_start(VALUE klass, VALUE args)
{
    return thread_create_core(rb_thread_alloc(klass), args, 0);
}

.handle_interrupt(hash) { ... } ⇒ Object

Changes asynchronous interrupt timing.

interrupt means asynchronous event and corresponding procedure by Thread#raise, Thread#kill, signal trap (not supported yet) and main thread termination (if main thread terminates, then all other thread will be killed).

The given hash has pairs like ExceptionClass => :TimingSymbol. Where the ExceptionClass is the interrupt handled by the given block. The TimingSymbol can be one of the following symbols:

:immediate

Invoke interrupts immediately.

:on_blocking

Invoke interrupts while BlockingOperation.

:never

Never invoke all interrupts.

BlockingOperation means that the operation will block the calling thread, such as read and write. On CRuby implementation, BlockingOperation is any operation executed without GVL.

Masked asynchronous interrupts are delayed until they are enabled. This method is similar to sigprocmask(3).

NOTE

Asynchronous interrupts are difficult to use.

If you need to communicate between threads, please consider to use another way such as Queue.

Or use them with deep understanding about this method.

Usage

In this example, we can guard from Thread#raise exceptions.

Using the :never TimingSymbol the RuntimeError exception will always be ignored in the first block of the main thread. In the second ::handle_interrupt block we can purposefully handle RuntimeError exceptions.

th = Thread.new do
  Thread.handle_interrupt(RuntimeError => :never) {
    begin
      # You can write resource allocation code safely.
      Thread.handle_interrupt(RuntimeError => :immediate) {
   # ...
      }
    ensure
      # You can write resource deallocation code safely.
    end
  }
end
Thread.pass
# ...
th.raise "stop"

While we are ignoring the RuntimeError exception, it’s safe to write our resource allocation code. Then, the ensure block is where we can safely deallocate your resources.

Guarding from TimeoutError

In the next example, we will guard from the TimeoutError exception. This will help prevent from leaking resources when TimeoutError exceptions occur during normal ensure clause. For this example we use the help of the standard library Timeout, from lib/timeout.rb

require 'timeout'
Thread.handle_interrupt(TimeoutError => :never) {
  timeout(10){
    # TimeoutError doesn't occur here
    Thread.handle_interrupt(TimeoutError => :on_blocking) {
      # possible to be killed by TimeoutError
      # while blocking operation
    }
    # TimeoutError doesn't occur here
  }
}

In the first part of the timeout block, we can rely on TimeoutError being ignored. Then in the TimeoutError => :on_blocking block, any operation that will block the calling thread is susceptible to a TimeoutError exception being raised.

Stack control settings

It’s possible to stack multiple levels of ::handle_interrupt blocks in order to control more than one ExceptionClass and TimingSymbol at a time.

Thread.handle_interrupt(FooError => :never) {
  Thread.handle_interrupt(BarError => :never) {
     # FooError and BarError are prohibited.
  }
}

Inheritance with ExceptionClass

All exceptions inherited from the ExceptionClass parameter will be considered.

Thread.handle_interrupt(Exception => :never) {
  # all exceptions inherited from Exception are prohibited.
}

Yields:



1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
 
# File 'thread.c', line 1791

static VALUE
rb_thread_s_handle_interrupt(VALUE self, VALUE mask_arg)
{
    VALUE mask;
    rb_thread_t *th = GET_THREAD();
    VALUE r = Qnil;
    int state;

    if (!rb_block_given_p()) {
	rb_raise(rb_eArgError, "block is needed.");
    }

    mask = rb_convert_type(mask_arg, T_HASH, "Hash", "to_hash");
    rb_hash_foreach(mask, handle_interrupt_arg_check_i, 0);
    rb_ary_push(th->pending_interrupt_mask_stack, mask);
    if (!rb_threadptr_pending_interrupt_empty_p(th)) {
	th->pending_interrupt_queue_checked = 0;
	RUBY_VM_SET_INTERRUPT(th);
    }

    TH_PUSH_TAG(th);
    if ((state = EXEC_TAG()) == 0) {
	r = rb_yield(Qnil);
    }
    TH_POP_TAG();

    rb_ary_pop(th->pending_interrupt_mask_stack);
    if (!rb_threadptr_pending_interrupt_empty_p(th)) {
	th->pending_interrupt_queue_checked = 0;
	RUBY_VM_SET_INTERRUPT(th);
    }

    RUBY_VM_CHECK_INTS(th);

    if (state) {
	JUMP_TAG(state);
    }

    return r;
}

.kill(thread) ⇒ Object

Causes the given thread to exit, see also 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



2232
2233
2234
2235
2236
 
# File 'thread.c', line 2232

static VALUE
rb_thread_s_kill(VALUE obj, VALUE th)
{
    return rb_thread_kill(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}

This will produce:

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

Returns:



2396
2397
2398
2399
2400
2401
2402
 
# File 'thread.c', line 2396

VALUE
rb_thread_list(void)
{
    VALUE ary = rb_ary_new();
    st_foreach(GET_THREAD()->vm->living_threads, thread_list_i, ary);
    return ary;
}

.main ⇒ Object

Returns the main thread.



2438
2439
2440
2441
2442
 
# File 'thread.c', line 2438

static VALUE
rb_thread_s_main(VALUE klass)
{
    return rb_thread_main();
}

.new ⇒ Object

Thread.new(*args, &proc) -> thread

Thread.new(*args) { |args| ... }	-> thread

Creates a new thread executing the given block.

Any +args+ given to ::new will be passed to the block:

arr = [] a, b, c = 1, 2, 3 Thread.new(a,b,c) { |d,e,f| arr << d << e << f }.join arr #=> [1, 2, 3]

A ThreadError exception is raised if ::new is called without a block.

If you're going to subclass Thread, be sure to call super in your
+initialize+ method, otherwise a ThreadError will be raised.



684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
 
# File 'thread.c', line 684

static VALUE
thread_s_new(int argc, VALUE *argv, VALUE klass)
{
    rb_thread_t *th;
    VALUE thread = rb_thread_alloc(klass);

    if (GET_VM()->main_thread->status == THREAD_KILLED)
	rb_raise(rb_eThreadError, "can't alloc thread");

    rb_obj_call_init(thread, argc, argv);
    GetThreadPtr(thread, th);
    if (!th->first_args) {
	rb_raise(rb_eThreadError, "uninitialized thread - check `%s#initialize'",
		 rb_class2name(klass));
    }
    return thread;
}

.pass ⇒ nil

Give the thread scheduler a hint to pass execution to another thread. A running thread may or may not switch, it depends on OS and processor.

Returns:

  • (nil) 


1516
1517
1518
1519
1520
1521
 
# File 'thread.c', line 1516

static VALUE
thread_s_pass(VALUE klass)
{
    rb_thread_schedule();
    return Qnil;
}

.pending_interrupt?(error = nil) ⇒ Boolean

Returns whether or not the asynchronous queue is empty.

Since Thread::handle_interrupt can be used to defer asynchronous events, this method can be used to determine if there are any deferred events.

If you find this method returns true, then you may finish :never blocks.

For example, the following method processes deferred asynchronous events immediately.

def Thread.kick_interrupt_immediately
  Thread.handle_interrupt(Object => :immediate) {
    Thread.pass
  }
end

If error is given, then check only for error type deferred events.

Usage

th = Thread.new{
  Thread.handle_interrupt(RuntimeError => :on_blocking){
    while true
      ...
      # reach safe point to invoke interrupt
      if Thread.pending_interrupt?
        Thread.handle_interrupt(Object => :immediate){}
      end
      ...
    end
  }
}
...
th.raise # stop thread

This example can also be written as the following, which you should use to avoid asynchronous interrupts.

flag = true
th = Thread.new{
  Thread.handle_interrupt(RuntimeError => :on_blocking){
    while true
      ...
      # reach safe point to invoke interrupt
      break if flag == false
      ...
    end
  }
}
...
flag = false # stop thread

Returns:

  • (Boolean) 


1927
1928
1929
1930
1931
 
# File 'thread.c', line 1927

static VALUE
rb_thread_s_pending_interrupt_p(int argc, VALUE *argv, VALUE self)
{
    return rb_thread_pending_interrupt_p(argc, argv, GET_THREAD()->self);
}

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

Basically the same as ::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) 


712
713
714
715
716
 
# File 'thread.c', line 712

static VALUE
thread_start(VALUE klass, VALUE args)
{
    return thread_create_core(rb_thread_alloc(klass), args, 0);
}

.stop ⇒ nil

Stops execution of the current thread, putting it into a “sleep” state, and schedules execution of another thread.

a = Thread.new { print "a"; Thread.stop; print "c" }
sleep 0.1 while a.status!='sleep'
print "b"
a.run
a.join
#=> "abc"

Returns:

  • (nil) 


2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
 
# File 'thread.c', line 2345

VALUE
rb_thread_stop(void)
{
    if (rb_thread_alone()) {
	rb_raise(rb_eThreadError,
		 "stopping only thread\n\tnote: use sleep to stop forever");
    }
    rb_thread_sleep_deadly();
    return Qnil;
}

Instance Method Details

#[](sym) ⇒ Object?

Attribute Reference—Returns the value of a fiber-local variable (current thread’s root fiber if not explicitly inside a Fiber), using either a symbol or a string name. If the specified variable does not exist, returns nil.

[
  Thread.new { Thread.current["name"] = "A" },
  Thread.new { Thread.current[:name]  = "B" },
  Thread.new { Thread.current["name"] = "C" }
].each do |th|
  th.join
  puts "#{th.inspect}: #{th[:name]}"
end

This will produce:

#<Thread:0x00000002a54220 dead>: A
#<Thread:0x00000002a541a8 dead>: B
#<Thread:0x00000002a54130 dead>: C

Thread#[] and Thread#[]= are not thread-local but fiber-local. This confusion did not exist in Ruby 1.8 because fibers are only available since Ruby 1.9. Ruby 1.9 chooses that the methods behaves fiber-local to save following idiom for dynamic scope.

def meth(newvalue)
  begin
    oldvalue = Thread.current[:name]
    Thread.current[:name] = newvalue
    yield
  ensure
    Thread.current[:name] = oldvalue
  end
end

The idiom may not work as dynamic scope if the methods are thread-local and a given block switches fiber.

f = Fiber.new {
  meth(1) {
    Fiber.yield
  }
}
meth(2) {
  f.resume
}
f.resume
p Thread.current[:name]
#=> nil if fiber-local
#=> 2 if thread-local (The value 2 is leaked to outside of meth method.)

For thread-local variables, please see #thread_variable_get and #thread_variable_set.

Returns:



2832
2833
2834
2835
2836
2837
2838
 
# File 'thread.c', line 2832

static VALUE
rb_thread_aref(VALUE thread, VALUE key)
{
    ID id = rb_check_id(&key);
    if (!id) return Qnil;
    return rb_thread_local_aref(thread, id);
}

#[]=(sym) ⇒ Object

Attribute Assignment—Sets or creates the value of a fiber-local variable, using either a symbol or a string.

See also Thread#[].

For thread-local variables, please see #thread_variable_set and #thread_variable_get.

Returns:



2883
2884
2885
2886
2887
 
# File 'thread.c', line 2883

static VALUE
rb_thread_aset(VALUE self, VALUE id, VALUE val)
{
    return rb_thread_local_aset(self, rb_to_id(id), val);
}

#abort_on_exception ⇒ Boolean

Returns the status of the thread-local “abort on exception” condition for this thr.

The default is false.

See also #abort_on_exception=.

There is also a class level method to set this for all threads, see ::abort_on_exception.

Returns:

  • (Boolean) 


2524
2525
2526
2527
2528
2529
2530
 
# File 'thread.c', line 2524

static VALUE
rb_thread_abort_exc(VALUE thread)
{
    rb_thread_t *th;
    GetThreadPtr(thread, th);
    return th->abort_on_exception ? Qtrue : Qfalse;
}

#abort_on_exception=(boolean) ⇒ Boolean

When set to true, all threads (including the main program) will abort if an exception is raised in this thr.

The process will effectively exit(0).

See also #abort_on_exception.

There is also a class level method to set this for all threads, see ::abort_on_exception=.

Returns:

  • (Boolean) 


2548
2549
2550
2551
2552
2553
2554
2555
2556
 
# File 'thread.c', line 2548

static VALUE
rb_thread_abort_exc_set(VALUE thread, VALUE val)
{
    rb_thread_t *th;

    GetThreadPtr(thread, th);
    th->abort_on_exception = RTEST(val);
    return val;
}

#add_trace_func(proc) ⇒ Proc

Adds proc as a handler for tracing.

See Thread#set_trace_func and Kernel#set_trace_func.

Returns:



527
528
529
530
531
532
533
534
535
 
# File 'vm_trace.c', line 527

static VALUE
thread_add_trace_func_m(VALUE obj, VALUE trace)
{
    rb_thread_t *th;

    GetThreadPtr(obj, th);
    thread_add_trace_func(th, trace);
    return trace;
}

#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

See also #stop? and #status.

Returns:

  • (Boolean)

Returns:

  • (Boolean) 


2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
 
# File 'thread.c', line 2671

static VALUE
rb_thread_alive_p(VALUE thread)
{
    rb_thread_t *th;
    GetThreadPtr(thread, th);

    if (rb_threadptr_dead(th))
	return Qfalse;
    return Qtrue;
}

#backtrace ⇒ Array

Returns the current backtrace of the target thread.

Returns:



5040
5041
5042
5043
5044
 
# File 'thread.c', line 5040

static VALUE
rb_thread_backtrace_m(int argc, VALUE *argv, VALUE thval)
{
    return rb_vm_thread_backtrace(argc, argv, thval);
}

#backtrace_locations(*args) ⇒ Object

Returns the execution stack for the target thread—an array containing backtrace location objects.

See Thread::Backtrace::Location for more information.

This method behaves similarly to Kernel#caller_locations except it applies to a specific thread.



5057
5058
5059
5060
5061
 
# File 'thread.c', line 5057

static VALUE
rb_thread_backtrace_locations_m(int argc, VALUE *argv, VALUE thval)
{
    return rb_vm_thread_backtrace_locations(argc, argv, thval);
}

#exit ⇒ nil #kill ⇒ nil #terminate ⇒ nil

Terminates thr 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, exits the process.

Overloads:

  • #exit ⇒ nil

    Returns:

    • (nil)
  • #kill ⇒ nil

    Returns:

    • (nil)
  • #terminate ⇒ nil

    Returns:

    • (nil) 


2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
 
# File 'thread.c', line 2190

VALUE
rb_thread_kill(VALUE thread)
{
    rb_thread_t *th;

    GetThreadPtr(thread, th);

    if (th->to_kill || th->status == THREAD_KILLED) {
	return thread;
    }
    if (th == th->vm->main_thread) {
	rb_exit(EXIT_SUCCESS);
    }

    thread_debug("rb_thread_kill: %p (%p)\n", (void *)th, (void *)th->thread_id);

    if (th == GET_THREAD()) {
	/* kill myself immediately */
	rb_threadptr_to_kill(th);
    }
    else {
	rb_threadptr_pending_interrupt_enque(th, eKillSignal);
	rb_threadptr_interrupt(th);
    }
    return thread;
}

#group ⇒ nil

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

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

Returns:

  • (nil) 


2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
 
# File 'thread.c', line 2569

VALUE
rb_thread_group(VALUE thread)
{
    rb_thread_t *th;
    VALUE group;
    GetThreadPtr(thread, th);
    group = th->thgroup;

    if (!group) {
	group = Qnil;
    }
    return group;
}

#inspect ⇒ String

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

Returns:



2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
 
# File 'thread.c', line 2737

static VALUE
rb_thread_inspect(VALUE thread)
{
    const char *cname = rb_obj_classname(thread);
    rb_thread_t *th;
    const char *status;
    VALUE str;

    GetThreadPtr(thread, th);
    status = thread_status_name(th);
    str = rb_sprintf("#<%s:%p %s>", cname, (void *)thread, status);
    OBJ_INFECT(str, thread);

    return str;
}

#join ⇒ Object #join(limit) ⇒ Object

The calling thread will suspend execution and run this thr.

Does not return until thr exits or until the given 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 or $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 thread x finish, thread a will be killed on exit.
#=> "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)

This will produce:

tick...
Waiting
tick...
Waiting
tick...
tick...



898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
 
# File 'thread.c', line 898

static VALUE
thread_join_m(int argc, VALUE *argv, VALUE self)
{
    rb_thread_t *target_th;
    double delay = DELAY_INFTY;
    VALUE limit;

    GetThreadPtr(self, target_th);

    rb_scan_args(argc, argv, "01", &limit);
    if (!NIL_P(limit)) {
	delay = rb_num2dbl(limit);
    }

    return thread_join(target_th, delay);
}

#key?(sym) ⇒ Boolean

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

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

Returns:

  • (Boolean)

Returns:

  • (Boolean) 


2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
 
# File 'thread.c', line 2963

static VALUE
rb_thread_key_p(VALUE self, VALUE key)
{
    rb_thread_t *th;
    ID id = rb_check_id(&key);

    GetThreadPtr(self, th);

    if (!id || !th->local_storage) {
	return Qfalse;
    }
    if (st_lookup(th->local_storage, id, 0)) {
	return Qtrue;
    }
    return Qfalse;
}

#keys ⇒ Array

Returns an array of the names of the fiber-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:



3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
 
# File 'thread.c', line 3018

static VALUE
rb_thread_keys(VALUE self)
{
    rb_thread_t *th;
    VALUE ary = rb_ary_new();
    GetThreadPtr(self, th);

    if (th->local_storage) {
	st_foreach(th->local_storage, thread_keys_i, ary);
    }
    return ary;
}

#exit ⇒ nil #kill ⇒ nil #terminate ⇒ nil

Terminates thr 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, exits the process.

Overloads:

  • #exit ⇒ nil

    Returns:

    • (nil)
  • #kill ⇒ nil

    Returns:

    • (nil)
  • #terminate ⇒ nil

    Returns:

    • (nil) 


2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
 
# File 'thread.c', line 2190

VALUE
rb_thread_kill(VALUE thread)
{
    rb_thread_t *th;

    GetThreadPtr(thread, th);

    if (th->to_kill || th->status == THREAD_KILLED) {
	return thread;
    }
    if (th == th->vm->main_thread) {
	rb_exit(EXIT_SUCCESS);
    }

    thread_debug("rb_thread_kill: %p (%p)\n", (void *)th, (void *)th->thread_id);

    if (th == GET_THREAD()) {
	/* kill myself immediately */
	rb_threadptr_to_kill(th);
    }
    else {
	rb_threadptr_pending_interrupt_enque(th, eKillSignal);
	rb_threadptr_interrupt(th);
    }
    return thread;
}

#pending_interrupt?(error = nil) ⇒ Boolean

Returns whether or not the asynchronous queue is empty for the target thread.

If error is given, then check only for error type deferred events.

See ::pending_interrupt? for more information.

Returns:

  • (Boolean) 


1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
 
# File 'thread.c', line 1842

static VALUE
rb_thread_pending_interrupt_p(int argc, VALUE *argv, VALUE target_thread)
{
    rb_thread_t *target_th;

    GetThreadPtr(target_thread, target_th);

    if (rb_threadptr_pending_interrupt_empty_p(target_th)) {
	return Qfalse;
    }
    else {
	if (argc == 1) {
	    VALUE err;
	    rb_scan_args(argc, argv, "01", &err);
	    if (!rb_obj_is_kind_of(err, rb_cModule)) {
		rb_raise(rb_eTypeError, "class or module required for rescue clause");
	    }
	    if (rb_threadptr_pending_interrupt_include_p(target_th, err)) {
		return Qtrue;
	    }
	    else {
		return Qfalse;
	    }
	}
	return Qtrue;
    }
}

#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 thread will run more frequently than lower-priority threads (but lower-priority threads can also run).

This is just hint for Ruby thread scheduler. It may be ignored on some platform.

Thread.current.priority   #=> 0

Returns:



3119
3120
3121
3122
3123
3124
3125
 
# File 'thread.c', line 3119

static VALUE
rb_thread_priority(VALUE thread)
{
    rb_thread_t *th;
    GetThreadPtr(thread, th);
    return INT2NUM(th->priority);
}

#priority=(integer) ⇒ Object

Sets the priority of thr to integer. Higher-priority threads will run more frequently than lower-priority threads (but lower-priority threads can also run).

This is just hint for Ruby thread scheduler. It may be ignored on some platform.

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
count1    #=> 622504
count2    #=> 5832



3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
 
# File 'thread.c', line 3154

static VALUE
rb_thread_priority_set(VALUE thread, VALUE prio)
{
    rb_thread_t *th;
    int priority;
    GetThreadPtr(thread, th);


#if USE_NATIVE_THREAD_PRIORITY
    th->priority = NUM2INT(prio);
    native_thread_apply_priority(th);
#else
    priority = NUM2INT(prio);
    if (priority > RUBY_THREAD_PRIORITY_MAX) {
	priority = RUBY_THREAD_PRIORITY_MAX;
    }
    else if (priority < RUBY_THREAD_PRIORITY_MIN) {
	priority = RUBY_THREAD_PRIORITY_MIN;
    }
    th->priority = priority;
#endif
    return INT2NUM(th->priority);
}

#raise ⇒ Object #raise(string) ⇒ Object #raise(exception[, string [, array]]) ⇒ Object

Raises an exception from the given thread. The caller does not have to be thr. See Kernel#raise for more information.

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

This will produce:

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



2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
 
# File 'thread.c', line 2161

static VALUE
thread_raise_m(int argc, VALUE *argv, VALUE self)
{
    rb_thread_t *target_th;
    rb_thread_t *th = GET_THREAD();
    GetThreadPtr(self, target_th);
    rb_threadptr_raise(target_th, argc, argv);

    /* To perform Thread.current.raise as Kernel.raise */
    if (th == target_th) {
	RUBY_VM_CHECK_INTS(th);
    }
    return Qnil;
}

#run ⇒ Object

Wakes up thr, making it eligible for scheduling.

a = Thread.new { puts "a"; Thread.stop; puts "c" }
sleep 0.1 while a.status!='sleep'
puts "Got here"
a.run
a.join

This will produce:

a
Got here
c

See also the instance method #wakeup.



2321
2322
2323
2324
2325
2326
2327
 
# File 'thread.c', line 2321

VALUE
rb_thread_run(VALUE thread)
{
    rb_thread_wakeup(thread);
    rb_thread_schedule();
    return 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:



2721
2722
2723
2724
2725
2726
2727
2728
 
# File 'thread.c', line 2721

static VALUE
rb_thread_safe_level(VALUE thread)
{
    rb_thread_t *th;
    GetThreadPtr(thread, th);

    return INT2NUM(th->safe_level);
}

#set_trace_func(proc) ⇒ Proc #set_trace_func(nil) ⇒ nil

Establishes proc on thr as the handler for tracing, or disables tracing if the parameter is nil.

See Kernel#set_trace_func.

Overloads:

  • #set_trace_func(proc) ⇒ Proc

    Returns:

  • #set_trace_func(nil) ⇒ nil

    Returns:

    • (nil) 


548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
 
# File 'vm_trace.c', line 548

static VALUE
thread_set_trace_func_m(VALUE obj, VALUE trace)
{
    rb_thread_t *th;

    GetThreadPtr(obj, th);
    rb_threadptr_remove_event_hook(th, call_trace_func, Qundef);

    if (NIL_P(trace)) {
	return Qnil;
    }

    thread_add_trace_func(th, trace);
    return trace;
}

#status ⇒ String, ...

Returns the status of thr.

"sleep"

Returned if this thread is sleeping or waiting on I/O

"run"

When this thread is executing

"aborting"

If this thread is aborting

false

When this thread is terminated normally

nil

If terminated with an exception.

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

See also the instance methods #alive? and #stop?

Returns:



2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
 
# File 'thread.c', line 2640

static VALUE
rb_thread_status(VALUE thread)
{
    rb_thread_t *th;
    GetThreadPtr(thread, th);

    if (rb_threadptr_dead(th)) {
	if (!NIL_P(th->errinfo) && !FIXNUM_P(th->errinfo)
	    /* TODO */ ) {
	    return Qnil;
	}
	return Qfalse;
    }
    return rb_str_new2(thread_status_name(th));
}

#stop? ⇒ Boolean

Returns true if thr is dead or sleeping.

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

See also #alive? and #status.

Returns:

  • (Boolean)

Returns:

  • (Boolean) 


2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
 
# File 'thread.c', line 2696

static VALUE
rb_thread_stop_p(VALUE thread)
{
    rb_thread_t *th;
    GetThreadPtr(thread, th);

    if (rb_threadptr_dead(th))
	return Qtrue;
    if (th->status == THREAD_STOPPED || th->status == THREAD_STOPPED_FOREVER)
	return Qtrue;
    return Qfalse;
}

#exit ⇒ nil #kill ⇒ nil #terminate ⇒ nil

Terminates thr 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, exits the process.

Overloads:

  • #exit ⇒ nil

    Returns:

    • (nil)
  • #kill ⇒ nil

    Returns:

    • (nil)
  • #terminate ⇒ nil

    Returns:

    • (nil) 


2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
 
# File 'thread.c', line 2190

VALUE
rb_thread_kill(VALUE thread)
{
    rb_thread_t *th;

    GetThreadPtr(thread, th);

    if (th->to_kill || th->status == THREAD_KILLED) {
	return thread;
    }
    if (th == th->vm->main_thread) {
	rb_exit(EXIT_SUCCESS);
    }

    thread_debug("rb_thread_kill: %p (%p)\n", (void *)th, (void *)th->thread_id);

    if (th == GET_THREAD()) {
	/* kill myself immediately */
	rb_threadptr_to_kill(th);
    }
    else {
	rb_threadptr_pending_interrupt_enque(th, eKillSignal);
	rb_threadptr_interrupt(th);
    }
    return thread;
}

#thread_variable?(key) ⇒ Boolean

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

me = Thread.current
me.thread_variable_set(:oliver, "a")
me.thread_variable?(:oliver)    #=> true
me.thread_variable?(:stanley)   #=> false

Note that these are not fiber local variables. Please see Thread#[] and Thread#thread_variable_get for more details.

Returns:

  • (Boolean)

Returns:

  • (Boolean) 


3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
 
# File 'thread.c', line 3084

static VALUE
rb_thread_variable_p(VALUE thread, VALUE key)
{
    VALUE locals;
    ID id = rb_check_id(&key);

    if (!id) return Qfalse;

    locals = rb_ivar_get(thread, id_locals);

    if (!RHASH(locals)->ntbl)
        return Qfalse;

    if (st_lookup(RHASH(locals)->ntbl, ID2SYM(id), 0)) {
	return Qtrue;
    }

    return Qfalse;
}

#thread_variable_get(key) ⇒ Object?

Returns the value of a thread local variable that has been set. Note that these are different than fiber local values. For fiber local values, please see Thread#[] and Thread#[]=.

Thread local values are carried along with threads, and do not respect fibers. For example:

Thread.new {
  Thread.current.thread_variable_set("foo", "bar") # set a thread local
  Thread.current["foo"] = "bar"                    # set a fiber local

  Fiber.new {
    Fiber.yield [
      Thread.current.thread_variable_get("foo"), # get the thread local
      Thread.current["foo"],                     # get the fiber local
    ]
  }.resume
}.join.value # => ['bar', nil]

The value “bar” is returned for the thread local, where nil is returned for the fiber local. The fiber is executed in the same thread, so the thread local values are available.

Returns:



2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
 
# File 'thread.c', line 2917

static VALUE
rb_thread_variable_get(VALUE thread, VALUE key)
{
    VALUE locals;
    ID id = rb_check_id(&key);

    if (!id) return Qnil;
    locals = rb_ivar_get(thread, id_locals);
    return rb_hash_aref(locals, ID2SYM(id));
}

#thread_variable_set(key, value) ⇒ Object

Sets a thread local with key to value. Note that these are local to threads, and not to fibers. Please see Thread#thread_variable_get and Thread#[] for more information.



2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
 
# File 'thread.c', line 2937

static VALUE
rb_thread_variable_set(VALUE thread, VALUE id, VALUE val)
{
    VALUE locals;

    if (OBJ_FROZEN(thread)) {
	rb_error_frozen("thread locals");
    }

    locals = rb_ivar_get(thread, id_locals);
    return rb_hash_aset(locals, ID2SYM(rb_to_id(id)), val);
}

#thread_variables ⇒ Array

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

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

Note that these are not fiber local variables. Please see Thread#[] and Thread#thread_variable_get for more details.

Returns:



3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
 
# File 'thread.c', line 3055

static VALUE
rb_thread_variables(VALUE thread)
{
    VALUE locals;
    VALUE ary;

    locals = rb_ivar_get(thread, id_locals);
    ary = rb_ary_new();
    rb_hash_foreach(locals, keys_i, ary);

    return ary;
}

#value ⇒ Object

Waits for thr to complete, using #join, and returns its value or raises the exception which terminated the thread.

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

b = Thread.new { raise 'something went wrong' }
b.value   #=> RuntimeError: something went wrong

Returns:



929
930
931
932
933
934
935
936
 
# File 'thread.c', line 929

static VALUE
thread_value(VALUE self)
{
    rb_thread_t *th;
    GetThreadPtr(self, th);
    thread_join(th, DELAY_INFTY);
    return th->value;
}

#wakeup ⇒ Object

Marks a given thread as eligible for scheduling, however it may still remain blocked on I/O.

Note: This does not invoke the scheduler, see #run for more information.

c = Thread.new { Thread.stop; puts "hey!" }
sleep 0.1 while c.status!='sleep'
c.wakeup
c.join
#=> "hey!"



2275
2276
2277
2278
2279
2280
2281
2282
 
# File 'thread.c', line 2275

VALUE
rb_thread_wakeup(VALUE thread)
{
    if (!RTEST(rb_thread_wakeup_alive(thread))) {
	rb_raise(rb_eThreadError, "killed thread");
    }
    return thread;
}