{@code boolean compareAndSet(expectedValue, updateValue);}
*
* This method (which varies in argument types across different * classes) atomically sets a variable to the {@code updateValue} if it * currently holds the {@code expectedValue}, reporting {@code 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 {@code 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 java.util.concurrent.atomic.AtomicBoolean}, * {@link java.util.concurrent.atomic.AtomicInteger}, * {@link java.util.concurrent.atomic.AtomicLong}, and * {@link 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 {@code AtomicLong} and * {@code AtomicInteger} provide atomic increment methods. One * application is to generate sequence numbers, as in: * *
{@code
* class Sequencer {
* private final AtomicLong sequenceNumber
* = new AtomicLong(0);
* public long next() {
* return sequenceNumber.getAndIncrement();
* }
* }}
*
* It is straightforward to define new utility functions that, like * {@code getAndIncrement}, apply a function to a value atomically. * For example, given some transformation *
{@code long transform(long input)}
*
* write your utility method as follows:
* {@code
* boolean getAndTransform(AtomicLong var) {
* while (true) {
* long current = var.get();
* long next = transform(current);
* if (var.compareAndSet(current, next))
* return current;
* }
* }}
*
* 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 * {@code compareAndSet} operations on any selected {@code volatile} * field of any selected class. * * {@link java.util.concurrent.atomic.AtomicReferenceFieldUpdater}, * {@link java.util.concurrent.atomic.AtomicIntegerFieldUpdater}, and * {@link 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 {@code 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 java.util.concurrent.atomic.AtomicIntegerArray},
* {@link java.util.concurrent.atomic.AtomicLongArray}, and
* {@link java.util.concurrent.atomic.AtomicReferenceArray} classes
* further extend atomic operation support to arrays of these types.
* These classes are also notable in providing {@code volatile} access
* semantics for their array elements, which is not supported for
* ordinary arrays.
*
*
* The atomic classes also support method {@code weakCompareAndSet},
* which has limited applicability. On some platforms, the weak version
* may be more efficient than {@code compareAndSet} in the normal case,
* but differs in that any given invocation of the
* {@code weakCompareAndSet} method may return {@code false}
* spuriously (that is, for no apparent reason)
The {@link 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 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 {@code 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 * {@code java.lang.Integer} and related classes. They do not * define methods such as {@code hashCode} and * {@code 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 {@code byte}. In those infrequent cases where you would * like to do so, you can use an {@code AtomicInteger} to hold * {@code byte} values, and cast appropriately. * * You can also hold floats using * {@link java.lang.Float#floatToRawIntBits} and * {@link java.lang.Float#intBitsToFloat} conversions, and doubles using * {@link java.lang.Double#doubleToRawLongBits} and * {@link java.lang.Double#longBitsToDouble} conversions. * * @since 1.5 */ package java.util.concurrent.atomic;