libjava/classpath/external/jsr166/java/util/concurrent/atomic/package.html

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
   2 <html> <head>
   3 <title>Atomics</title>
   4 </head>
   5
   6 <body>
   7
   8 A small toolkit of classes that support lock-free thread-safe
   9 programming on single variables. In essence, the classes in this
  10 package extend the notion of <tt>volatile</tt> values, fields, and
  11 array elements to those that also provide an atomic conditional update
  12 operation of the form:
  13
  14 <pre>
  15   boolean compareAndSet(expectedValue, updateValue);
  16 </pre>
  17
  18 <p> This method (which varies in argument types across different
  19 classes) atomically sets a variable to the <tt>updateValue</tt> if it
  20 currently holds the <tt>expectedValue</tt>, reporting <tt>true</tt> on
  21 success.  The classes in this package also contain methods to get and
  22 unconditionally set values, as well as a weaker conditional atomic
  23 update operation <tt>weakCompareAndSet</tt> desribed below.
  24
  25 <p> The specifications of these methods enable implementations to
  26 employ efficient machine-level atomic instructions that are available
  27 on contemporary processors. However on some platforms, support may
  28 entail some form of internal locking. Thus the methods are not
  29 strictly guaranteed to be non-blocking --
  30 a thread may block transiently before performing the operation.
  31
  32 <p> Instances of classes {@link
  33 java.util.concurrent.atomic.AtomicBoolean}, {@link
  34 java.util.concurrent.atomic.AtomicInteger}, {@link
  35 java.util.concurrent.atomic.AtomicLong}, and {@link
  36 java.util.concurrent.atomic.AtomicReference} each provide access and
  37 updates to a single variable of the corresponding type.  Each class
  38 also provides appropriate utility methods for that type.  For example,
  39 classes <tt>AtomicLong</tt> and <tt>AtomicInteger</tt> provide atomic
  40 increment methods.  One application is to generate sequence numbers,
  41 as in:
  42
  43 <pre>
  44 class Sequencer {
  45   private AtomicLong sequenceNumber = new AtomicLong(0);
  46   public long next() { return sequenceNumber.getAndIncrement(); }
  47 }
  48 </pre>
  49
  50 <p>The memory effects for accesses and updates of atomics generally
  51 follow the rules for volatiles, as stated in <a
  52 href="http://java.sun.com/docs/books/jls/"> The Java Language
  53 Specification, Third Edition (17.4 Memory Model)</a>:
  54
  55 <ul>
  56
  57   <li> <tt>get</tt> has the memory effects of reading a
  58 <tt>volatile</tt> variable.
  59
  60   <li> <tt>set</tt> has the memory effects of writing (assigning) a
  61 <tt>volatile</tt> variable.
  62
  63   <li> <tt>lazySet</tt> has the memory effects of writing (assigning)
  64   a <tt>volatile</tt> variable except that it permits reorderings with
  65   subsequent (but not previous) memory actions that do not themselves
  66   impose reordering constraints with ordinary non-<tt>volatile</tt>
  67   writes.  Among other usage contexts, <tt>lazySet</tt> may apply when
  68   nulling out, for the sake of garbage collection, a reference that is
  69   never accessed again.
  70
  71   <li><tt>weakCompareAndSet</tt> atomically reads and conditionally
  72   writes a variable but does <em>not</em>
  73   create any happens-before orderings, so provides no guarantees
  74   with respect to previous or subsequent reads and writes of any
  75   variables other than the target of the <tt>weakCompareAndSet</tt>.
  76
  77   <li> <tt>compareAndSet</tt>
  78   and all other read-and-update operations such as <tt>getAndIncrement</tt>
  79   have the memory effects of both reading and
  80   writing <tt>volatile</tt> variables.
  81 </ul>
  82
  83 <p>In addition to classes representing single values, this package
  84 contains <em>Updater</em> classes that can be used to obtain
  85 <tt>compareAndSet</tt> operations on any selected <tt>volatile</tt>
  86 field of any selected class.  {@link
  87 java.util.concurrent.atomic.AtomicReferenceFieldUpdater}, {@link
  88 java.util.concurrent.atomic.AtomicIntegerFieldUpdater}, and {@link
  89 java.util.concurrent.atomic.AtomicLongFieldUpdater} are
  90 reflection-based utilities that provide access to the associated field
  91 types. These are mainly of use in atomic data structures in which
  92 several <tt>volatile</tt> fields of the same node (for example, the
  93 links of a tree node) are independently subject to atomic
  94 updates. These classes enable greater flexibility in how and when to
  95 use atomic updates, at the expense of more awkward reflection-based
  96 setup, less convenient usage, and weaker guarantees.
  97
  98 <p>The {@link java.util.concurrent.atomic.AtomicIntegerArray}, {@link
  99 java.util.concurrent.atomic.AtomicLongArray}, and {@link
 100 java.util.concurrent.atomic.AtomicReferenceArray} classes further
 101 extend atomic operation support to arrays of these types. These
 102 classes are also notable in providing <tt>volatile</tt> access
 103 semantics for their array elements, which is not supported for
 104 ordinary arrays.
 105
 106 <p>The atomic classes also support method <tt>weakCompareAndSet</tt>,
 107 which has limited applicability. On some platforms, the weak version
 108 may be more efficient than <tt>compareAndSet</tt> in the normal case,
 109 but differs in that any given invocation of <tt>weakCompareAndSet</tt>
 110 method may return <tt>false</tt> spuriously (that is, for no apparent
 111 reason). A <tt>false</tt> return means only that the operation may be
 112 retried if desired, relying on the guarantee that repeated invocation
 113 when the variable holds <tt>expectedValue</tt> and no other thread is
 114 also attempting to set the variable will eventually succeed.  (Such
 115 spurious failures may for example be due to memory contention effects
 116 that are unrelated to whether the expected and current values are
 117 equal.)  Additionally <tt>weakCompareAndSet</tt> does not provide
 118 ordering guarantees that are usually needed for synchronization
 119 control.  However, the method may be useful for updating counters and
 120 statistics when such updates are unrelated to the other happens-before
 121 orderings of a program. When a thread sees an update to an atomic
 122 variable caused by a <tt>weakCompareAndSet</tt>, it does not
 123 necessarily see updates to any <em>other</em> variables that occurred
 124 before the <tt>weakCompareAndSet</tt>.  This may be acceptable when
 125 for example updating performance statistics, but rarely otherwise.
 126
 127 <p> The {@link java.util.concurrent.atomic.AtomicMarkableReference}
 128 class associates a single boolean with a reference. For example, this
 129 bit might be used inside a data structure to mean that the object
 130 being referenced has logically been deleted. The {@link
 131 java.util.concurrent.atomic.AtomicStampedReference} class associates
 132 an integer value with a reference. This may be used for example, to
 133 represent version numbers corresponding to series of updates.
 134
 135 <p> Atomic classes are designed primarily as building blocks for
 136 implementing non-blocking data structures and related infrastructure
 137 classes.  The <tt>compareAndSet</tt> method is not a general
 138 replacement for locking. It applies only when critical updates for an
 139 object are confined to a <em>single</em> variable.
 140
 141 <p> Atomic classes are not general purpose replacements for
 142 <tt>java.lang.Integer</tt> and related classes. They do <em>not</em>
 143 define methods such as <tt>hashCode</tt> and
 144 <tt>compareTo</tt>. (Because atomic variables are expected to be
 145 mutated, they are poor choices for hash table keys.)  Additionally,
 146 classes are provided only for those types that are commonly useful in
 147 intended applications. For example, there is no atomic class for
 148 representing <tt>byte</tt>. In those infrequent cases where you would
 149 like to do so, you can use an <tt>AtomicInteger</tt> to hold
 150 <tt>byte</tt> values, and cast appropriately. You can also hold floats
 151 using <tt>Float.floatToIntBits</tt> and <tt>Float.intBitstoFloat</tt>
 152 conversions, and doubles using <tt>Double.doubleToLongBits</tt> and
 153 <tt>Double.longBitsToDouble</tt> conversions.
 154
 155
 156 @since 1.5
 157
 158 </body> </html>