Class: Thread

Inherits:

Object

Object
Thread

show all

Defined in:: vm.c

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 Thread::new.
.kill(thread) ⇒ Object

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

:nodoc:.
.pass ⇒ nil

Invokes the thread scheduler to pass execution to another thread.
.start ⇒ Object

Basically the same as Thread::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 thread-local variable, using either a symbol or a string name.
#[]=(sym) ⇒ Object

Attribute Assignment---Sets or creates the value of a thread-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 thr.
#abort_on_exception=(boolean) ⇒ Boolean

When set to true, causes all threads (including the main program) to abort if an exception is raised in thr.
#add_trace_func(proc) ⇒ Proc

Adds proc as a handler for tracing.
#alive? ⇒ Boolean

Returns true if thr is running or sleeping.
#backtrace ⇒ Array

Returns the current back trace of the thr.
#exit ⇒ Object

Terminates thr and schedules another thread to be run.
#group ⇒ nil

Returns the ThreadGroup which contains thr, or nil if the thread 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 thr.
#key?(sym) ⇒ Boolean

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

Returns an an array of the names of the thread-local variables (as Symbols).
#kill ⇒ Object

Terminates thr and schedules another thread to be run.
#priority ⇒ Integer

Returns the priority of thr.
#priority=(integer) ⇒ Object

Sets the priority of thr to integer.
#raise ⇒ Object

Raises an exception (see Kernel::raise) from thr.
#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: "sleep" if thr is sleeping or waiting on I/O, "run" if thr is executing, "aborting" if thr is aborting, false if thr terminated normally, and nil if thr terminated with an exception.
#stop? ⇒ Boolean

Returns true if thr is dead or sleeping.
#terminate ⇒ Object

Terminates thr and schedules another thread to be run.
#value ⇒ Object

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

Marks thr as eligible for scheduling (it may still remain blocked on I/O, however).

Constructor Details

#initialize ⇒ `Object`

:nodoc:

# File 'thread.c'

