Class: Concurrent::AtomicFixnum — Concurrent Ruby

# Class: Concurrent::AtomicFixnum

Inherits:
  AtomicFixnumImplementation
  - Object
  - Concurrent::AtomicFixnum
  show all

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

## Overview

A numeric value that can be updated atomically. Reads and writes to an atomic fixnum and thread-safe and guaranteed to succeed. Reads and writes may block briefly but no explicit locking is required.

## 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. Performance:

    Testing with ruby 2.1.2
    Testing with Concurrent::MutexAtomicFixnum...
      3.130000   0.000000   3.130000 (  3.136505)
    Testing with Concurrent::CAtomicFixnum...
      0.790000   0.000000   0.790000 (  0.785550)

    Testing with jruby 1.9.3
    Testing with Concurrent::MutexAtomicFixnum...
      5.460000   2.460000   7.920000 (  3.715000)
    Testing with Concurrent::JavaAtomicFixnum...
      4.520000   0.030000   4.550000 (  1.187000)

See Also:

- java.util.concurrent.atomic.AtomicLong

## Instance Method Summary collapse

- #compare_and_set(expect, update) ⇒ Boolean

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

- #decrement(delta = 1) ⇒ Fixnum

  Decreases the current value by the given amount (defaults to 1).

- #increment(delta = 1) ⇒ Fixnum

  Increases the current value by the given amount (defaults to 1).

- #initialize(initial = 0) ⇒ undocumented constructor

  Creates a new `AtomicFixnum` with the given initial value.

- #to_s ⇒ String (also: #inspect)

  Short string representation.

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

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

- #value ⇒ Fixnum

  Retrieves the current `Fixnum` value.

- #value=(value) ⇒ Fixnum

  Explicitly sets the value.

## Constructor Details

### #initialize(initial = 0) ⇒ `undocumented`

Creates a new `AtomicFixnum` with the given initial value.

Parameters:

- initial (`Fixnum`) (defaults to: `0`) —

  the initial value

Raises:

- (`ArgumentError`) —

  if the initial value is not a `Fixnum`

    135
    136
    137
    138
    139
    140
    141
    142
    # File 'lib/concurrent/atomic/atomic_fixnum.rb', line 135

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

      alias_method :inspect, :to_s
    end

## Instance Method Details

### #compare_and_set(expect, update) ⇒ `Boolean`

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

Parameters:

- expect (`Fixnum`) —

  the expected value

- update (`Fixnum`) —

  the new value

Returns:

- (`Boolean`) —

  true if the value was updated else false

    135
    136
    137
    138
    139
    140
    141
    142
    # File 'lib/concurrent/atomic/atomic_fixnum.rb', line 135

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

      alias_method :inspect, :to_s
    end

### #decrement(delta = 1) ⇒ `Fixnum`

Decreases the current value by the given amount (defaults to 1).

Parameters:

- delta (`Fixnum`) (defaults to: `1`) —

  the amount by which to decrease the current value

Returns:

- (`Fixnum`) —

  the current value after decrementation

    135
    136
    137
    138
    139
    140
    141
    142
    # File 'lib/concurrent/atomic/atomic_fixnum.rb', line 135

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

      alias_method :inspect, :to_s
    end

### #increment(delta = 1) ⇒ `Fixnum`

Increases the current value by the given amount (defaults to 1).

Parameters:

- delta (`Fixnum`) (defaults to: `1`) —

  the amount by which to increase the current value

Returns:

- (`Fixnum`) —

  the current value after incrementation

    135
    136
    137
    138
    139
    140
    141
    142
    # File 'lib/concurrent/atomic/atomic_fixnum.rb', line 135

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

      alias_method :inspect, :to_s
    end

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

Returns Short string representation.

Returns:

- (`String`) —

  Short string representation.

    137
    138
    139
    # File 'lib/concurrent/atomic/atomic_fixnum.rb', line 137

    def to_s
      format '%s value:%s>', super[0..-2], value
    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

    135
    136
    137
    138
    139
    140
    141
    142
    # File 'lib/concurrent/atomic/atomic_fixnum.rb', line 135

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

      alias_method :inspect, :to_s
    end

### #value ⇒ `Fixnum`

Retrieves the current `Fixnum` value.

Returns:

- (`Fixnum`) —

  the current value

    135
    136
    137
    138
    139
    140
    141
    142
    # File 'lib/concurrent/atomic/atomic_fixnum.rb', line 135

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

      alias_method :inspect, :to_s
    end

### #value=(value) ⇒ `Fixnum`

Explicitly sets the value.

Parameters:

- value (`Fixnum`) —

  the new value to be set

Returns:

- (`Fixnum`) —

  the current value

Raises:

- (`ArgumentError`) —

  if the new value is not a `Fixnum`

    135
    136
    137
    138
    139
    140
    141
    142
    # File 'lib/concurrent/atomic/atomic_fixnum.rb', line 135

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

      alias_method :inspect, :to_s
    end