Class: Thread (Ruby 2.3.4)

    In Files

    • prelude.rb
    • thread.c
    • thread_sync.c
    • vm.c
    • vm_trace.c

    Class/Module Index [+]

    Quicksearch

    Thread

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

    Public Class Methods

    DEBUG → num click to toggle source

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

     
                   static VALUE
    rb_thread_s_debug(void)
    {
        return INT2NUM(rb_thread_debug_enabled);
    }
                
    DEBUG = num click to toggle source

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

     
                   static VALUE
    rb_thread_s_debug_set(VALUE self, VALUE val)
    {
        rb_thread_debug_enabled = RTEST(val) ? NUM2INT(val) : 0;
        return val;
    }
                
    abort_on_exception → true or false click to toggle source

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

    The default is false.

    When set to true, 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.

    See also ::abort_on_exception=.

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

     
                   static VALUE
    rb_thread_s_abort_exc(void)
    {
        return GET_THREAD()->vm->thread_abort_on_exception ? Qtrue : Qfalse;
    }
                
    abort_on_exception= boolean → true or false click to toggle source

    When set to true, if any thread is aborted by an exception, the raised exception will be re-raised in the main thread. 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=.

     
                   static VALUE
    rb_thread_s_abort_exc_set(VALUE self, VALUE val)
    {
        GET_THREAD()->vm->thread_abort_on_exception = RTEST(val);
        return val;
    }
                
    current → thread click to toggle source

    Returns the currently executing thread.

    Thread.current   #=> #<Thread:0x401bdf4c run>
    
     
                   static VALUE
    thread_s_current(VALUE klass)
    {
        return rb_thread_current();
    }
                
    exclusive { block } => obj click to toggle source

    Wraps the block in a single, VM-global Thread::Mutex#synchronize, returning the value of the block. A thread executing inside the exclusive section will only block other threads which also use the ::exclusive mechanism.

     
                   # File prelude.rb, line 10
    def self.exclusive
      warn "Thread.exclusive is deprecated, use Mutex", caller
      MUTEX_FOR_THREAD_EXCLUSIVE.synchronize{
        yield
      }
    end
                
    exit → thread click to toggle source

    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.

     
                   static VALUE
    rb_thread_exit(void)
    {
        rb_thread_t *th = GET_THREAD();
        return rb_thread_kill(th->self);
    }
                
    fork([args]*) {|args| block } → thread click to toggle source

    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.

     
                   static VALUE
    thread_start(VALUE klass, VALUE args)
    {
        return thread_create_core(rb_thread_alloc(klass), args, 0);
    }
                
    handle_interrupt(hash) { ... } → result of the block click to toggle source

    Changes asynchronous interrupt timing.

    interrupt means asynchronous event and corresponding procedure by #raise, #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 #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 Timeout::Error

    In the next example, we will guard from the Timeout::Error exception. This will help prevent from leaking resources when Timeout::Error 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(Timeout::Error => :never) {
      timeout(10){
        # Timeout::Error doesn't occur here
        Thread.handle_interrupt(Timeout::Error => :on_blocking) {
          # possible to be killed by Timeout::Error
          # while blocking operation
        }
        # Timeout::Error doesn't occur here
      }
    }
    

    In the first part of the timeout block, we can rely on Timeout::Error being ignored. Then in the Timeout::Error => :on_blocking block, any operation that will block the calling thread is susceptible to a Timeout::Error 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.
    }
    
     
                   static VALUE
    rb_thread_s_handle_interrupt(VALUE self, VALUE mask_arg)
    {
        VALUE mask;
        rb_thread_t *th = GET_THREAD();
        volatile VALUE r = Qnil;
        int state;
    
        if (!rb_block_given_p()) {
            rb_raise(rb_eArgError, "block is needed.");
        }
    
        mask = 0;
        mask_arg = rb_convert_type(mask_arg, T_HASH, "Hash", "to_hash");
        rb_hash_foreach(mask_arg, handle_interrupt_arg_check_i, (VALUE)&mask);
        if (!mask) {
            return rb_yield(Qnil);
        }
        OBJ_FREEZE_RAW(mask);
        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) → thread click to toggle source

    Causes the given thread to exit, see also ::exit.

    count = 0
    a = Thread.new { loop { count += 1 } }
    sleep(0.1)       #=> 0
    Thread.kill(a)   #=> #<Thread:0x401b3d30 dead>
    count            #=> 93947
    a.alive?         #=> false
    
     
                   static VALUE
    rb_thread_s_kill(VALUE obj, VALUE th)
    {
        return rb_thread_kill(th);
    }
                
    list → array click to toggle source

    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>
    
     
                   VALUE
    rb_thread_list(void)
    {
        VALUE ary = rb_ary_new();
        rb_vm_t *vm = GET_THREAD()->vm;
        rb_thread_t *th = 0;
    
        list_for_each(&vm->living_threads, th, vmlt_node) {
            switch (th->status) {
              case THREAD_RUNNABLE:
              case THREAD_STOPPED:
              case THREAD_STOPPED_FOREVER:
                rb_ary_push(ary, th->self);
              default:
                break;
            }
        }
        return ary;
    }
                
    main → thread click to toggle source

    Returns the main thread.

     
                   static VALUE
    rb_thread_s_main(VALUE klass)
    {
        return rb_thread_main();
    }
                
    new { ... } → thread click to toggle source
    new(*args, &proc) → 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.

     
                   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 (!threadptr_initialized(th)) {
            rb_raise(rb_eThreadError, "uninitialized thread - check `%"PRIsVALUE"#initialize'",
                     klass);
        }
        return thread;
    }
                
    pass → nil click to toggle source

    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.

     
                   static VALUE
    thread_s_pass(VALUE klass)
    {
        rb_thread_schedule();
        return Qnil;
    }
                
    pending_interrupt?(error = nil) → true/false click to toggle source

    Returns whether or not the asynchronous queue is empty.

    Since ::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
     
                   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| block } → thread click to toggle source

    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.

     
                   static VALUE
    thread_start(VALUE klass, VALUE args)
    {
        return thread_create_core(rb_thread_alloc(klass), args, 0);
    }
                
    stop → nil click to toggle source

    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"
    
     
                   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;
    }
                

    Public Instance Methods

    thr[sym] → obj or nil click to toggle source

    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
    

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

     
                   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);
    }
                
    thr[sym] = obj → obj click to toggle source

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

    See also #[].

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

     
                   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 → true or false click to toggle source

    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.

     
                   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 → true or false click to toggle source

    When set to true, if this thr is aborted by an exception, the raised exception will be re-raised in the main thread.

    See also abort_on_exception.

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

     
                   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 click to toggle source

    Adds proc as a handler for tracing.

    See #set_trace_func and Kernel#set_trace_func.

     
                   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? → true or false click to toggle source

    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.

     
                   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 click to toggle source

    Returns the current backtrace of the target thread.

     
                   static VALUE
    rb_thread_backtrace_m(int argc, VALUE *argv, VALUE thval)
    {
        return rb_vm_thread_backtrace(argc, argv, thval);
    }
                
    backtrace_locations(*args) → array or nil click to toggle source

    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.

     
                   static VALUE
    rb_thread_backtrace_locations_m(int argc, VALUE *argv, VALUE thval)
    {
        return rb_vm_thread_backtrace_locations(argc, argv, thval);
    }
                
    exit → thr or nil click to toggle source
    kill → thr or nil
    terminate → thr or 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.

     
                   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 (%"PRI_THREAD_ID")\n", (void *)th, thread_id_str(th));
    
        if (th == GET_THREAD()) {
            /* kill myself immediately */
            rb_threadptr_to_kill(th);
        }
        else {
            threadptr_check_pending_interrupt_queue(th);
            rb_threadptr_pending_interrupt_enque(th, eKillSignal);
            rb_threadptr_interrupt(th);
        }
        return thread;
    }
                
    group → thgrp or nil click to toggle source

    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>
    
     
                   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 click to toggle source

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

     
                   static VALUE
    rb_thread_inspect(VALUE thread)
    {
        VALUE cname = rb_class_path(rb_obj_class(thread));
        rb_thread_t *th;
        const char *status;
        VALUE str;
    
        GetThreadPtr(thread, th);
        status = thread_status_name(th);
        str = rb_sprintf("#<%"PRIsVALUE":%p", cname, (void *)thread);
        if (!NIL_P(th->name)) {
            rb_str_catf(str, "@%"PRIsVALUE, th->name);
        }
        if (!th->first_func && th->first_proc) {
            VALUE loc = rb_proc_location(th->first_proc);
            if (!NIL_P(loc)) {
                const VALUE *ptr = RARRAY_CONST_PTR(loc);
                rb_str_catf(str, "@%"PRIsVALUE":%"PRIsVALUE, ptr[0], ptr[1]);
                rb_gc_force_recycle(loc);
            }
        }
        rb_str_catf(str, " %s>", status);
        OBJ_INFECT(str, thread);
    
        return str;
    }
                
    join → thr click to toggle source
    join(limit) → thr

    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...
     
                   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) → true or false click to toggle source

    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
    
     
                   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 click to toggle source

    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]
    
     
                   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 → thr or nil click to toggle source
    kill → thr or nil
    terminate → thr or 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.

     
                   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 (%"PRI_THREAD_ID")\n", (void *)th, thread_id_str(th));
    
        if (th == GET_THREAD()) {
            /* kill myself immediately */
            rb_threadptr_to_kill(th);
        }
        else {
            threadptr_check_pending_interrupt_queue(th);
            rb_threadptr_pending_interrupt_enque(th, eKillSignal);
            rb_threadptr_interrupt(th);
        }
        return thread;
    }
                
    name → string click to toggle source

    show the name of the thread.

     
                   static VALUE
    rb_thread_getname(VALUE thread)
    {
        rb_thread_t *th;
        GetThreadPtr(thread, th);
        return th->name;
    }
                
    name=(name) → string click to toggle source

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

     
                   static VALUE
    rb_thread_setname(VALUE thread, VALUE name)
    {
    #ifdef SET_ANOTHER_THREAD_NAME
        const char *s = "";
    #endif
        rb_thread_t *th;
        GetThreadPtr(thread, th);
        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);
    #ifdef SET_ANOTHER_THREAD_NAME
            s = RSTRING_PTR(name);
    #endif
        }
        th->name = name;
    #if defined(SET_ANOTHER_THREAD_NAME)
        if (threadptr_initialized(th)) {
            SET_ANOTHER_THREAD_NAME(th->thread_id, s);
        }
    #endif
        return name;
    }
                
    pending_interrupt?(error = nil) → true/false click to toggle source

    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.

     
                   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 (!target_th->pending_interrupt_queue) {
            return Qfalse;
        }
        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 click to toggle source

    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
    
     
                   static VALUE
    rb_thread_priority(VALUE thread)
    {
        rb_thread_t *th;
        GetThreadPtr(thread, th);
        return INT2NUM(th->priority);
    }
                
    priority= integer → thr click to toggle source

    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
    
     
                   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 click to toggle source
    raise(string)
    raise(exception [, string [, array]])

    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
     
                   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);
        threadptr_check_pending_interrupt_queue(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 → thr click to toggle source

    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.

     
                   VALUE
    rb_thread_run(VALUE thread)
    {
        rb_thread_wakeup(thread);
        rb_thread_schedule();
        return thread;
    }
                
    safe_level → integer click to toggle source

    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 = 1; sleep }
    Thread.current.safe_level   #=> 0
    thr.safe_level              #=> 1
    
     
                   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 click to toggle source
    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.

     
                   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, false or nil click to toggle source

    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?

     
                   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? → true or false click to toggle source

    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.

     
                   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;
    }
                
    terminate → thr or nil click to toggle source

    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.

     
                   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 (%"PRI_THREAD_ID")\n", (void *)th, thread_id_str(th));
    
        if (th == GET_THREAD()) {
            /* kill myself immediately */
            rb_threadptr_to_kill(th);
        }
        else {
            threadptr_check_pending_interrupt_queue(th);
            rb_threadptr_pending_interrupt_enque(th, eKillSignal);
            rb_threadptr_interrupt(th);
        }
        return thread;
    }
                
    thread_variable?(key) → true or false click to toggle source

    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 #[] and #thread_variable_get for more details.

     
                   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) → obj or nil click to toggle source

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

    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.

     
                   static VALUE
    rb_thread_variable_get(VALUE thread, VALUE key)
    {
        VALUE locals;
    
        locals = rb_ivar_get(thread, id_locals);
        return rb_hash_aref(locals, rb_to_symbol(key));
    }
                
    thread_variable_set(key, value) click to toggle source

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

     
                   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, rb_to_symbol(id), val);
    }
                
    thread_variables → array click to toggle source

    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 #[] and #thread_variable_get for more details.

     
                   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 → obj click to toggle source

    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
    
     
                   static VALUE
    thread_value(VALUE self)
    {
        rb_thread_t *th;
        GetThreadPtr(self, th);
        thread_join(th, DELAY_INFTY);
        return th->value;
    }
                
    wakeup → thr click to toggle source

    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!"
    
     
                   VALUE
    rb_thread_wakeup(VALUE thread)
    {
        if (!RTEST(rb_thread_wakeup_alive(thread))) {
            rb_raise(rb_eThreadError, "killed thread");
        }
        return thread;
    }