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 classes in this package also contain methods to get and unconditionally set values, as well as a weaker conditional atomic update operation weakCompareAndSet described below.
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 -- a thread may block transiently before performing the operation.
Instances of classes {@link edu.emory.mathcs.backport.java.util.concurrent.atomic.AtomicBoolean}, {@link edu.emory.mathcs.backport.java.util.concurrent.atomic.AtomicInteger}, {@link edu.emory.mathcs.backport.java.util.concurrent.atomic.AtomicLong}, and {@link edu.emory.mathcs.backport.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(0); public long next() { return sequenceNumber.getAndIncrement(); } }
The memory effects for accesses and updates of atomics generally follow the rules for volatiles, as stated in The Java Language Specification, Third Edition (17.4 Memory Model):
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. {@link edu.emory.mathcs.backport.java.util.concurrent.atomic.AtomicReferenceFieldUpdater}, {@link edu.emory.mathcs.backport.java.util.concurrent.atomic.AtomicIntegerFieldUpdater}, and {@link edu.emory.mathcs.backport.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 {@link edu.emory.mathcs.backport.java.util.concurrent.atomic.AtomicIntegerArray}, {@link
edu.emory.mathcs.backport.java.util.concurrent.atomic.AtomicLongArray}, and {@link
edu.emory.mathcs.backport.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, which is not supported for
ordinary arrays.
The atomic classes also support method weakCompareAndSet,
which has limited applicability. On some platforms, the weak version
may be more efficient than compareAndSet in the normal case,
but differs in that any given invocation of the
weakCompareAndSet method may return false
spuriously (that is, for no apparent reason)
The {@link edu.emory.mathcs.backport.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 {@link edu.emory.mathcs.backport.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.
Atomic classes 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.
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 in intended applications. 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. You can also hold floats using Float.floatToIntBits and Float.intBitstoFloat conversions, and doubles using Double.doubleToLongBits and Double.longBitsToDouble conversions. @since 1.5