/* :nodoc: */
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 rb_proc_location(VALUE self);
    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_PTR(loc)[0]);
    if (NIL_P(line = RARRAY_PTR(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, or if the global $DEBUG flag is true (perhaps because the command line option -d was specified) all threads will abort (the process will exit(0)) if an exception is raised in any thread. See also Thread::abort_on_exception=.

Returns:

(Boolean)

# File 'thread.c'

/*
 *  call-seq:
 *     Thread.abort_on_exception   -> true or false
 *
 *  Returns the status of the global ``abort on exception'' condition.  The
 *  default is <code>false</code>. When set to <code>true</code>, or if the
 *  global <code>$DEBUG</code> flag is <code>true</code> (perhaps because the
 *  command line option <code>-d</code> was specified) all threads will abort
 *  (the process will <code>exit(0)</code>) if an exception is raised in any
 *  thread. See also <code>Thread::abort_on_exception=</code>.
 */

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"

produces:

In new thread
prog.rb:4: Exception from thread (RuntimeError)
 from prog.rb:2:in `initialize'
 from prog.rb:2:in `new'
 from prog.rb:2

Returns:

(Boolean)

# File 'thread.c'

/*
 *  call-seq:
 *     Thread.abort_on_exception= boolean   -> true or false
 *
 *  When set to <code>true</code>, 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"
 *
 *  <em>produces:</em>
 *
 *     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
 */

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

.current ⇒ `Object`

Returns the currently executing thread.

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

# File 'thread.c'

/*
 *  call-seq:
 *     Thread.current   -> thread
 *
 *  Returns the currently executing thread.
 *
 *     Thread.current   #=> #<Thread:0x401bdf4c run>
 */

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

.DEBUG ⇒ `Numeric`

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

Returns:

(Numeric)

# File 'thread.c'

/*
 *  call-seq:
 *     Thread.DEBUG     -> num
 *
 *  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) ⇒ `Object`

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

# File 'thread.c'

/*
 *  call-seq:
 *     Thread.DEBUG = num
 *
 *  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;
}

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

# File 'thread.c'

/*
 *  call-seq:
 *     Thread.exit   -> thread
 *
 *  Terminates the currently running thread and schedules another thread to be
 *  run. If this thread is already marked to be killed, <code>exit</code>
 *  returns the <code>Thread</code>. If this is the main thread, or the last
 *  thread, exit the process.
 */

static VALUE
rb_thread_exit(void)
{
    return rb_thread_kill(GET_THREAD()->self);
}

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

Basically the same as Thread::new. However, if class Thread is subclassed, then calling start in that subclass will not invoke the subclass's initialize method.

Overloads:

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

# File 'thread.c'

/*
 *  call-seq:
 *     Thread.start([args]*) {|args| block }   -> thread
 *     Thread.fork([args]*) {|args| block }    -> thread
 *
 *  Basically the same as <code>Thread::new</code>. However, if class
 *  <code>Thread</code> is subclassed, then calling <code>start</code> in that
 *  subclass will not invoke the subclass's <code>initialize</code> method.
 */

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

.kill(thread) ⇒ `Object`

Causes the given thread to exit (see Thread::exit).

count = 0
a = Thread.new { loop { count += 1 } }
sleep(0.1)       #=> 0
Thread.kill(a)   #=> #<Thread:0x401b3d30 dead>
count            #=> 93947
a.alive?         #=> false

# File 'thread.c'

/*
 *  call-seq:
 *     Thread.kill(thread)   -> thread
 *
 *  Causes the given <em>thread</em> to exit (see <code>Thread::exit</code>).
 *
 *     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`

Returns an array of Thread objects for all threads that are either runnable or stopped.

Thread.new { sleep(200) }
Thread.new { 1000000.times {|i| i*i } }
Thread.new { Thread.stop }
Thread.list.each {|t| p t}

produces:

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

Returns:

(Array)

# File 'thread.c'

/*
 *  call-seq:
 *     Thread.list   -> array
 *
 *  Returns an array of <code>Thread</code> 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}
 *
 *  <em>produces:</em>
 *
 *     #<Thread:0x401b3e84 sleep>
 *     #<Thread:0x401b3f38 run>
 *     #<Thread:0x401b3fb0 sleep>
 *     #<Thread:0x401bdf4c run>
 */

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.

# File 'thread.c'

/*
 *  call-seq:
 *     Thread.main   -> thread
 *
 *  Returns the main thread.
 */

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

.new ⇒ `Object`

:nodoc:

# File 'thread.c'

/* :nodoc: */
static VALUE
thread_s_new(int argc, VALUE *argv, VALUE klass)
{
    rb_thread_t *th;
    VALUE thread = rb_thread_alloc(klass);
    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`

Invokes the thread scheduler to pass execution to another thread.

a = Thread.new { print "a"; Thread.pass;
                 print "b"; Thread.pass;
                 print "c" }
b = Thread.new { print "x"; Thread.pass;
                 print "y"; Thread.pass;
                 print "z" }
a.join
b.join

produces:

axbycz

Returns:

(nil)

# File 'thread.c'

/*
 *  call-seq:
 *     Thread.pass   -> nil
 *
 *  Invokes the thread scheduler to pass execution to another thread.
 *
 *     a = Thread.new { print "a"; Thread.pass;
 *                      print "b"; Thread.pass;
 *                      print "c" }
 *     b = Thread.new { print "x"; Thread.pass;
 *                      print "y"; Thread.pass;
 *                      print "z" }
 *     a.join
 *     b.join
 *
 *  <em>produces:</em>
 *
 *     axbycz
 */

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

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

Basically the same as Thread::new. However, if class Thread is subclassed, then calling start in that subclass will not invoke the subclass's initialize method.

Overloads:

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

# File 'thread.c'

/*
 *  call-seq:
 *     Thread.start([args]*) {|args| block }   -> thread
 *     Thread.fork([args]*) {|args| block }    -> thread
 *
 *  Basically the same as <code>Thread::new</code>. However, if class
 *  <code>Thread</code> is subclassed, then calling <code>start</code> in that
 *  subclass will not invoke the subclass's <code>initialize</code> method.
 */

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

.stop ⇒ `nil`

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

a = Thread.new { print "a"; Thread.stop; print "c" }
Thread.pass
print "b"
a.run
a.join

produces:

abc

Returns:

(nil)

# File 'thread.c'

/*
 *  call-seq:
 *     Thread.stop   -> nil
 *
 *  Stops execution of the current thread, putting it into a ``sleep'' state,
 *  and schedules execution of another thread.
 *
 *     a = Thread.new { print "a"; Thread.stop; print "c" }
 *     Thread.pass
 *     print "b"
 *     a.run
 *     a.join
 *
 *  <em>produces:</em>
 *
 *     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;
}

Instance Method Details

#[](sym) ⇒ `Object`^?

Attribute Reference---Returns the value of a thread-local variable, using either a symbol or a string name. If the specified variable does not exist, returns nil.

a = Thread.new { Thread.current["name"] = "A"; Thread.stop }
b = Thread.new { Thread.current[:name]  = "B"; Thread.stop }
c = Thread.new { Thread.current["name"] = "C"; Thread.stop }
Thread.list.each {|x| puts "#{x.inspect}: #{x[:name]}" }

produces:

#<Thread:0x401b3b3c sleep>: C
#<Thread:0x401b3bc8 sleep>: B
#<Thread:0x401b3c68 sleep>: A
#<Thread:0x401bdf4c run>:

Returns:

(Object, nil)

# File 'thread.c'

/*
 *  call-seq:
 *      thr[sym]   -> obj or nil
 *
 *  Attribute Reference---Returns the value of a thread-local variable, using
 *  either a symbol or a string name. If the specified variable does not exist,
 *  returns <code>nil</code>.
 *
 *     a = Thread.new { Thread.current["name"] = "A"; Thread.stop }
 *     b = Thread.new { Thread.current[:name]  = "B"; Thread.stop }
 *     c = Thread.new { Thread.current["name"] = "C"; Thread.stop }
 *     Thread.list.each {|x| puts "#{x.inspect}: #{x[:name]}" }
 *
 *  <em>produces:</em>
 *
 *     #<Thread:0x401b3b3c sleep>: C
 *     #<Thread:0x401b3bc8 sleep>: B
 *     #<Thread:0x401b3c68 sleep>: A
 *     #<Thread:0x401bdf4c run>:
 */

static VALUE
rb_thread_aref(VALUE thread, VALUE id)
{
    return rb_thread_local_aref(thread, rb_to_id(id));
}

#[]=(sym) ⇒ `Object`

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

Returns:

(Object)

# File 'thread.c'

/*
 *  call-seq:
 *      thr[sym] = obj   -> obj
 *
 *  Attribute Assignment---Sets or creates the value of a thread-local variable,
 *  using either a symbol or a string. See also <code>Thread#[]</code>.
 */

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 thr. The default is false. See also Thread::abort_on_exception=.

Returns:

(Boolean)

# File 'thread.c'

/*
 *  call-seq:
 *     thr.abort_on_exception   -> true or false
 *
 *  Returns the status of the thread-local ``abort on exception'' condition for
 *  <i>thr</i>. The default is <code>false</code>. See also
 *  <code>Thread::abort_on_exception=</code>.
 */

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, causes all threads (including the main program) to abort if an exception is raised in thr. The process will effectively exit(0).

Returns:

(Boolean)

# File 'thread.c'

/*
 *  call-seq:
 *     thr.abort_on_exception= boolean   -> true or false
 *
 *  When set to <code>true</code>, causes all threads (including the main
 *  program) to abort if an exception is raised in <i>thr</i>. The process will
 *  effectively <code>exit(0)</code>.
 */

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

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

Returns:

(Proc)

# File 'thread.c'

/*
 *  call-seq:
 *     thr.add_trace_func(proc)    -> proc
 *
 *  Adds _proc_ as a handler for tracing.
 *  See <code>Thread#set_trace_func</code> and +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? ⇒ `Boolean`

Returns true if thr is running or sleeping.

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

Returns:

(Boolean)

# File 'thread.c'

/*
 *  call-seq:
 *     thr.alive?   -> true or false
 *
 *  Returns <code>true</code> if <i>thr</i> is running or sleeping.
 *
 *     thr = Thread.new { }
 *     thr.join                #=> #<Thread:0x401b3fb0 dead>
 *     Thread.current.alive?   #=> true
 *     thr.alive?              #=> false
 */

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 back trace of the thr.

Returns:

(Array)

# File 'thread.c'

/*
 *  call-seq:
 *     thr.backtrace    -> array
 *
 *  Returns the current back trace of the _thr_.
 */

static VALUE
rb_thread_backtrace_m(VALUE thval)
{
    return rb_thread_backtrace(thval);
}

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

Terminates thr and schedules another thread to be run. If this thread is already marked to be killed, exit returns the Thread. If this is the main thread, or the last thread, exits the process.

Overloads:

#exit ⇒ nil
Returns:
- (nil)
#kill ⇒ nil
Returns:
- (nil)
#terminate ⇒ nil
Returns:
- (nil)

# File 'thread.c'

/*
 *  call-seq:
 *     thr.exit        -> thr or nil
 *     thr.kill        -> thr or nil
 *     thr.terminate   -> thr or nil
 *
 *  Terminates <i>thr</i> and schedules another thread to be run. If this thread
 *  is already marked to be killed, <code>exit</code> returns the
 *  <code>Thread</code>. 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 != GET_THREAD() && th->safe_level < 4) {
    rb_secure(4);
    }
    if (th->status == THREAD_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);

    rb_threadptr_interrupt(th);
    th->thrown_errinfo = eKillSignal;
    th->status = THREAD_TO_KILL;

    return thread;
}

#group ⇒ `nil`

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

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

Returns:

(nil)

# File 'thread.c'

/*
 *  call-seq:
 *     thr.group   -> thgrp or nil
 *
 *  Returns the <code>ThreadGroup</code> which contains <i>thr</i>, or nil if
 *  the thread 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`

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

Returns:

(String)

# File 'thread.c'

/*
 * call-seq:
 *   thr.inspect   -> string
 *
 * Dump the name, id, and status of _thr_ to a string.
 */

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->status);
    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 thr. Does not return until thr exits or until limit seconds have passed. If the time limit expires, nil will be returned, otherwise thr is returned.

Any threads not joined will be killed when the main program exits. If thr had previously raised an exception and the abort_on_exception and $DEBUG flags are not set (so the exception has not yet been processed) it will be processed at this time.

a = Thread.new { print "a"; sleep(10); print "b"; print "c" }
x = Thread.new { print "x"; Thread.pass; print "y"; print "z" }
x.join # Let x thread finish, a will be killed on exit.

produces:

axyz

The following example illustrates the limit parameter.

y = Thread.new { 4.times { sleep 0.1; puts 'tick... ' }}
puts "Waiting" until y.join(0.15)

produces:

tick...
Waiting
tick...
Waitingtick...

tick...

# File 'thread.c'

/*
 *  call-seq:
 *     thr.join          -> thr
 *     thr.join(limit)   -> thr
 *
 *  The calling thread will suspend execution and run <i>thr</i>. Does not
 *  return until <i>thr</i> exits or until <i>limit</i> seconds have passed. If
 *  the time limit expires, <code>nil</code> will be returned, otherwise
 *  <i>thr</i> is returned.
 *
 *  Any threads not joined will be killed when the main program exits.  If
 *  <i>thr</i> had previously raised an exception and the
 *  <code>abort_on_exception</code> and <code>$DEBUG</code> flags are not set
 *  (so the exception has not yet been processed) it will be processed at this
 *  time.
 *
 *     a = Thread.new { print "a"; sleep(10); print "b"; print "c" }
 *     x = Thread.new { print "x"; Thread.pass; print "y"; print "z" }
 *     x.join # Let x thread finish, a will be killed on exit.
 *
 *  <em>produces:</em>
 *
 *     axyz
 *
 *  The following example illustrates the <i>limit</i> parameter.
 *
 *     y = Thread.new { 4.times { sleep 0.1; puts 'tick... ' }}
 *     puts "Waiting" until y.join(0.15)
 *
 *  <em>produces:</em>
 *
 *     tick...
 *     Waiting
 *     tick...
 *     Waitingtick...
 *
 *
 *     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) ⇒ `Boolean`

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

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

Returns:

(Boolean)

# File 'thread.c'

/*
 *  call-seq:
 *     thr.key?(sym)   -> true or false
 *
 *  Returns <code>true</code> if the given string (or symbol) exists as a
 *  thread-local variable.
 *
 *     me = Thread.current
 *     me[:oliver] = "a"
 *     me.key?(:oliver)    #=> true
 *     me.key?(:stanley)   #=> false
 */

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

    GetThreadPtr(self, th);

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

#keys ⇒ `Array`

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

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

Returns:

(Array)

# File 'thread.c'

/*
 *  call-seq:
 *     thr.keys   -> array
 *
 *  Returns an an array of the names of the thread-local variables (as Symbols).
 *
 *     thr = Thread.new do
 *       Thread.current[:cat] = 'meow'
 *       Thread.current["dog"] = 'woof'
 *     end
 *     thr.join   #=> #<Thread:0x401b3f10 dead>
 *     thr.keys   #=> [:dog, :cat]
 */

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

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

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

Terminates thr and schedules another thread to be run. If this thread is already marked to be killed, exit returns the Thread. If this is the main thread, or the last thread, exits the process.

Overloads:

#exit ⇒ nil
Returns:
- (nil)
#kill ⇒ nil
Returns:
- (nil)
#terminate ⇒ nil
Returns:
- (nil)

# File 'thread.c'

/*
 *  call-seq:
 *     thr.exit        -> thr or nil
 *     thr.kill        -> thr or nil
 *     thr.terminate   -> thr or nil
 *
 *  Terminates <i>thr</i> and schedules another thread to be run. If this thread
 *  is already marked to be killed, <code>exit</code> returns the
 *  <code>Thread</code>. 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 != GET_THREAD() && th->safe_level < 4) {
    rb_secure(4);
    }
    if (th->status == THREAD_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);

    rb_threadptr_interrupt(th);
    th->thrown_errinfo = eKillSignal;
    th->status = THREAD_TO_KILL;

    return thread;
}

#priority ⇒ `Integer`

Returns the priority of thr. Default is inherited from the current thread which creating the new thread, or zero for the initial main thread; higher-priority thread will run more frequently than lower-priority threads (but lower-priority threads can also run).

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

Thread.current.priority   #=> 0

Returns:

(Integer)

# File 'thread.c'

/*
 *  call-seq:
 *     thr.priority   -> integer
 *
 *  Returns the priority of <i>thr</i>. 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) ⇒ `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

# File 'thread.c'

/*
 *  call-seq:
 *     thr.priority= integer   -> thr
 *
 *  Sets the priority of <i>thr</i> to <i>integer</i>. 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);

    rb_secure(4);

#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;
    th->slice = priority;
#endif
    return INT2NUM(th->priority);
}

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

Raises an exception (see Kernel::raise) from thr. The caller does not have to be thr.

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

produces:

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

# File 'thread.c'

/*
 *  call-seq:
 *     thr.raise
 *     thr.raise(string)
 *     thr.raise(exception [, string [, array]])
 *
 *  Raises an exception (see <code>Kernel::raise</code>) from <i>thr</i>. The
 *  caller does not have to be <i>thr</i>.
 *
 *     Thread.abort_on_exception = true
 *     a = Thread.new { sleep(200) }
 *     a.raise("Gotcha")
 *
 *  <em>produces:</em>
 *
 *     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 *th;
    GetThreadPtr(self, th);
    rb_threadptr_raise(th, argc, argv);
    return Qnil;
}

#run ⇒ `Object`

Wakes up thr, making it eligible for scheduling.

a = Thread.new { puts "a"; Thread.stop; puts "c" }
Thread.pass
puts "Got here"
a.run
a.join

produces:

a
Got here
c

# File 'thread.c'

/*
 *  call-seq:
 *     thr.run   -> thr
 *
 *  Wakes up <i>thr</i>, making it eligible for scheduling.
 *
 *     a = Thread.new { puts "a"; Thread.stop; puts "c" }
 *     Thread.pass
 *     puts "Got here"
 *     a.run
 *     a.join
 *
 *  <em>produces:</em>
 *
 *     a
 *     Got here
 *     c
 */

VALUE
rb_thread_run(VALUE thread)
{
    rb_thread_wakeup(thread);
    rb_thread_schedule();
    return thread;
}

#safe_level ⇒ `Integer`

Returns the safe level in effect for thr. Setting thread-local safe levels can help when implementing sandboxes which run insecure code.

thr = Thread.new { $SAFE = 3; sleep }
Thread.current.safe_level   #=> 0
thr.safe_level              #=> 3

Returns:

(Integer)

# File 'thread.c'

/*
 *  call-seq:
 *     thr.safe_level   -> integer
 *
 *  Returns the safe level in effect for <i>thr</i>. Setting thread-local safe
 *  levels can help when implementing sandboxes which run insecure code.
 *
 *     thr = Thread.new { $SAFE = 3; sleep }
 *     Thread.current.safe_level   #=> 0
 *     thr.safe_level              #=> 3
 */

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

Overloads:

#set_trace_func(proc) ⇒ Proc
Returns:
- (Proc)
#set_trace_func(nil) ⇒ nil
Returns:
- (nil)

# File 'thread.c'

/*
 *  call-seq:
 *     thr.set_trace_func(proc)    -> proc
 *     thr.set_trace_func(nil)     -> nil
 *
 *  Establishes _proc_ on _thr_ as the handler for tracing, or
 *  disables tracing if the parameter is +nil+.
 *  See +set_trace_func+.
 */

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

    if (NIL_P(trace)) {
    return Qnil;
    }
    thread_add_trace_func(th, trace);
    return trace;
}

#status ⇒ `String`, ...

Returns the status of thr: "sleep" if thr is sleeping or waiting on I/O, "run" if thr is executing, "aborting" if thr is aborting, false if thr terminated normally, and nil if thr terminated with an exception.

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

Returns:

(String, false, nil)

# File 'thread.c'

/*
 *  call-seq:
 *     thr.status   -> string, false or nil
 *
 *  Returns the status of <i>thr</i>: ``<code>sleep</code>'' if <i>thr</i> is
 *  sleeping or waiting on I/O, ``<code>run</code>'' if <i>thr</i> is executing,
 *  ``<code>aborting</code>'' if <i>thr</i> is aborting, <code>false</code> if
 *  <i>thr</i> terminated normally, and <code>nil</code> if <i>thr</i>
 *  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"
 */

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->status));
}

