Package java.util.concurrent.atomic

See:
           Description

Package java.util.concurrent.atomic Description

A small toolkit of classes that support lock-free thread-safeprogramming on single variables. In essence, the classes in thispackage extend the notion of volatile values, fields, andarray elements to those that also provide an atomic conditional updateoperation of the form:

  boolean compareAndSet(expectedValue, updateValue);

This method (which varies in argument types across differentclasses) atomically sets a variable to the updateValue if itcurrently holds the expectedValue , reporting true onsuccess. The classes in this package also contain methods to get andunconditionally set values, as well as a weaker conditional atomicupdate operation operation:

 
 boolean weakCompareAndSet(expectedValue, updateValue);
 

weakCompareAndSet

The specifications of these methods enable implementations toemploy efficient machine-level atomic instructions that are availableon contemporary processors. However on some platforms, support mayentail some form of internal locking. Thus the methods are notstrictly guaranteed to be non-blocking --a thread may block transiently before performing the operation. non-blocking.

The classes and methods in this package provide a few relatedoperations and capabilities to form a small toolkit of commonconstructions using atomics.

Instances of classes AtomicBoolean , AtomicInteger , AtomicLong , and AtomicReference each provide access andupdates and updates to a single variable of variableof the corresponding type. Each classalso class also provides appropriate utility appropriateutility methods for that type. For example,classes example, classes AtomicLong and AtomicInteger AtomicInt provide atomicincrement atomic increment methods. One application is applicationis to generate sequence numbers,as numbers, as in:

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

The memory effects for accesses and updates of atomics generally follow therules atomicsfollow the rules for volatiles:

• get has the memory effects of reading a volatile variable.
• set has the memory effects of writing (assigning) a volatile variable.
• weakCompareAndSet atomically reads and conditionally writes a variable, is ordered with respect to other memory operations on that variable, but otherwise acts as an ordinary non-volatile memory operation.
• compareAndSet and all other read-and-update operations such as , getAndIncrement weakCompareAndSet ,and other read-and-update operations have the memory effects of both reading and writing andwriting volatile variables.

In addition to classes representing single values, this packagecontains Updater classes that can be used to obtain compareAndSet operations on any selected volatile field of any selected class. AtomicReferenceFieldUpdater , AtomicIntegerFieldUpdater , and AtomicLongFieldUpdater arereflection-based are reflection-based utilities that provide thatprovide access to the associated fieldtypes. field types. These are mainly of use in usein atomic data structures in whichseveral which several volatile fields of the ofthe same node (for example, thelinks the links of a tree node) are independently areindependently subject to atomicupdates. atomic updates. These classes enable greater flexibility greaterflexibility in how and when touse to use atomic updates, at the expense of more ofmore awkward reflection-basedsetup, reflection-based setup, less convenient usage, and weaker guarantees. weakerguarantees.

The AtomicIntegerArray , AtomicLongArray , and AtomicReferenceArray classes furtherextend further extend atomic operation support operationsupport to arrays of these types. Theseclasses These classes are also notable in providing inproviding volatile accesssemantics access semantics for their array elements, which elements,which is not supported forordinary for ordinary arrays.

The AtomicMarkableReference class associates a single boolean singleboolean with a reference. For example, thisbit this bit might be used inside a data adata structure to mean that the objectbeing object being referenced has logically been logicallybeen deleted. The AtomicStampedReference class associatesan integer associates aninteger value with a reference. This may be used for example, torepresent version numbers corresponding to series of updates.

Atomic classes Atomics are not used very often in application-level classes.They are designed primarily as building blocks forimplementing non-blocking for implementingnon-blocking data structures and related infrastructureclasses. infrastructure classes. The compareAndSet method is not a generalreplacement for locking. general replacement forlocking. It applies only when critical updates for anobject are confined an object areconfined to a single variable.

Atomic And atomic classes are not general notgeneral purpose replacements for java.lang.Integer and related andrelated classes. They do notdefine NOT define methods such as hashCode and compareTo . (Because atomic variables are variablesare expected to bemutated, be mutated, they are poor choices for hash table keys.) Additionally,classes tablekeys.) Additionally, classes are provided only for those types that are thatare commonly useful inintended applications. as atomics. For example, there is no atomic class forrepresenting classfor representing byte . In those infrequent cases where you wouldlike youwould like to do so, you can use an AtomicInteger to hold byte values, and cast appropriately. You can also hold floatsusing Similarly, you can holdfloating point types using Float.floatToIntBits and Float.intBitstoFloat conversions, and doubles using Double.doubleToLongBits and Double.longBitsToDouble conversions.

Since:

1.5