Class: Thread
Relationships & Source Files | |
Namespace Children | |
Classes:
| |
Extension / Inclusion / Inheritance Descendants | |
Subclasses:
|
|
Inherits: | Object |
Defined in: | vm.c, prelude.rb, thread.c, vm_trace.c |
Overview
Threads are the Ruby implementation for a concurrent programming model.
Programs that require multiple threads of execution are a perfect candidate for Ruby's Thread
class.
For example, we can create a new thread separate from the main thread's execution using .new.
thr = Thread.new { puts "Whats the big deal" }
Then we are able to pause the execution of the main thread and allow our new thread to finish, using #join:
thr.join #=> "Whats the big deal"
If we don't call thr.join
before the main thread terminates, then all other threads including thr
will be killed.
Alternatively, you can use an array for handling multiple threads at once, like in the following example:
threads = []
threads << Thread.new { puts "Whats the big deal" }
threads << Thread.new { 3.times { puts "Threads are fun!" } }
After creating a few threads we wait for them all to finish consecutively.
threads.each { |thr| thr.join }
Thread initialization
In order to create new threads, Ruby provides .new, .start, and .fork. A block must be provided with each of these methods, otherwise a ::ThreadError will be raised.
When subclassing the Thread
class, the #initialize method of your subclass will be ignored by .start and .fork. Otherwise, be sure to call super in your #initialize method.
Thread termination
For terminating threads, Ruby provides a variety of ways to do this.
The class method .kill, is meant to exit a given thread:
thr = Thread.new { ... }
Thread.kill(thr) # sends exit() to thr
Alternatively, you can use the instance method #exit, or any of its aliases #kill or #terminate.
thr.exit
Thread status
Ruby provides a few instance methods for querying the state of a given thread. To get a string with the current thread's state use #status
thr = Thread.new { sleep }
thr.status # => "sleep"
thr.exit
thr.status # => false
You can also use #alive? to tell if the thread is running or sleeping, and #stop? if the thread is dead or sleeping.
Thread variables and scope
Since threads are created with blocks, the same rules apply to other Ruby blocks for variable scope. Any local variables created within this block are accessible to only this thread.
Fiber-local vs. Thread-local
Each fiber has its own bucket for #[] 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.
Class Attribute Summary
-
.abort_on_exception ⇒ Boolean
rw
Returns the status of the global “abort on exception'' condition.
-
.abort_on_exception=(boolean) ⇒ Boolean
rw
When set to
true
, if any thread is aborted by an exception, the raised exception will be re-raised in the main thread. -
DEBUG ⇒ Numeric
rw
Returns the thread debug level.
-
DEBUG=(num)
rw
Sets the thread debug level.
Class Method Summary
-
.current ⇒ Thread
Returns the currently executing thread.
-
.exclusive ⇒ Object
Wraps the block in a single, VM-global Mutex#synchronize, returning the value of the block.
-
.exit ⇒ Thread
Terminates the currently running thread and schedules another thread to be run.
-
.fork([args]*) {|args| ... } ⇒ Thread
(also: .start)
Basically the same as .new.
-
.handle_interrupt(hash) ⇒ result of the block
Changes asynchronous interrupt timing.
-
.kill(thread) ⇒ Thread
Causes the given
thread
to exit, see also .exit. -
.list ⇒ Array
Returns an array of
Thread
objects for all threads that are either runnable or stopped. -
.main ⇒ Thread
Returns the main thread.
-
.new ⇒ Thread
constructor
Creates a new thread executing the given block.
-
.pass ⇒ nil
Give the thread scheduler a hint to pass execution to another thread.
-
.pending_interrupt?(error = nil) ⇒ Boolean
Returns whether or not the asynchronous queue is empty.
-
.start([args]*) {|args| ... } ⇒ Thread
Alias for .fork.
-
.stop ⇒ nil
Stops execution of the current thread, putting it into a “sleep'' state, and schedules execution of another thread.
Instance Attribute Summary
-
#abort_on_exception ⇒ Boolean
rw
Returns the status of the thread-local “abort on exception'' condition for this
thr
. -
#abort_on_exception=(boolean) ⇒ Boolean
rw
When set to
true
, if thisthr
is aborted by an exception, the raised exception will be re-raised in the main thread. -
#name ⇒ String
rw
show the name of the thread.
-
#name=(name) ⇒ String
rw
set given name to the ruby thread.
-
#priority ⇒ Integer
rw
Returns the priority of thr.
-
#priority=(integer) ⇒ Thread
rw
Sets the priority of thr to integer.
-
#alive? ⇒ Boolean
readonly
Returns
true
ifthr
is running or sleeping. -
#stop? ⇒ Boolean
readonly
Returns
true
ifthr
is dead or sleeping.
Instance Method Summary
-
#[](sym) ⇒ Object?
Attribute Reference—Returns the value of a fiber-local variable (current thread's root fiber if not explicitly inside a ::Fiber), using either a symbol or a string name.
-
#[]=(sym, obj) ⇒ Object
Attribute Assignment—Sets or creates the value of a fiber-local variable, using either a symbol or a string.
-
#add_trace_func(proc) ⇒ Proc
Adds proc as a handler for tracing.
-
#backtrace ⇒ Array
Returns the current backtrace of the target thread.
-
#backtrace_locations(*args) ⇒ Array?
Returns the execution stack for the target thread—an array containing backtrace location objects.
-
#exit ⇒ Thread?
(also: #kill, #terminate)
Terminates
thr
and schedules another thread to be run. -
#group ⇒ thgrp?
Returns the ::ThreadGroup which contains the given thread, or returns
nil
ifthr
is not a member of any group. -
#inspect ⇒ String
Dump the name, id, and status of thr to a string.
-
#join ⇒ Thread
The calling thread will suspend execution and run this
thr
. -
#key?(sym) ⇒ Boolean
Returns
true
if the given string (or symbol) exists as a fiber-local variable. -
#keys ⇒ Array
Returns an array of the names of the fiber-local variables (as Symbols).
-
#kill ⇒ Thread?
Alias for #exit.
-
#pending_interrupt?(error = nil) ⇒ Boolean
Returns whether or not the asynchronous queue is empty for the target thread.
-
#raise
Raises an exception from the given thread.
-
#run ⇒ Thread
Wakes up
thr
, making it eligible for scheduling. -
#safe_level ⇒ Integer
Returns the safe level in effect for thr.
-
#set_trace_func(proc) ⇒ Proc
Establishes proc on thr as the handler for tracing, or disables tracing if the parameter is
nil
. -
#status ⇒ String, ...
Returns the status of
thr
. -
#terminate ⇒ Thread?
Alias for #exit.
-
#thread_variable?(key) ⇒ Boolean
Returns
true
if the given string (or symbol) exists as a thread-local variable. -
#thread_variable_get(key) ⇒ Object?
Returns the value of a thread local variable that has been set.
-
#thread_variable_set(key, value)
Sets a thread local with
key
to #value. -
#thread_variables ⇒ Array
Returns an array of the names of the thread-local variables (as Symbols).
-
#value ⇒ Object
Waits for
thr
to complete, using #join, and returns its value or raises the exception which terminated the thread. -
#wakeup ⇒ Thread
Marks a given thread as eligible for scheduling, however it may still remain blocked on I/O.
Constructor Details
.new ⇒ Thread
.new(*args, &proc) ⇒ Thread
.new(*args) {|args| ... } ⇒ Thread
Thread
.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.
Class Attribute Details
.abort_on_exception ⇒ Boolean
(rw)
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.
.abort_on_exception=(boolean) ⇒ Boolean
(rw)
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=.
DEBUG ⇒ Numeric (rw)
Returns the thread debug level. Available only if compiled with THREAD_DEBUG=-1.
DEBUG=(num) (rw)
Sets the thread debug level. Available only if compiled with THREAD_DEBUG=-1.
Class Method Details
.current ⇒ Thread
Returns the currently executing thread.
Thread.current #=> #<Thread:0x401bdf4c run>
.exclusive ⇒ Object
Wraps the block in a single, VM-global 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
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.
.start([args]*) {|args| ... } ⇒ Thread
.fork([args]*) {|args| ... } ⇒ Thread
Also known as: .start
Thread
.fork([args]*) {|args| ... } ⇒ Thread
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.
.handle_interrupt(hash) ⇒ result
of
the
block
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.
}
.kill(thread) ⇒ Thread
.list ⇒ Array
Returns an array of Thread
objects for all threads that are either runnable or stopped.
Thread.new { sleep(200) }
Thread.new { 1000000.times {|i| i*i } }
Thread.new { Thread.stop }
Thread.list.each {|t| p t}
This will produce:
#<Thread:0x401b3e84 sleep>
#<Thread:0x401b3f38 run>
#<Thread:0x401b3fb0 sleep>
#<Thread:0x401bdf4c run>
.main ⇒ Thread
Returns the main thread.
.pass ⇒ nil
Give the thread scheduler a hint to pass execution to another thread. A running thread may or may not switch, it depends on OS and processor.
.pending_interrupt?(error = nil) ⇒ Boolean
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
.start([args]*) {|args| ... } ⇒ Thread
.fork([args]*) {|args| ... } ⇒ Thread
Thread
.fork([args]*) {|args| ... } ⇒ Thread
Alias for .fork.
.stop ⇒ nil
Instance Attribute Details
#abort_on_exception ⇒ Boolean
(rw)
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.
#abort_on_exception=(boolean) ⇒ Boolean
(rw)
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=.
#alive? ⇒ Boolean
(readonly)
#name ⇒ String (rw)
show the name of the thread.
#name=(name) ⇒ String (rw)
set given name to the ruby thread. On some platform, it may set the name to pthread and/or kernel.
#priority ⇒ Integer (rw)
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
#priority=(integer) ⇒ Thread
(rw)
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
#stop? ⇒ Boolean
(readonly)
Instance Method Details
#[](sym) ⇒ Object?
Attribute Reference—Returns the value of a fiber-local variable (current thread's root fiber if not explicitly inside a ::Fiber), using either a symbol or a string name. If the specified variable does not exist, returns nil
.
[
Thread.new { Thread.current["name"] = "A" },
Thread.new { Thread.current[:name] = "B" },
Thread.new { Thread.current["name"] = "C" }
].each do |th|
th.join
puts "#{th.inspect}: #{th[:name]}"
end
This will produce:
#<Thread:0x00000002a54220 dead>: A
#<Thread:0x00000002a541a8 dead>: B
#<Thread:0x00000002a54130 dead>: C
[]
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.
#[]=(sym, obj) ⇒ Object
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.
#add_trace_func(proc) ⇒ Proc
Adds proc as a handler for tracing.
See #set_trace_func and Kernel.set_trace_func.
#backtrace ⇒ Array
Returns the current backtrace of the target thread.
#backtrace_locations(*args) ⇒ Array?
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.
#exit ⇒ Thread
?
#kill ⇒ Thread
?
#terminate ⇒ Thread
?
Also known as: #kill, #terminate
Thread
?
#kill ⇒ Thread
?
#terminate ⇒ Thread
?
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.
#group ⇒ thgrp
?
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>
#inspect ⇒ String
Dump the name, id, and status of thr to a string.
#join ⇒ Thread
#join(limit) ⇒ Thread
Thread
#join(limit) ⇒ Thread
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...
#key?(sym) ⇒ Boolean
Returns true
if the given string (or symbol) exists as a fiber-local variable.
me = Thread.current
me[:oliver] = "a"
me.key?(:oliver) #=> true
me.key?(:stanley) #=> false
#keys ⇒ Array
#exit ⇒ Thread
?
#kill ⇒ Thread
?
#terminate ⇒ Thread
?
Thread
?
#kill ⇒ Thread
?
#terminate ⇒ Thread
?
Alias for #exit.
#pending_interrupt?(error = nil) ⇒ Boolean
Returns whether or not the asynchronous queue is empty for the target thread.
If error
is given, then check only for error
type deferred events.
See .pending_interrupt? for more information.
#raise
#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
#run ⇒ Thread
#safe_level ⇒ Integer
#set_trace_func(proc) ⇒ Proc
#set_trace_func(nil) ⇒ nil
nil
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"
-
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"
#exit ⇒ Thread
?
#kill ⇒ Thread
?
#terminate ⇒ Thread
?
Thread
?
#kill ⇒ Thread
?
#terminate ⇒ Thread
?
Alias for #exit.
#thread_variable?(key) ⇒ Boolean
Returns true
if the given string (or symbol) exists as a thread-local variable.
me = Thread.current
me.thread_variable_set(:oliver, "a")
me.thread_variable?(:oliver) #=> true
me.thread_variable?(:stanley) #=> false
Note that these are not fiber local variables. Please see #[] and #thread_variable_get for more details.
#thread_variable_get(key) ⇒ Object?
Returns the value of a thread local variable that has been set. Note that these are different than fiber local values. For fiber local values, please see #[] 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.
#thread_variable_set(key, value)
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.
#thread_variables ⇒ Array
Returns an array of the names of the thread-local variables (as Symbols).
thr = Thread.new do
Thread.current.thread_variable_set(:cat, 'meow')
Thread.current.thread_variable_set("dog", 'woof')
end
thr.join #=> #<Thread:0x401b3f10 dead>
thr.thread_variables #=> [:dog, :cat]
Note that these are not fiber local variables. Please see #[] and #thread_variable_get for more details.