#stop? ⇒ `Boolean`

Returns true if thr is dead or sleeping.

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

Returns:

(Boolean)

# File 'thread.c'

/*
 *  call-seq:
 *     thr.stop?   -> true or false
 *
 *  Returns <code>true</code> if <i>thr</i> is dead or sleeping.
 *
 *     a = Thread.new { Thread.stop }
 *     b = Thread.current
 *     a.stop?   #=> true
 *     b.stop?   #=> false
 */

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

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

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

Terminates thr and schedules another thread to be run. If this thread is already marked to be killed, exit returns the Thread. If this is the main thread, or the last thread, exits the process.

Overloads:

#exit ⇒ nil
Returns:
- (nil)
#kill ⇒ nil
Returns:
- (nil)
#terminate ⇒ nil
Returns:
- (nil)

# File 'thread.c'

/*
 *  call-seq:
 *     thr.exit        -> thr or nil
 *     thr.kill        -> thr or nil
 *     thr.terminate   -> thr or nil
 *
 *  Terminates <i>thr</i> and schedules another thread to be run. If this thread
 *  is already marked to be killed, <code>exit</code> returns the
 *  <code>Thread</code>. 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 != GET_THREAD() && th->safe_level < 4) {
    rb_secure(4);
    }
    if (th->status == THREAD_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);

    rb_threadptr_interrupt(th);
    th->thrown_errinfo = eKillSignal;
    th->status = THREAD_TO_KILL;

    return thread;
}

#value ⇒ `Object`

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

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

Returns:

(Object)

# File 'thread.c'

/*
 *  call-seq:
 *     thr.value   -> obj
 *
 *  Waits for <i>thr</i> to complete (via <code>Thread#join</code>) and returns
 *  its value.
 *
 *     a = Thread.new { 2 + 2 }
 *     a.value   #=> 4
 */

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

