# Class: Concurrent::AtomicReference

Inherits:
  AtomicReferenceImplementation
  - Object
  - Concurrent::AtomicReference
  show all

Defined in:
  lib/concurrent-ruby/concurrent/atomic/atomic_reference.rb

## Overview

An object reference that may be updated atomically. All read and write operations have java volatile semantic.

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

See Also:

- http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/atomic/AtomicReference.html
- http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/atomic/package-summary.html

## Instance Method Summary collapse

- #compare_and_set(old_value, new_value) ⇒ Boolean

  Atomically sets the value to the given updated value if the current value == the expected value.

- #get ⇒ Object

  Gets the current value.

- #get_and_set(new_value) ⇒ Object

  Atomically sets to the given value and returns the old value.

- #initialize(value = nil) ⇒ undocumented constructor
- #set(new_value) ⇒ Object

  Sets to the given value.

- #to_s ⇒ String (also: #inspect)

  Short string representation.

- #try_update {|Object| ... } ⇒ Object

  Pass the current value to the given block, replacing it with the block's result.

- #try_update! {|Object| ... } ⇒ Object

  Pass the current value to the given block, replacing it with the block's result.

- #update {|Object| ... } ⇒ Object

  Pass the current value to the given block, replacing it with the block's result.

## Constructor Details

### #initialize(value = nil) ⇒ `undocumented`

Parameters:

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

  The initial value.

    196
    197
    198
    199
    200
    201
    202
    203
    204

    # File 'lib/concurrent-ruby/concurrent/atomic/atomic_reference.rb', line 196

    class AtomicReference < AtomicReferenceImplementation

      # @return [String] Short string representation.
      def to_s
        format '%s value:%s>', super[0..-2], get
      end

      alias_method :inspect, :to_s
    end

## Instance Method Details

### #compare_and_set(old_value, new_value) ⇒ `Boolean`

Atomically sets the value to the given updated value if the current value == the expected value.

that the actual value was not equal to the expected value.

Parameters:

- old_value (`Object`) —

  the expected value

- new_value (`Object`) —

  the new value

Returns:

- (`Boolean`) —

  `true` if successful. A `false` return indicates

    196
    197
    198
    199
    200
    201
    202
    203
    204

    # File 'lib/concurrent-ruby/concurrent/atomic/atomic_reference.rb', line 196

    class AtomicReference < AtomicReferenceImplementation

      # @return [String] Short string representation.
      def to_s
        format '%s value:%s>', super[0..-2], get
      end

      alias_method :inspect, :to_s
    end

### #get ⇒ `Object`

Gets the current value.

Returns:

- (`Object`) —

  the current value

    196
    197
    198
    199
    200
    201
    202
    203
    204

    # File 'lib/concurrent-ruby/concurrent/atomic/atomic_reference.rb', line 196

    class AtomicReference < AtomicReferenceImplementation

      # @return [String] Short string representation.
      def to_s
        format '%s value:%s>', super[0..-2], get
      end

      alias_method :inspect, :to_s
    end

### #get_and_set(new_value) ⇒ `Object`

Atomically sets to the given value and returns the old value.

Parameters:

- new_value (`Object`) —

  the new value

Returns:

- (`Object`) —

  the old value

    196
    197
    198
    199
    200
    201
    202
    203
    204

    # File 'lib/concurrent-ruby/concurrent/atomic/atomic_reference.rb', line 196

    class AtomicReference < AtomicReferenceImplementation

      # @return [String] Short string representation.
      def to_s
        format '%s value:%s>', super[0..-2], get
      end

      alias_method :inspect, :to_s
    end

### #set(new_value) ⇒ `Object`

Sets to the given value.

Parameters:

- new_value (`Object`) —

  the new value

Returns:

- (`Object`) —

  the new value

    196
    197
    198
    199
    200
    201
    202
    203
    204

    # File 'lib/concurrent-ruby/concurrent/atomic/atomic_reference.rb', line 196

    class AtomicReference < AtomicReferenceImplementation

      # @return [String] Short string representation.
      def to_s
        format '%s value:%s>', super[0..-2], get
      end

      alias_method :inspect, :to_s
    end

### #to_s ⇒ `String` Also known as: inspect

Returns Short string representation.

Returns:

- (`String`) —

  Short string representation.

    199
    200
    201

    # File 'lib/concurrent-ruby/concurrent/atomic/atomic_reference.rb', line 199

    def to_s
      format '%s value:%s>', super[0..-2], get
    end

### #try_update {|Object| ... } ⇒ `Object`

Note:

This method was altered to avoid raising an exception by default. Instead, this method now returns `nil` in case of failure. For more info, please see: https://github.com/ruby-concurrency/concurrent-ruby/pull/336

Pass the current value to the given block, replacing it with the block's result. Return nil if the update fails.

Yields:

- (`Object`) —

  Calculate a new value for the atomic reference using given (old) value

Yield Parameters:

- old_value (`Object`) —

  the starting value of the atomic reference

Returns:

- (`Object`) —

  the new value, or nil if update failed

    196
    197
    198
    199
    200
    201
    202
    203
    204

    # File 'lib/concurrent-ruby/concurrent/atomic/atomic_reference.rb', line 196

    class AtomicReference < AtomicReferenceImplementation

      # @return [String] Short string representation.
      def to_s
        format '%s value:%s>', super[0..-2], get
      end

      alias_method :inspect, :to_s
    end

### #try_update! {|Object| ... } ⇒ `Object`

Note:

This behavior mimics the behavior of the original `AtomicReference#try_update` API. The reason this was changed was to avoid raising exceptions (which are inherently slow) by default. For more info: https://github.com/ruby-concurrency/concurrent-ruby/pull/336

Pass the current value to the given block, replacing it with the block's result. Raise an exception if the update fails.

Yields:

- (`Object`) —

  Calculate a new value for the atomic reference using given (old) value

Yield Parameters:

- old_value (`Object`) —

  the starting value of the atomic reference

Returns:

- (`Object`) —

  the new value

Raises:

- (`Concurrent::ConcurrentUpdateError`) —

  if the update fails

    196
    197
    198
    199
    200
    201
    202
    203
    204

    # File 'lib/concurrent-ruby/concurrent/atomic/atomic_reference.rb', line 196

    class AtomicReference < AtomicReferenceImplementation

      # @return [String] Short string representation.
      def to_s
        format '%s value:%s>', super[0..-2], get
      end

      alias_method :inspect, :to_s
    end

### #update {|Object| ... } ⇒ `Object`

Pass the current value to the given block, replacing it with the block's result. May retry if the value changes during the block's execution.

Yields:

- (`Object`) —

  Calculate a new value for the atomic reference using given (old) value

Yield Parameters:

- old_value (`Object`) —

  the starting value of the atomic reference

Returns:

- (`Object`) —

  the new value

    196
    197
    198
    199
    200
    201
    202
    203
    204

    # File 'lib/concurrent-ruby/concurrent/atomic/atomic_reference.rb', line 196

    class AtomicReference < AtomicReferenceImplementation

      # @return [String] Short string representation.
      def to_s
        format '%s value:%s>', super[0..-2], get
      end

      alias_method :inspect, :to_s
    end