Class: Concurrent::ThreadLocalVar — Concurrent Ruby

# Class: Concurrent::ThreadLocalVar

Inherits:
  ThreadLocalVarImplementation
  - Object
  - Concurrent::ThreadLocalVar
  show all

Defined in:
  lib/concurrent/atomic/thread_local_var.rb

## Overview

A `ThreadLocalVar` is a variable where the value is different for each thread. Each variable may have a default value, but when you modify the variable only the current thread will ever see that change.

## Thread-safe Variable Classes

Each of the thread-safe variable classes is designed to solve a different problem. In general:

- Agent: Shared, mutable variable providing independent, uncoordinated, asynchronous change of individual values. Best used when the value will undergo frequent, complex updates. Suitable when the result of an update does not need to be known immediately.
- Atom: Shared, mutable variable providing independent, uncoordinated, synchronous change of individual values. Best used when the value will undergo frequent reads but only occasional, though complex, updates. Suitable when the result of an update must be known immediately.
- AtomicReference: A simple object reference that can be atomically. Updates are synchronous but fast. Best used when updates a simple set operations. Not suitable when updates are complex. AtomicBoolean and AtomicFixnum are similar but optimized for the given data type.
- Exchanger: Shared, stateless synchronization point. Used when two or more threads need to exchange data. The threads will pair then block on each other until the exchange is complete.
- MVar: Shared synchronization point. Used when one thread must give a value to another, which must take the value. The threads will block on each other until the exchange is complete.
- ThreadLocalVar: Shared, mutable, isolated variable which holds a different value for each thread which has access. Often used as an instance variable in objects which must maintain different state for different threads.
- TVar: Shared, mutable variables which provide coordinated, synchronous, change of many stated. Used when multiple value must change together, in an all-or-nothing transaction.

Examples:

    v = ThreadLocalVar.new(14)
    v.value #=> 14
    v.value = 2
    v.value #=> 2

    v = ThreadLocalVar.new(14)

    t1 = Thread.new do
      v.value #=> 14
      v.value = 1
      v.value #=> 1
    end

    t2 = Thread.new do
      v.value #=> 14
      v.value = 2
      v.value #=> 2
    end

    v.value #=> 14

See Also:

- Java ThreadLocal

## Instance Method Summary collapse

- #bind(value) { ... } ⇒ Object

  Bind the given value to thread local storage during execution of the given block.

- #initialize(default = nil, &default_block) ⇒ undocumented constructor

  Creates a thread local variable.

- #value ⇒ Object

  Returns the value in the current thread's copy of this thread-local variable.

- #value=(value) ⇒ Object

  Sets the current thread's copy of this thread-local variable to the specified value.

## Constructor Details

### #initialize(default = nil, &default_block) ⇒ `undocumented`

Creates a thread local variable.

Parameters:

- default (`Object`) (defaults to: `nil`) —

  the default value when otherwise unset

- default_block (`Proc`) —

  Optional block that gets called to obtain the default value for each thread

    102
    103
    # File 'lib/concurrent/atomic/thread_local_var.rb', line 102

    class ThreadLocalVar < ThreadLocalVarImplementation
    end

## Instance Method Details

### #bind(value) { ... } ⇒ `Object`

Bind the given value to thread local storage during execution of the given block.

Parameters:

- value (`Object`) —

  the value to bind

Yields:

- the operation to be performed with the bound variable

Returns:

- (`Object`) —

  the value

    102
    103
    # File 'lib/concurrent/atomic/thread_local_var.rb', line 102

    class ThreadLocalVar < ThreadLocalVarImplementation
    end

### #value ⇒ `Object`

Returns the value in the current thread's copy of this thread-local variable.

Returns:

- (`Object`) —

  the current value

    102
    103
    # File 'lib/concurrent/atomic/thread_local_var.rb', line 102

    class ThreadLocalVar < ThreadLocalVarImplementation
    end

### #value=(value) ⇒ `Object`

Sets the current thread's copy of this thread-local variable to the specified value.

Parameters:

- value (`Object`) —

  the value to set

Returns:

- (`Object`) —

  the new value

    102
    103
    # File 'lib/concurrent/atomic/thread_local_var.rb', line 102

    class ThreadLocalVar < ThreadLocalVarImplementation
    end