OpenJDK 1.23 · java.util.concurrent.atomic · APIdia, the JavaDoc alternative

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 java.lang.invoke.VarHandle operations.

Instances of classes java.util.concurrent.atomic.AtomicBoolean, java.util.concurrent.atomic.AtomicInteger, java.util.concurrent.atomic.AtomicLong, and java.util.concurrent.atomic.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 java.util.concurrent.atomic.AtomicIntegerArray, java.util.concurrent.atomic.AtomicLongArray, and java.util.concurrent.atomic.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 java.lang.invoke.VarHandle, and are of more limited use. java.util.concurrent.atomic.AtomicReferenceFieldUpdater, java.util.concurrent.atomic.AtomicIntegerFieldUpdater, and java.util.concurrent.atomic.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 java.util.concurrent.atomic.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 java.util.concurrent.atomic.AtomicStampedReference class associates an integer value with a reference. This may be used for example, to represent version numbers corresponding to series of updates.

Class Summary

Modifier and Type	Class and Description
public class	AtomicBoolean A `boolean` value that may be updated atomically.
public class	AtomicInteger An `int` value that may be updated atomically.
public class	AtomicIntegerArray An `int` array in which elements may be updated atomically.
public abstract class	AtomicIntegerFieldUpdater< The type of the object holding the updatable field T> A reflection-based utility that enables atomic updates to designated `volatile int` fields of designated classes.
public class	AtomicLong A `long` value that may be updated atomically.
public class	AtomicLongArray A `long` array in which elements may be updated atomically.
public abstract class	AtomicLongFieldUpdater< The type of the object holding the updatable field T> A reflection-based utility that enables atomic updates to designated `volatile long` fields of designated classes.
public class	AtomicMarkableReference< The type of object referred to by this reference V> An `AtomicMarkableReference` maintains an object reference along with a mark bit, that can be updated atomically.
public class	AtomicReference< The type of object referred to by this reference V> An object reference that may be updated atomically.
public class	AtomicReferenceArray< The base class of elements held in this array E> An array of object references in which elements may be updated atomically.
public abstract class	AtomicReferenceFieldUpdater< The type of the object holding the updatable field T, The type of the field V> A reflection-based utility that enables atomic updates to designated `volatile` reference fields of designated classes.
public class	AtomicStampedReference< The type of object referred to by this reference V> An `AtomicStampedReference` maintains an object reference along with an integer "stamp", that can be updated atomically.
public class	DoubleAccumulator One or more variables that together maintain a running `double` value updated using a supplied function.
public class	DoubleAdder One or more variables that together maintain an initially zero `double` sum.
public class	LongAccumulator One or more variables that together maintain a running `long` value updated using a supplied function.
public class	LongAdder One or more variables that together maintain an initially zero `long` sum.
pack-priv abstract class	Striped64 A package-local class holding common representation and mechanics for classes supporting dynamic striping on 64bit values.

Package java.util.concurrent.atomic

Class Summary