java.util.concurrent.atomic.package-info Maven / Gradle / Ivy
/*
* Written by Doug Lea with assistance from members of JCP JSR-166
* Expert Group and released to the public domain, as explained at
* http://creativecommons.org/publicdomain/zero/1.0/
*/
/**
* 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 {@code volatile} values, fields, and
* array elements to those that also provide an atomic conditional update
* operation of the form:
*
* {@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
* long getAndTransform(AtomicLong var) {
* while (true) {
* long current = var.get();
* long next = transform(current);
* if (var.compareAndSet(current, next))
* return current;
* // return next; for transformAndGet
* }
* }}
*
* The memory effects for accesses and updates of atomics generally
* follow the rules for volatiles, as stated in
*
* The Java Language Specification (17.4 Memory Model):
*
*
*
* - {@code get} has the memory effects of reading a
* {@code volatile} variable.
*
*
- {@code set} has the memory effects of writing (assigning) a
* {@code volatile} variable.
*
*
- {@code lazySet} has the memory effects of writing (assigning)
* a {@code volatile} variable except that it permits reorderings with
* subsequent (but not previous) memory actions that do not themselves
* impose reordering constraints with ordinary non-{@code volatile}
* writes. Among other usage contexts, {@code lazySet} may apply when
* nulling out, for the sake of garbage collection, a reference that is
* never accessed again.
*
*
- {@code weakCompareAndSet} atomically reads and conditionally
* writes a variable but does not
* create any happens-before orderings, so provides no guarantees
* with respect to previous or subsequent reads and writes of any
* variables other than the target of the {@code weakCompareAndSet}.
*
*
- {@code compareAndSet}
* and all other read-and-update operations such as {@code getAndIncrement}
* have the memory effects of both reading and
* writing {@code volatile} variables.
*
*
* 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). A
* {@code false} return means only that the operation may be retried if
* desired, relying on the guarantee that repeated invocation when the
* variable holds {@code expectedValue} and no other thread is also
* attempting to set the variable will eventually succeed. (Such
* spurious failures may for example be due to memory contention effects
* that are unrelated to whether the expected and current values are
* equal.) Additionally {@code weakCompareAndSet} does not provide
* ordering guarantees that are usually needed for synchronization
* control. However, the method may be useful for updating counters and
* statistics when such updates are unrelated to the other
* happens-before orderings of a program. When a thread sees an update
* to an atomic variable caused by a {@code weakCompareAndSet}, it does
* not necessarily see updates to any other variables that
* occurred before the {@code weakCompareAndSet}. This may be
* acceptable when, for example, updating performance statistics, but
* rarely otherwise.
*
*
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 equals}, {@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;