Package java.util.concurrent.atomic

See:
           Description

Class Summary
AtomicBoolean	A boolean value that may be updated atomically.
AtomicInteger	An int value that may be updated atomically.
AtomicIntegerArray	An int array in which elements may be updated atomically.
AtomicIntegerFieldUpdater<T>	A reflection-based utility that enables atomic updates to designated volatile int fields of designated classes.
AtomicLong	A long value that may be updated atomically.
AtomicLongArray	A long array in which elements may be updated atomically.
AtomicLongFieldUpdater<T>	A reflection-based utility that enables atomic updates to designated volatile long fields of designated classes.
AtomicMarkableReference<V>	An AtomicMarkableReference maintains an object reference along with a mark bit, that can be updated atomically.
AtomicReference<V>	An object reference that may be updated atomically.
AtomicReferenceArray<E>	An array of object references in which elements may be updated atomically.
AtomicReferenceFieldUpdater<T,V>	A reflection-based utility that enables atomic updates to designated volatile reference fields of designated classes.
AtomicStampedReference<V>	An AtomicStampedReference maintains an object reference along with an integer "stamp", that can be updated atomically.

 

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 weakCompareAndSet . The weak version may bemore efficient in the normal case, but differs in that any giveninvocation of weakCompareAndSet method may fail, evenspuriously (that is, for no apparent reason). A false returnmeans only that the operation may be retried if desired, relying onthe guarantee that repeated invocation when the variable holds expectedValue and no other thread is also attempting to setthe variable will eventually succeed.

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.

Instances of classes AtomicBoolean , AtomicInteger , AtomicLong , and AtomicReference each provide access andupdates to a single variable of the corresponding type. Each classalso provides appropriate utility methods for that type. For example,classes AtomicLong and AtomicInteger provide atomicincrement methods. One application is to generate sequence 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 generallyfollow the rules for volatiles, as stated in The Java LanguageSpecification, Third Edition (17.4 Memory Model) : The memory effects for accesses and updates of atomics generally follow therules for volatiles:

• 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 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, for the sake of garbage collection, a reference that is never accessed again.
• 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 have the memory effects of both reading and writing 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 utilities that provide access to the associated fieldtypes. These are mainly of use in atomic data structures in whichseveral volatile fields of the same node (for example, thelinks of a tree node) are independently subject to atomicupdates. These classes enable greater flexibility in how and when touse atomic updates, at the expense of more awkward reflection-basedsetup, less convenient usage, and weaker guarantees.

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

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

Atomic classes are designed primarily as building blocks forimplementing non-blocking data structures and related infrastructureclasses. The compareAndSet method is not a generalreplacement for locking. It applies only when critical updates for anobject are confined to a single variable.

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

Since:

1.5