Module java.base

# Package java.util.concurrent.atomic

package java.util.concurrent.atomic
A small toolkit of classes that support lock-free thread-safe programming on single variables. Instances of Atomic classes maintain values that are accessed and updated using methods otherwise available for fields using associated atomic `VarHandle` operations.

Instances of classes `AtomicBoolean`, `AtomicInteger`, `AtomicLong`, and `AtomicReference` each provide access and updates to a single variable of the corresponding type. Each class also provides appropriate utility methods for that type. For example, classes `AtomicLong` and `AtomicInteger` provide atomic increment methods. One application is to generate sequence numbers, as in:

     class Sequencer {
       private final AtomicLong sequenceNumber
         = new AtomicLong(17);
       public long next() {
         return sequenceNumber.getAndIncrement();
       }
     }

Arbitrary transformations of the contained value are provided both by low-level read-modify-write operations such as `compareAndSet` and by higher-level methods such as `getAndUpdate`.

These classes are not general purpose replacements for `java.lang.Integer` and related classes. They do not define methods such as `equals`, `hashCode` and `compareTo`. Because atomic variables are expected to be mutated, they are poor choices for hash table keys.

The `AtomicIntegerArray`, `AtomicLongArray`, and `AtomicReferenceArray` classes further extend atomic operation support to arrays of these types. These classes are also notable in providing `volatile` access semantics for their array elements.

In addition to classes representing single values and arrays, this package contains Updater classes that can be used to obtain `compareAndSet` and related operations on any selected `volatile` field of any selected class. These classes predate the introduction of `VarHandle`, and are of more limited use. `AtomicReferenceFieldUpdater`, `AtomicIntegerFieldUpdater`, and `AtomicLongFieldUpdater` are reflection-based utilities that provide access to the associated field types. These are mainly of use in atomic data structures in which several `volatile` fields of the same node (for example, the links of a tree node) are independently subject to atomic updates. These classes enable greater flexibility in how and when to use atomic updates, at the expense of more awkward reflection-based setup, less convenient usage, and weaker guarantees.

The `AtomicMarkableReference` class associates a single boolean with a reference. For example, this bit might be used inside a data structure to mean that the object being referenced has logically been deleted. The `AtomicStampedReference` class associates an integer value with a reference. This may be used for example, to represent version numbers corresponding to series of updates.

Since:
  1.5

Related Packages
Package
Description
java.util.concurrent
Utility classes commonly useful in concurrent programming.
java.util.concurrent.locks
Interfaces and classes providing a framework for locking and waiting for conditions that is distinct from built-in synchronization and monitors.
Classes
Class
Description
AtomicBoolean
A `boolean` value that may be updated atomically.
AtomicInteger
An `int` value that may be updated atomically.
AtomicIntegerArray
An `int` array in which elements may be updated atomically.
AtomicIntegerFieldUpdater<T>
A reflection-based utility that enables atomic updates to designated `volatile int` fields of designated classes.
AtomicLong
A `long` value that may be updated atomically.
AtomicLongArray
A `long` array in which elements may be updated atomically.
AtomicLongFieldUpdater<T>
A reflection-based utility that enables atomic updates to designated `volatile long` fields of designated classes.
AtomicMarkableReference<V>
An `AtomicMarkableReference` maintains an object reference along with a mark bit, that can be updated atomically.
AtomicReference<V>
An object reference that may be updated atomically.
AtomicReferenceArray<E>
An array of object references in which elements may be updated atomically.
AtomicReferenceFieldUpdater<T,V>
A reflection-based utility that enables atomic updates to designated `volatile` reference fields of designated classes.
AtomicStampedReference<V>
An `AtomicStampedReference` maintains an object reference along with an integer "stamp", that can be updated atomically.
DoubleAccumulator
One or more variables that together maintain a running `double` value updated using a supplied function.
DoubleAdder
One or more variables that together maintain an initially zero `double` sum.
LongAccumulator
One or more variables that together maintain a running `long` value updated using a supplied function.
LongAdder
One or more variables that together maintain an initially zero `long` sum.