1 files changed, 158 insertions, 0 deletions
diff --git a/external/jsr166/java/util/concurrent/atomic/package.html b/external/jsr166/java/util/concurrent/atomic/package.html
new file mode 100644
index 000000000..6bc191ddf
--- /dev/null
+++ b/external/jsr166/java/util/concurrent/atomic/package.html
@@ -0,0 +1,158 @@
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html> <head>
+<title>Atomics</title>
+</head>
+
+<body>
+
+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 <tt>volatile</tt> values, fields, and
+array elements to those that also provide an atomic conditional update
+operation of the form:
+
+<pre>
+  boolean compareAndSet(expectedValue, updateValue);
+</pre>
+
+<p> This method (which varies in argument types across different
+classes) atomically sets a variable to the <tt>updateValue</tt> if it
+currently holds the <tt>expectedValue</tt>, reporting <tt>true</tt> 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 <tt>weakCompareAndSet</tt> desribed below.
+
+<p> 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.
+
+<p> 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 <tt>AtomicLong</tt> and <tt>AtomicInteger</tt> provide atomic
+increment methods.  One application is to generate sequence numbers,
+as in:
+
+<pre>
+class Sequencer {
+  private AtomicLong sequenceNumber = new AtomicLong(0);
+  public long next() { return sequenceNumber.getAndIncrement(); }
+}
+</pre>
+
+<p>The memory effects for accesses and updates of atomics generally
+follow the rules for volatiles, as stated in <a
+href="http://java.sun.com/docs/books/jls/"> The Java Language
+Specification, Third Edition (17.4 Memory Model)</a>:
+
+<ul>
+
+  <li> <tt>get</tt> has the memory effects of reading a
+<tt>volatile</tt> variable.
+
+  <li> <tt>set</tt> has the memory effects of writing (assigning) a
+<tt>volatile</tt> variable.
+
+  <li> <tt>lazySet</tt> has the memory effects of writing (assigning)
+  a <tt>volatile</tt> variable except that it permits reorderings with
+  subsequent (but not previous) memory actions that do not themselves
+  impose reordering constraints with ordinary non-<tt>volatile</tt>
+  writes.  Among other usage contexts, <tt>lazySet</tt> may apply when
+  nulling out, for the sake of garbage collection, a reference that is
+  never accessed again.
+
+  <li><tt>weakCompareAndSet</tt> atomically reads and conditionally
+  writes a variable but does <em>not</em>
+  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 <tt>weakCompareAndSet</tt>.
+
+  <li> <tt>compareAndSet</tt>
+  and all other read-and-update operations such as <tt>getAndIncrement</tt>
+  have the memory effects of both reading and
+  writing <tt>volatile</tt> variables.
+</ul>
+
+<p>In addition to classes representing single values, this package
+contains <em>Updater</em> classes that can be used to obtain
+<tt>compareAndSet</tt> operations on any selected <tt>volatile</tt>
+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 <tt>volatile</tt> 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.
+
+<p>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 <tt>volatile</tt> access
+semantics for their array elements, which is not supported for
+ordinary arrays.
+
+<p>The atomic classes also support method <tt>weakCompareAndSet</tt>,
+which has limited applicability. On some platforms, the weak version
+may be more efficient than <tt>compareAndSet</tt> in the normal case,
+but differs in that any given invocation of <tt>weakCompareAndSet</tt>
+method may return <tt>false</tt> spuriously (that is, for no apparent
+reason). A <tt>false</tt> return means only that the operation may be
+retried if desired, relying on the guarantee that repeated invocation
+when the variable holds <tt>expectedValue</tt> 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 <tt>weakCompareAndSet</tt> 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 <tt>weakCompareAndSet</tt>, it does not
+necessarily see updates to any <em>other</em> variables that occurred
+before the <tt>weakCompareAndSet</tt>.  This may be acceptable when
+for example updating performance statistics, but rarely otherwise.
+
+<p> 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.
+
+<p> Atomic classes are designed primarily as building blocks for
+implementing non-blocking data structures and related infrastructure
+classes.  The <tt>compareAndSet</tt> method is not a general
+replacement for locking. It applies only when critical updates for an
+object are confined to a <em>single</em> variable.
+
+<p> Atomic classes are not general purpose replacements for
+<tt>java.lang.Integer</tt> and related classes. They do <em>not</em>
+define methods such as <tt>hashCode</tt> and
+<tt>compareTo</tt>. (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 <tt>byte</tt>. In those infrequent cases where you would
+like to do so, you can use an <tt>AtomicInteger</tt> to hold
+<tt>byte</tt> values, and cast appropriately. You can also hold floats
+using <tt>Float.floatToIntBits</tt> and <tt>Float.intBitstoFloat</tt>
+conversions, and doubles using <tt>Double.doubleToLongBits</tt> and
+<tt>Double.longBitsToDouble</tt> conversions.
+
+
+@since 1.5
+
+</body> </html>