Package java.util.concurrent.atomic

A small toolkit of classes that support lock-free thread-safe programming on single variables.

See:
Description

Class Summary

AtomicBoolean	An AtomicBoolean maintains a boolean value that is updated atomically.
AtomicInteger	An AtomicInteger maintains an int value that is updated atomically.
AtomicIntegerArray	An AtomicIntegerArray maintains a int array in which elements may be updated atomically, and are accessed using volatile semantics.
AtomicIntegerFieldUpdater<T>	An AtomicIntegerFieldUpdater is a reflection-based utility that enables atomic updates to designated integer fields of designated classes.
AtomicLong	An AtomicLong maintains a long value that is updated atomically.
AtomicLongArray	An AtomicLongArray maintains a long array in which elements may be updated atomically, and are accessed using volatile semantics.
AtomicLongFieldUpdater<T>	An AtomicLongFieldUpdater is a reflection-based utility that enables atomic updates to designated 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 AtomicReference maintains an object reference that is updated atomically.
AtomicReferenceArray<V>	An AtomicReferenceArray maintains an array of object references in which elements may be updated atomically, and are accessed using volatile semantics.
AtomicReferenceFieldUpdater<T,V>	An AtomicReferenceFieldUpdater is a reflection-based utility that enables atomic updates to designated reference fields of designated classes.
AtomicStampedReference<V>	An AtomicStampedReference maintains an object reference along with an integer "stamp", that can be updated atomically.

Package java.util.concurrent.atomic Description

A small toolkit of classes that support lock-free thread-safe programming on single variables. In essence, the classes in this package extend the notion of volatile values, fields, and array elements to those that also provide an atomic conditional update operation of the form:

  boolean compareAndSet(expectedValue, updateValue);

This method (which varies in argument types across different classes) atomically sets a variable to the updateValue if it currently holds the expectedValue, reporting true on success. The memory effects for accesses and updates of atomics follow the rules for volatiles, so an invocation of compareAndSet has the memory effects of a volatile read followed by a volatile write.

The classes in this package additionally support a weaker version of this operation:

  boolean weakCompareAndSet(expectedValue, updateValue);

The weak version may be more efficient in the normal case, but differs in that any given invocation of weakCompareAndSet method may fail, even spuriously (that is, for no apparent reason). A false return means only that the operation may be retried if desired, relying on the guarantee that repeated invocation when the variable holds expectedValue and no other thread is also attempting to set the variable will eventually succeed.

The specifications of these methods enable implementations to employ efficient machine-level atomic instructions that are available on contemporary processors. However on some platforms, support may entail some form of internal locking. Thus the methods are not strictly guaranteed to be non-blocking.

The classes and methods in this package provide a few related operations and capabilities to form a small toolkit of common constructions using atomics.

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 AtomicInt provide atomic increment methods. One application is to generate sequence numbers, as in:

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

In addition to classes representing single values, this package contains Updater classes that can be used to obtain compareAndSet operations on any selected volatile field of any selected class. 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 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, which is not otherwise supported for ordinary Java arrays.

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.

Atomics are not used very often in application-level classes. They are designed primarily as building blocks for implementing non-blocking data structures and related infrastructure classes. The compareAndSet method is not a general replacement for locking. It applies only when critical updates for an object are confined to a single variable. And atomic classes are not general purpose replacements for java.lang.Integer and related classes. They do NOT define methods such as hashCode and compareTo. (Because atomic variables are expected to be mutated, they are poor choices for hash table keys.) Additionally, classes are provided only for those types that are commonly useful as atomics. For example, there is no atomic class for representing byte. In those infrequent cases where you would like to do so, you can use an AtomicInteger to hold byte values, and cast appropriately. Similarly, you can hold floating point types using Float.floatToIntBits and Float.intBitstoFloat conversions.