1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/rt/emul/compact/src/main/java/java/util/concurrent/atomic/package-info.java Thu Oct 03 15:40:35 2013 +0200
1.3 @@ -0,0 +1,199 @@
1.4 +/*
1.5 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.6 + *
1.7 + * This code is free software; you can redistribute it and/or modify it
1.8 + * under the terms of the GNU General Public License version 2 only, as
1.9 + * published by the Free Software Foundation. Oracle designates this
1.10 + * particular file as subject to the "Classpath" exception as provided
1.11 + * by Oracle in the LICENSE file that accompanied this code.
1.12 + *
1.13 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.14 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.15 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.16 + * version 2 for more details (a copy is included in the LICENSE file that
1.17 + * accompanied this code).
1.18 + *
1.19 + * You should have received a copy of the GNU General Public License version
1.20 + * 2 along with this work; if not, write to the Free Software Foundation,
1.21 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.22 + *
1.23 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.24 + * or visit www.oracle.com if you need additional information or have any
1.25 + * questions.
1.26 + */
1.27 +
1.28 +/*
1.29 + * This file is available under and governed by the GNU General Public
1.30 + * License version 2 only, as published by the Free Software Foundation.
1.31 + * However, the following notice accompanied the original version of this
1.32 + * file:
1.33 + *
1.34 + * Written by Doug Lea with assistance from members of JCP JSR-166
1.35 + * Expert Group and released to the public domain, as explained at
1.36 + * http://creativecommons.org/publicdomain/zero/1.0/
1.37 + */
1.38 +
1.39 +/**
1.40 + * A small toolkit of classes that support lock-free thread-safe
1.41 + * programming on single variables. In essence, the classes in this
1.42 + * package extend the notion of {@code volatile} values, fields, and
1.43 + * array elements to those that also provide an atomic conditional update
1.44 + * operation of the form:
1.45 + *
1.46 + * <pre>
1.47 + * boolean compareAndSet(expectedValue, updateValue);
1.48 + * </pre>
1.49 + *
1.50 + * <p>This method (which varies in argument types across different
1.51 + * classes) atomically sets a variable to the {@code updateValue} if it
1.52 + * currently holds the {@code expectedValue}, reporting {@code true} on
1.53 + * success. The classes in this package also contain methods to get and
1.54 + * unconditionally set values, as well as a weaker conditional atomic
1.55 + * update operation {@code weakCompareAndSet} described below.
1.56 + *
1.57 + * <p>The specifications of these methods enable implementations to
1.58 + * employ efficient machine-level atomic instructions that are available
1.59 + * on contemporary processors. However on some platforms, support may
1.60 + * entail some form of internal locking. Thus the methods are not
1.61 + * strictly guaranteed to be non-blocking --
1.62 + * a thread may block transiently before performing the operation.
1.63 + *
1.64 + * <p>Instances of classes
1.65 + * {@link java.util.concurrent.atomic.AtomicBoolean},
1.66 + * {@link java.util.concurrent.atomic.AtomicInteger},
1.67 + * {@link java.util.concurrent.atomic.AtomicLong}, and
1.68 + * {@link java.util.concurrent.atomic.AtomicReference}
1.69 + * each provide access and updates to a single variable of the
1.70 + * corresponding type. Each class also provides appropriate utility
1.71 + * methods for that type. For example, classes {@code AtomicLong} and
1.72 + * {@code AtomicInteger} provide atomic increment methods. One
1.73 + * application is to generate sequence numbers, as in:
1.74 + *
1.75 + * <pre>
1.76 + * class Sequencer {
1.77 + * private final AtomicLong sequenceNumber
1.78 + * = new AtomicLong(0);
1.79 + * public long next() {
1.80 + * return sequenceNumber.getAndIncrement();
1.81 + * }
1.82 + * }
1.83 + * </pre>
1.84 + *
1.85 + * <p>The memory effects for accesses and updates of atomics generally
1.86 + * follow the rules for volatiles, as stated in section 17.4 of
1.87 + * <cite>The Java™ Language Specification</cite>.
1.88 + *
1.89 + * <ul>
1.90 + *
1.91 + * <li> {@code get} has the memory effects of reading a
1.92 + * {@code volatile} variable.
1.93 + *
1.94 + * <li> {@code set} has the memory effects of writing (assigning) a
1.95 + * {@code volatile} variable.
1.96 + *
1.97 + * <li> {@code lazySet} has the memory effects of writing (assigning)
1.98 + * a {@code volatile} variable except that it permits reorderings with
1.99 + * subsequent (but not previous) memory actions that do not themselves
1.100 + * impose reordering constraints with ordinary non-{@code volatile}
1.101 + * writes. Among other usage contexts, {@code lazySet} may apply when
1.102 + * nulling out, for the sake of garbage collection, a reference that is
1.103 + * never accessed again.
1.104 + *
1.105 + * <li>{@code weakCompareAndSet} atomically reads and conditionally
1.106 + * writes a variable but does <em>not</em>
1.107 + * create any happens-before orderings, so provides no guarantees
1.108 + * with respect to previous or subsequent reads and writes of any
1.109 + * variables other than the target of the {@code weakCompareAndSet}.
1.110 + *
1.111 + * <li> {@code compareAndSet}
1.112 + * and all other read-and-update operations such as {@code getAndIncrement}
1.113 + * have the memory effects of both reading and
1.114 + * writing {@code volatile} variables.
1.115 + * </ul>
1.116 + *
1.117 + * <p>In addition to classes representing single values, this package
1.118 + * contains <em>Updater</em> classes that can be used to obtain
1.119 + * {@code compareAndSet} operations on any selected {@code volatile}
1.120 + * field of any selected class.
1.121 + *
1.122 + * {@link java.util.concurrent.atomic.AtomicReferenceFieldUpdater},
1.123 + * {@link java.util.concurrent.atomic.AtomicIntegerFieldUpdater}, and
1.124 + * {@link java.util.concurrent.atomic.AtomicLongFieldUpdater} are
1.125 + * reflection-based utilities that provide access to the associated
1.126 + * field types. These are mainly of use in atomic data structures in
1.127 + * which several {@code volatile} fields of the same node (for
1.128 + * example, the links of a tree node) are independently subject to
1.129 + * atomic updates. These classes enable greater flexibility in how
1.130 + * and when to use atomic updates, at the expense of more awkward
1.131 + * reflection-based setup, less convenient usage, and weaker
1.132 + * guarantees.
1.133 + *
1.134 + * <p>The
1.135 + * {@link java.util.concurrent.atomic.AtomicIntegerArray},
1.136 + * {@link java.util.concurrent.atomic.AtomicLongArray}, and
1.137 + * {@link java.util.concurrent.atomic.AtomicReferenceArray} classes
1.138 + * further extend atomic operation support to arrays of these types.
1.139 + * These classes are also notable in providing {@code volatile} access
1.140 + * semantics for their array elements, which is not supported for
1.141 + * ordinary arrays.
1.142 + *
1.143 + * <a name="Spurious">
1.144 + * <p>The atomic classes also support method {@code weakCompareAndSet},
1.145 + * which has limited applicability. On some platforms, the weak version
1.146 + * may be more efficient than {@code compareAndSet} in the normal case,
1.147 + * but differs in that any given invocation of the
1.148 + * {@code weakCompareAndSet} method may return {@code false}
1.149 + * <em>spuriously</em> (that is, for no apparent reason)</a>. A
1.150 + * {@code false} return means only that the operation may be retried if
1.151 + * desired, relying on the guarantee that repeated invocation when the
1.152 + * variable holds {@code expectedValue} and no other thread is also
1.153 + * attempting to set the variable will eventually succeed. (Such
1.154 + * spurious failures may for example be due to memory contention effects
1.155 + * that are unrelated to whether the expected and current values are
1.156 + * equal.) Additionally {@code weakCompareAndSet} does not provide
1.157 + * ordering guarantees that are usually needed for synchronization
1.158 + * control. However, the method may be useful for updating counters and
1.159 + * statistics when such updates are unrelated to the other
1.160 + * happens-before orderings of a program. When a thread sees an update
1.161 + * to an atomic variable caused by a {@code weakCompareAndSet}, it does
1.162 + * not necessarily see updates to any <em>other</em> variables that
1.163 + * occurred before the {@code weakCompareAndSet}. This may be
1.164 + * acceptable when, for example, updating performance statistics, but
1.165 + * rarely otherwise.
1.166 + *
1.167 + * <p>The {@link java.util.concurrent.atomic.AtomicMarkableReference}
1.168 + * class associates a single boolean with a reference. For example, this
1.169 + * bit might be used inside a data structure to mean that the object
1.170 + * being referenced has logically been deleted.
1.171 + *
1.172 + * The {@link java.util.concurrent.atomic.AtomicStampedReference}
1.173 + * class associates an integer value with a reference. This may be
1.174 + * used for example, to represent version numbers corresponding to
1.175 + * series of updates.
1.176 + *
1.177 + * <p>Atomic classes are designed primarily as building blocks for
1.178 + * implementing non-blocking data structures and related infrastructure
1.179 + * classes. The {@code compareAndSet} method is not a general
1.180 + * replacement for locking. It applies only when critical updates for an
1.181 + * object are confined to a <em>single</em> variable.
1.182 + *
1.183 + * <p>Atomic classes are not general purpose replacements for
1.184 + * {@code java.lang.Integer} and related classes. They do <em>not</em>
1.185 + * define methods such as {@code hashCode} and
1.186 + * {@code compareTo}. (Because atomic variables are expected to be
1.187 + * mutated, they are poor choices for hash table keys.) Additionally,
1.188 + * classes are provided only for those types that are commonly useful in
1.189 + * intended applications. For example, there is no atomic class for
1.190 + * representing {@code byte}. In those infrequent cases where you would
1.191 + * like to do so, you can use an {@code AtomicInteger} to hold
1.192 + * {@code byte} values, and cast appropriately.
1.193 + *
1.194 + * You can also hold floats using
1.195 + * {@link java.lang.Float#floatToIntBits} and
1.196 + * {@link java.lang.Float#intBitsToFloat} conversions, and doubles using
1.197 + * {@link java.lang.Double#doubleToLongBits} and
1.198 + * {@link java.lang.Double#longBitsToDouble} conversions.
1.199 + *
1.200 + * @since 1.5
1.201 + */
1.202 +package java.util.concurrent.atomic;