class Thread

Threads are the Ruby implementation for a concurrent programming model.

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

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

thr =Thread.new {puts"What's the big deal" }

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

thr.join#=> "What's the big deal"

If we don’t callthr.join before the main thread terminates, then all other threads includingthr 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"What's 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 }

To retrieve the last value of a thread, usevalue

thr =Thread.new {sleep1;"Useful value" }thr.value#=> "Useful value"

`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 aThreadError will be raised.

When subclassing theThread class, theinitialize method of your subclass will be ignored by::start and::fork. Otherwise, be sure to call super in yourinitialize 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 {sleep }Thread.kill(thr)# sends exit() to thr

Alternatively, you can use the instance methodexit, or any of its aliaseskill orterminate.

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 usestatus

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

You can also usealive? to tell if the thread is running or sleeping, andstop? 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 forThread#[] storage. When you set a new fiber-local it is only accessible within thisFiber. To illustrate:

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

This example uses[] for getting and[]= for setting fiber-locals, you can also usekeys to list the fiber-locals for a given thread andkey? 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)pThread.current.thread_variable_get(:foo)# => 1Fiber.new{Thread.current.thread_variable_set(:foo,2)pThread.current.thread_variable_get(:foo)# => 2  }.resumepThread.current.thread_variable_get(:foo)# => 2}.join

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

This example makes use ofthread_variable_set to create new thread-locals, andthread_variable_get to reference them.

There is alsothread_variables to list all thread-locals, andthread_variable? to check if a given thread-local exists.

When an unhandled exception is raised inside a thread, it will terminate. By default, this exception will not propagate to other threads. The exception is stored and when another thread callsvalue orjoin, the exception will be re-raised in that thread.

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

An exception can be raised from outside the thread using theThread#raise instance method, which takes the same parameters asKernel#raise.

SettingThread.abort_on_exception = true,Thread#abort_on_exception = true, or $DEBUG = true will cause a subsequent unhandled exception raised in a thread to be automatically re-raised in the main thread.

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 methodwakeup 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 forpriority, 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.

Public Class Methods

abort_on_exception → true or false

Source

static VALUErb_thread_s_abort_exc(VALUE _){    return RBOOL(GET_THREAD()->vm->thread_abort_on_exception);}

Returns the status of the global “abort on exception” condition.

The default isfalse.

When set totrue, if any thread is aborted by an exception, the raised exception will be re-raised in the main thread.

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

NOTE¶↑

Asynchronous interrupts are difficult to use.

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

Or use them with deep understanding about this method.

Usage¶↑

In this example, we can guard fromThread#raise exceptions.

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

th =Thread.newdoThread.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  }endThread.pass# ...th.raise"stop"

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

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

For handling all interrupts, useObject and notException as the ExceptionClass, as kill/terminate interrupts are not handled byException.

ignore_deadlock → true or false

Source

static VALUErb_thread_s_ignore_deadlock(VALUE _){    return RBOOL(GET_THREAD()->vm->thread_ignore_deadlock);}

Returns the status of the global “ignore deadlock” condition. The default isfalse, so that deadlock conditions are not ignored.

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

report_on_exception → true or false

Source

static VALUErb_thread_s_report_exc(VALUE _){    return RBOOL(GET_THREAD()->vm->thread_report_on_exception);}

Returns the status of the global “report on exception” condition.

The default istrue since Ruby 2.5.

All threads created when this flag is true will report a message on $stderr if an exception kills the thread.

Thread.new {1.times {raise } }

will produce this output on $stderr:

#<Thread:...> terminated with exception (report_on_exception is true):Traceback (most recent call last):        2: from -e:1:in `block in <main>'        1: from -e:1:in `times'

This is done to catch errors in threads early. In some cases, you might not want this output. There are multiple ways to avoid the extra output:

If the exception is not intended, the best is to fix the cause of the exception so it does not happen anymore.
If the exception is intended, it might be better to rescue it closer to where it is raised rather then let it kill theThread.
If it is guaranteed theThread will be joined withThread#join orThread#value, then it is safe to disable this report withThread.current.report_on_exception = false when starting theThread. However, this might handle the exception much later, or not at all if theThread is never joined due to the parent thread being blocked, etc.

Public Instance Methods

thr[sym] → obj or nil

Source

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

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

[Thread.new {Thread.current["name"] ="A" },Thread.new {Thread.current[:name]  ="B" },Thread.new {Thread.current["name"] ="C" }].eachdo|th|th.joinputs"#{th.inspect}: #{th[:name]}"end

This will produce:

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

Thread#[] andThread#[]= 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.

defmeth(newvalue)beginoldvalue =Thread.current[:name]Thread.current[:name] =newvalueyieldensureThread.current[:name] =oldvalueendend

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.resumepThread.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 seethread_variable_get andthread_variable_set.

thr[sym] = obj → obj

Source

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

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

See alsostop? andstatus.

backtrace → array or nil

Source

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

Returns the current backtrace of the target thread.

backtrace_locations(*args) → array or nil