#wakeup ⇒ `Object`

Marks thr as eligible for scheduling (it may still remain blocked on I/O, however). Does not invoke the scheduler (see Thread#run).

c = Thread.new { Thread.stop; puts "hey!" }
c.wakeup

produces:

hey!

# File 'thread.c'

/*
 *  call-seq:
 *     thr.wakeup   -> thr
 *
 *  Marks <i>thr</i> as eligible for scheduling (it may still remain blocked on
 *  I/O, however). Does not invoke the scheduler (see <code>Thread#run</code>).
 *
 *     c = Thread.new { Thread.stop; puts "hey!" }
 *     c.wakeup
 *
 *  <em>produces:</em>
 *
 *     hey!
 */

VALUE
rb_thread_wakeup(VALUE thread)
{
    rb_thread_t *th;
    GetThreadPtr(thread, th);

    if (th->status == THREAD_KILLED) {
    rb_raise(rb_eThreadError, "killed thread");
    }
    rb_threadptr_ready(th);
    if (th->status != THREAD_TO_KILL) {
    th->status = THREAD_RUNNABLE;
    }
    return thread;
}

Class: Thread

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Object

Class Method Details

.abort_on_exception ⇒ Boolean

.abort_on_exception=(boolean) ⇒ Boolean

.current ⇒ Object

.DEBUG ⇒ Numeric

.DEBUG=(num) ⇒ Object

.exit ⇒ Object

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

.kill(thread) ⇒ Object

.list ⇒ Array

.main ⇒ Object

.new ⇒ Object

.pass ⇒ nil

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

.stop ⇒ nil

Instance Method Details

#[](sym) ⇒ Object?

#[]=(sym) ⇒ Object

#abort_on_exception ⇒ Boolean

#abort_on_exception=(boolean) ⇒ Boolean

#add_trace_func(proc) ⇒ Proc

#alive? ⇒ Boolean

#backtrace ⇒ Array

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

#group ⇒ nil

#inspect ⇒ String

#join ⇒ Object #join(limit) ⇒ Object

#key?(sym) ⇒ Boolean

#keys ⇒ Array

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

#priority ⇒ Integer

#priority=(integer) ⇒ Object

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

#run ⇒ Object

#safe_level ⇒ Integer

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

#status ⇒ String, ...

#stop? ⇒ Boolean

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

#value ⇒ Object

#wakeup ⇒ Object

#initialize ⇒ `Object`

.abort_on_exception ⇒ `Boolean`

.abort_on_exception=(boolean) ⇒ `Boolean`

.current ⇒ `Object`

.DEBUG ⇒ `Numeric`

.DEBUG=(num) ⇒ `Object`

.exit ⇒ `Object`

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

.kill(thread) ⇒ `Object`

.list ⇒ `Array`

.main ⇒ `Object`

.new ⇒ `Object`

.pass ⇒ `nil`

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

.stop ⇒ `nil`

#[](sym) ⇒ `Object`^?

#[]=(sym) ⇒ `Object`

#abort_on_exception ⇒ `Boolean`

#abort_on_exception=(boolean) ⇒ `Boolean`

#add_trace_func(proc) ⇒ `Proc`

#alive? ⇒ `Boolean`

#backtrace ⇒ `Array`

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

#group ⇒ `nil`

#inspect ⇒ `String`

#join ⇒ `Object` #join(limit) ⇒ `Object`

#key?(sym) ⇒ `Boolean`

#keys ⇒ `Array`

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

#priority ⇒ `Integer`

#priority=(integer) ⇒ `Object`

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

#run ⇒ `Object`

#safe_level ⇒ `Integer`

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

#status ⇒ `String`, ...

#stop? ⇒ `Boolean`

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

#value ⇒ `Object`

#wakeup ⇒ `Object`