Class: Thread
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
-
.abort_on_exception ⇒ Boolean
Returns the status of the global “abort on exception” condition.
-
.abort_on_exception=(boolean) ⇒ Boolean
When set to
true
, all threads will abort if an exception is raised. -
.current ⇒ Object
Returns the currently executing thread.
-
.DEBUG ⇒ Numeric
Returns the thread debug level.
-
.DEBUG=(num) ⇒ Object
Sets the thread debug level.
-
.exit ⇒ Object
Terminates the currently running thread and schedules another thread to be run.
-
.fork ⇒ Object
Basically the same as ::new.
-
.handle_interrupt(hash) { ... } ⇒ Object
Changes asynchronous interrupt timing.
-
.kill(thread) ⇒ Object
Causes the given
thread
to exit, see also Thread::exit. -
.list ⇒ Array
Returns an array of Thread objects for all threads that are either runnable or stopped.
-
.main ⇒ Object
Returns the main thread.
-
.new ⇒ Object
Thread.new(*args, &proc) -> thread Thread.new(*args) { |args| … } -> thread.
-
.pass ⇒ nil
Give the thread scheduler a hint to pass execution to another thread.
-
.pending_interrupt?(error = nil) ⇒ Boolean
Returns whether or not the asynchronous queue is empty.
-
.start ⇒ Object
Basically the same as ::new.
-
.stop ⇒ nil
Stops execution of the current thread, putting it into a “sleep” state, and schedules execution of another thread.
Instance Method Summary collapse
-
#[](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.
-
#[]=(sym) ⇒ Object
Attribute Assignment—Sets or creates the value of a fiber-local variable, using either a symbol or a string.
-
#abort_on_exception ⇒ Boolean
Returns the status of the thread-local “abort on exception” condition for this
thr
. -
#abort_on_exception=(boolean) ⇒ Boolean
When set to
true
, all threads (including the main program) will abort if an exception is raised in thisthr
. -
#add_trace_func(proc) ⇒ Proc
Adds proc as a handler for tracing.
-
#alive? ⇒ Boolean
Returns
true
ifthr
is running or sleeping. -
#backtrace ⇒ Array
Returns the current backtrace of the target thread.
-
#backtrace_locations(*args) ⇒ Object
Returns the execution stack for the target thread—an array containing backtrace location objects.
-
#exit ⇒ Object
Terminates
thr
and schedules another thread to be run. -
#group ⇒ nil
Returns the ThreadGroup which contains the given thread, or returns
nil
ifthr
is not a member of any group. -
#initialize ⇒ Object
constructor
:nodoc:.
-
#inspect ⇒ String
Dump the name, id, and status of thr to a string.
-
#join ⇒ Object
The calling thread will suspend execution and run this
thr
. -
#key?(sym) ⇒ Boolean
Returns
true
if the given string (or symbol) exists as a fiber-local variable. -
#keys ⇒ Array
Returns an array of the names of the fiber-local variables (as Symbols).
-
#kill ⇒ Object
Terminates
thr
and schedules another thread to be run. -
#pending_interrupt?(error = nil) ⇒ Boolean
Returns whether or not the asynchronous queue is empty for the target thread.
-
#priority ⇒ Integer
Returns the priority of thr.
-
#priority=(integer) ⇒ Object
Sets the priority of thr to integer.
-
#raise ⇒ Object
Raises an exception from the given thread.
-
#run ⇒ Object
Wakes up
thr
, making it eligible for scheduling. -
#safe_level ⇒ Integer
Returns the safe level in effect for thr.
-
#set_trace_func ⇒ Object
Establishes proc on thr as the handler for tracing, or disables tracing if the parameter is
nil
. -
#status ⇒ String, ...
Returns the status of
thr
. -
#stop? ⇒ Boolean
Returns
true
ifthr
is dead or sleeping. -
#terminate ⇒ Object
Terminates
thr
and schedules another thread to be run. -
#thread_variable?(key) ⇒ Boolean
Returns
true
if the given string (or symbol) exists as a thread-local variable. -
#thread_variable_get(key) ⇒ Object?
Returns the value of a thread local variable that has been set.
-
#thread_variable_set(key, value) ⇒ Object
Sets a thread local with
key
tovalue
. -
#thread_variables ⇒ Array
Returns an array of the names of the thread-local variables (as Symbols).
-
#value ⇒ Object
Waits for
thr
to complete, using #join, and returns its value. -
#wakeup ⇒ Object
Marks a given thread as eligible for scheduling, however it may still remain blocked on I/O.
Constructor Details
#initialize ⇒ Object
:nodoc:
716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 |
# File 'thread.c', line 716
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.
2458 2459 2460 2461 2462 |
# File 'thread.c', line 2458
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=.
2494 2495 2496 2497 2498 2499 |
# File 'thread.c', line 2494
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>
2412 2413 2414 2415 2416 |
# File 'thread.c', line 2412
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.
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.
2244 2245 2246 2247 2248 2249 |
# File 'thread.c', line 2244
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.
709 710 711 712 713 |
# File 'thread.c', line 709
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.
}
1784 1785 1786 1787 1788 1789 1790 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 |
# File 'thread.c', line 1784
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
2225 2226 2227 2228 2229 |
# File 'thread.c', line 2225
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>
2389 2390 2391 2392 2393 2394 2395 |
# File 'thread.c', line 2389
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.
2431 2432 2433 2434 2435 |
# File 'thread.c', line 2431
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.
681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 |
# File 'thread.c', line 681
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.
1509 1510 1511 1512 1513 1514 |
# File 'thread.c', line 1509
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
1920 1921 1922 1923 1924 |
# File 'thread.c', line 1920
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.
709 710 711 712 713 |
# File 'thread.c', line 709
static VALUE
thread_start(VALUE klass, VALUE args)
{
return thread_create_core(rb_thread_alloc(klass), args, 0);
}
|
.stop ⇒ nil
2338 2339 2340 2341 2342 2343 2344 2345 2346 2347 |
# File 'thread.c', line 2338
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.
2822 2823 2824 2825 2826 2827 2828 |
# File 'thread.c', line 2822
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.
2864 2865 2866 2867 2868 |
# File 'thread.c', line 2864
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.
2517 2518 2519 2520 2521 2522 2523 |
# File 'thread.c', line 2517
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=.
2541 2542 2543 2544 2545 2546 2547 2548 2549 |
# File 'thread.c', line 2541
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.
525 526 527 528 529 530 531 532 533 |
# File 'vm_trace.c', line 525
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
2664 2665 2666 2667 2668 2669 2670 2671 2672 2673 |
# File 'thread.c', line 2664
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.
5001 5002 5003 5004 5005 |
# File 'thread.c', line 5001
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.
5018 5019 5020 5021 5022 |
# File 'thread.c', line 5018
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.
2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 |
# File 'thread.c', line 2183
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
2562 2563 2564 2565 2566 2567 2568 2569 2570 2571 2572 2573 2574 |
# File 'thread.c', line 2562
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.
2730 2731 2732 2733 2734 2735 2736 2737 2738 2739 2740 2741 2742 2743 2744 |
# File 'thread.c', line 2730
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...
895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 |
# File 'thread.c', line 895
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
2944 2945 2946 2947 2948 2949 2950 2951 2952 2953 2954 2955 2956 2957 2958 2959 |
# File 'thread.c', line 2944
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
2999 3000 3001 3002 3003 3004 3005 3006 3007 3008 3009 3010 |
# File 'thread.c', line 2999
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.
2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 |
# File 'thread.c', line 2183
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.
1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 |
# File 'thread.c', line 1835
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
3100 3101 3102 3103 3104 3105 3106 |
# File 'thread.c', line 3100
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
3135 3136 3137 3138 3139 3140 3141 3142 3143 3144 3145 3146 3147 3148 3149 3150 3151 3152 3153 3154 3155 3156 3157 |
# File 'thread.c', line 3135
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
2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 |
# File 'thread.c', line 2154
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
2314 2315 2316 2317 2318 2319 2320 |
# File 'thread.c', line 2314
VALUE
rb_thread_run(VALUE thread)
{
rb_thread_wakeup(thread);
rb_thread_schedule();
return thread;
}
|
#safe_level ⇒ Integer
2714 2715 2716 2717 2718 2719 2720 2721 |
# File 'thread.c', line 2714
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.
546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 |
# File 'vm_trace.c', line 546
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?
2633 2634 2635 2636 2637 2638 2639 2640 2641 2642 2643 2644 2645 2646 2647 |
# File 'thread.c', line 2633
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
2689 2690 2691 2692 2693 2694 2695 2696 2697 2698 2699 2700 |
# File 'thread.c', line 2689
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.
2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 |
# File 'thread.c', line 2183
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.
3065 3066 3067 3068 3069 3070 3071 3072 3073 3074 3075 3076 3077 3078 3079 3080 3081 3082 3083 |
# File 'thread.c', line 3065
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.
2898 2899 2900 2901 2902 2903 2904 2905 2906 2907 |
# File 'thread.c', line 2898
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.
2918 2919 2920 2921 2922 2923 2924 2925 2926 2927 2928 2929 |
# File 'thread.c', line 2918
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.
3036 3037 3038 3039 3040 3041 3042 3043 3044 3045 3046 3047 |
# File 'thread.c', line 3036
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
922 923 924 925 926 927 928 929 |
# File 'thread.c', line 922
static VALUE
thread_value(VALUE self)
{
rb_thread_t *th;
GetThreadPtr(self, th);
thread_join(th, DELAY_INFTY);
return th->value;
}
|
#wakeup ⇒ Object
2268 2269 2270 2271 2272 2273 2274 2275 |
# File 'thread.c', line 2268
VALUE
rb_thread_wakeup(VALUE thread)
{
if (!RTEST(rb_thread_wakeup_alive(thread))) {
rb_raise(rb_eThreadError, "killed thread");
}
return thread;
}
|