Source

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

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

SeeThread::Backtrace::Location for more information.

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

exit → thr

Terminatesthr and schedules another thread to be run, returning the terminatedThread. If this is the main thread, or the last thread, exits the process.

Alias for:kill

fetch(sym) → obj

fetch(sym) { } → obj

fetch(sym, default) → obj

Source

static VALUErb_thread_fetch(int argc, VALUE *argv, VALUE self){    VALUE key, val;    ID id;    rb_thread_t *target_th = rb_thread_ptr(self);    int block_given;    rb_check_arity(argc, 1, 2);    key = argv[0];    block_given = rb_block_given_p();    if (block_given && argc == 2) {        rb_warn("block supersedes default value argument");    }    id = rb_check_id(&key);    if (id == recursive_key) {        return target_th->ec->local_storage_recursive_hash;    }    else if (id && target_th->ec->local_storage &&             rb_id_table_lookup(target_th->ec->local_storage, id, &val)) {        return val;    }    else if (block_given) {        return rb_yield(key);    }    else if (argc == 1) {        rb_key_err_raise(rb_sprintf("key not found: %+"PRIsVALUE, key), self, key);    }    else {        return argv[1];    }}

Returns a fiber-local for the given key. If the key can’t be found, there are several options: With no other arguments, it will raise aKeyError exception; ifdefault is given, then that will be returned; if the optional code block is specified, then that will be run and its result returned. SeeThread#[] andHash#fetch.

group → thgrp or nil

Source

VALUErb_thread_group(VALUE thread){    return rb_thread_ptr(thread)->thgroup;}

Returns theThreadGroup which contains the given thread.

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

inspect

Alias for:to_s

join → thr

join(limit) → thr

Source

