Package java.util.concurrent.atomic Description

A small toolkit of classes that support lock-free thread-safe programming on single variables. In essence, theInstances of Atomic classes in this package extend the notion of volatilemaintain values , fields, and array elements to thosethat 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 classes in this package also contain methods to getare accessed and unconditionally set values, as well as a weaker conditional atomic update operation weakCompareAndSet described below.The specifications of theseupdated using methods enable implementations to employ efficient machine-levelotherwise available for fields using associated 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 VarHandle operations.

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 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();
   }
 }Itisstraightforwardtodefinenewutilityfunctionsthat,likegetAndIncrement,applyafunctiontoa

Arbitrary transformations of the contained value atomically. For example, given some transformation

  long transform(long input)

are provided both by low-level read-modify-write your utility methodoperations such as follows:longgetAndTransform(AtomicLongvar){longprev,next;do{prev=var.get();next=transform(prev);}while(!var.compareAndSet(prev,next));returnprev;//returnnext;fortransformAndGet} The memory effects for accessesand updates of atomics generally follow the rules for volatiles,by higher-level methods such as stated in The Java Language Specification (17.4 Memory Model) :

get has the memory effects of reading a volatile variable.

set has the memory effects of writing (assigning) a volatile variable.

lazySet has the memory effects of writing (assigning) a volatile variable except that it permits reorderings with subsequent (but getAndUpdate.

These classes are not previous) memory actions that do not themselves impose reordering constraints with ordinary non-volatile writes. Among other usage contexts, lazySet may apply when nulling out,general purpose replacements for the sake of garbage collection, a reference that is never accessed again.weakCompareAndSet atomically reads java.lang.Integer and conditionally writes a variable but doesrelated classes. They do not create any happens-before orderings, so provides no guarantees with respect to previous or subsequent reads define methods such as equals, hashCode and writes of any compareTo . Because atomic variables other than the target of the weakCompareAndSet.compareAndSetare expected to be mutated, they are poor choices for hash table keys.

The AtomicIntegerArray, AtomicLongArray, and all other read-and-update operations such as getAndIncrement have the memory effects AtomicReferenceArray classes further extend atomic operation support to arrays of both reading and writingthese types. These classes are also notable in providing volatile variablesaccess 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 VarHandle, and are of more limited use. 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 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 falsespuriously (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. (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 weakCompareAndSet does not provide orderingguarantees 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 weakCompareAndSet, it does not necessarily see updates to any other variables that occurred before the weakCompareAndSet. This may be acceptable when, for example, updating performance statistics, but rarely otherwise.

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.Atomic