static VALUEthread_join_m(int argc, VALUE *argv, VALUE self){    VALUE timeout = Qnil;    rb_hrtime_t rel = 0, *limit = 0;    if (rb_check_arity(argc, 0, 1)) {        timeout = argv[0];    }    // Convert the timeout eagerly, so it's always converted and deterministic    /*     * This supports INFINITY and negative values, so we can't use     * rb_time_interval right now...     */    if (NIL_P(timeout)) {        /* unlimited */    }    else if (FIXNUM_P(timeout)) {        rel = rb_sec2hrtime(NUM2TIMET(timeout));        limit = &rel;    }    else {        limit = double2hrtime(&rel, rb_num2dbl(timeout));    }    return thread_join(rb_thread_ptr(self), timeout, limit);}

The calling thread will suspend execution and run thisthr.

Does not return untilthr exits or until the givenlimit seconds have passed.

If the time limit expires,nil will be returned, otherwisethr is returned.

Any threads not joined will be killed when the main program exits.

Ifthr 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 thelimit parameter.

y =Thread.new {4.times {sleep0.1;puts'tick... ' }}puts"Waiting"untily.join(0.15)

This will produce:

tick...Waitingtick...Waitingtick...tick...

key?(sym) → true or false

Source

static VALUErb_thread_key_p(VALUE self, VALUE key){    VALUE val;    ID id = rb_check_id(&key);    struct rb_id_table *local_storage = rb_thread_ptr(self)->ec->local_storage;    if (!id || local_storage == NULL) {        return Qfalse;    }    return RBOOL(rb_id_table_lookup(local_storage, id, &val));}

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

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

keys → array

Source

static VALUErb_thread_keys(VALUE self){    struct rb_id_table *local_storage = rb_thread_ptr(self)->ec->local_storage;    VALUE ary = rb_ary_new();    if (local_storage) {        rb_id_table_foreach(local_storage, thread_keys_i, (void *)ary);    }    return ary;}

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

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

kill → thr

Source

VALUErb_thread_kill(VALUE thread){    rb_thread_t *target_th = rb_thread_ptr(thread);    if (target_th->to_kill || target_th->status == THREAD_KILLED) {        return thread;    }    if (target_th == target_th->vm->ractor.main_thread) {        rb_exit(EXIT_SUCCESS);    }    RUBY_DEBUG_LOG("target_th:%u", rb_th_serial(target_th));    if (target_th == GET_THREAD()) {        /* kill myself immediately */        rb_threadptr_to_kill(target_th);    }    else {        threadptr_check_pending_interrupt_queue(target_th);        rb_threadptr_pending_interrupt_enque(target_th, RUBY_FATAL_THREAD_KILLED);        rb_threadptr_interrupt(target_th);    }    return thread;}

Terminatesthr and schedules another thread to be run, returning the terminatedThread. If this is the main thread, or the last thread, exits the process.

Also aliased as:terminate,exit

name → string

Source

static VALUErb_thread_getname(VALUE thread){    return rb_thread_ptr(thread)->name;}

show the name of the thread.

name=(name) → string

Source

static VALUErb_thread_setname(VALUE thread, VALUE name){    rb_thread_t *target_th = rb_thread_ptr(thread);    if (!NIL_P(name)) {        rb_encoding *enc;        StringValueCStr(name);        enc = rb_enc_get(name);        if (!rb_enc_asciicompat(enc)) {            rb_raise(rb_eArgError, "ASCII incompatible encoding (%s)",                     rb_enc_name(enc));        }        name = rb_str_new_frozen(name);    }    target_th->name = name;    if (threadptr_initialized(target_th) && target_th->has_dedicated_nt) {        native_set_another_thread_name(target_th->nt->thread_id, name);    }    return name;}

set given name to the ruby thread. On some platform, it may set the name to pthread and/or kernel.

native_thread_id → integer

Source

static VALUErb_thread_native_thread_id(VALUE thread){    rb_thread_t *target_th = rb_thread_ptr(thread);    if (rb_threadptr_dead(target_th)) return Qnil;    return native_thread_native_thread_id(target_th);}

Return the native thread ID which is used by the Ruby thread.

The ID depends on the OS. (not POSIX thread ID returned by pthread_self(3))

On Linux it is TID returned by gettid(2).
On macOS it is the system-wide unique integral ID of thread returned by pthread_threadid_np(3).
On FreeBSD it is the unique integral ID of the thread returned by pthread_getthreadid_np(3).
On Windows it is the thread identifier returned by GetThreadId().
On other platforms, it raisesNotImplementedError.

NOTE: If the thread is not associated yet or already deassociated with a native thread, it returnsnil. If the Ruby implementation uses M:N thread model, the ID may change depending on the timing.

pending_interrupt?(error = nil) → true/false

Source

static VALUErb_thread_pending_interrupt_p(int argc, VALUE *argv, VALUE target_thread){    rb_thread_t *target_th = rb_thread_ptr(target_thread);    if (!target_th->pending_interrupt_queue) {        return Qfalse;    }    if (rb_threadptr_pending_interrupt_empty_p(target_th)) {        return Qfalse;    }    if (rb_check_arity(argc, 0, 1)) {        VALUE err = argv[0];        if (!rb_obj_is_kind_of(err, rb_cModule)) {            rb_raise(rb_eTypeError, "class or module required for rescue clause");        }        return RBOOL(rb_threadptr_pending_interrupt_include_p(target_th, err));    }    else {        return Qtrue;    }}

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

Iferror is given, then check only forerror type deferred events.

See::pending_interrupt? for more information.

priority → integer

Source

static VALUErb_thread_priority(VALUE thread){    return INT2NUM(rb_thread_ptr(thread)->priority);}

Returns the priority ofthr. 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

priority= integer → thr

Source

static VALUErb_thread_priority_set(VALUE thread, VALUE prio){    rb_thread_t *target_th = rb_thread_ptr(thread);    int priority;#if USE_NATIVE_THREAD_PRIORITY    target_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;    }    target_th->priority = (int8_t)priority;#endif    return INT2NUM(target_th->priority);}

Sets the priority ofthr tointeger. 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 =0a =Thread.newdoloop {count1+=1 }enda.priority =-1b =Thread.newdoloop {count2+=1 }endb.priority =-2sleep1#=> 1count1#=> 622504count2#=> 5832

raise

raise(string)

raise(exception [, string [, array]])

Source

static VALUEthread_raise_m(int argc, VALUE *argv, VALUE self){    rb_thread_t *target_th = rb_thread_ptr(self);    const rb_thread_t *current_th = GET_THREAD();    threadptr_check_pending_interrupt_queue(target_th);    rb_threadptr_raise(target_th, argc, argv);    /* To perform Thread.current.raise as Kernel.raise */    if (current_th == target_th) {        RUBY_VM_CHECK_INTS(target_th->ec);    }    return Qnil;}

Raises an exception from the given thread. The caller does not have to bethr. SeeKernel#raise for more information.

Thread.abort_on_exception =truea =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

report_on_exception → true or false

Source

static VALUErb_thread_report_exc(VALUE thread){    return RBOOL(rb_thread_ptr(thread)->report_on_exception);}

Returns the status of the thread-local “report on exception” condition for thisthr.

The default value when creating aThread is the value of the global flagThread.report_on_exception.

Movatterモバイル変換

class Thread

`Thread` initialization¶↑

`Thread` termination¶↑

`Thread` status¶↑

`Thread` variables and scope¶↑

Fiber-local vs. Thread-local¶↑

`Exception` handling¶↑

Scheduling¶↑

Public Class Methods

NOTE¶↑

Usage¶↑

Stack control settings¶↑

Inheritance with ExceptionClass¶↑

Usage¶↑

Public Instance Methods

Movatterモバイル変換

class Thread

Thread initialization¶↑

Thread termination¶↑

Thread status¶↑

Thread variables and scope¶↑

Fiber-local vs. Thread-local¶↑

Exception handling¶↑

Scheduling¶↑

NOTE¶↑

Usage¶↑

Stack control settings¶↑

Inheritance with ExceptionClass¶↑

Usage¶↑

`Thread` initialization¶↑

`Thread` termination¶↑

`Thread` status¶↑

`Thread` variables and scope¶↑

`Exception` handling¶↑