2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 * This code is free software; you can redistribute it and/or modify it
5 * under the terms of the GNU General Public License version 2 only, as
6 * published by the Free Software Foundation. Oracle designates this
7 * particular file as subject to the "Classpath" exception as provided
8 * by Oracle in the LICENSE file that accompanied this code.
10 * This code is distributed in the hope that it will be useful, but WITHOUT
11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * version 2 for more details (a copy is included in the LICENSE file that
14 * accompanied this code).
16 * You should have received a copy of the GNU General Public License version
17 * 2 along with this work; if not, write to the Free Software Foundation,
18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
21 * or visit www.oracle.com if you need additional information or have any
26 * This file is available under and governed by the GNU General Public
27 * License version 2 only, as published by the Free Software Foundation.
28 * However, the following notice accompanied the original version of this
31 * Written by Doug Lea with assistance from members of JCP JSR-166
32 * Expert Group and released to the public domain, as explained at
33 * http://creativecommons.org/publicdomain/zero/1.0/
37 * A small toolkit of classes that support lock-free thread-safe
38 * programming on single variables. In essence, the classes in this
39 * package extend the notion of {@code volatile} values, fields, and
40 * array elements to those that also provide an atomic conditional update
41 * operation of the form:
44 * boolean compareAndSet(expectedValue, updateValue);
47 * <p>This method (which varies in argument types across different
48 * classes) atomically sets a variable to the {@code updateValue} if it
49 * currently holds the {@code expectedValue}, reporting {@code true} on
50 * success. The classes in this package also contain methods to get and
51 * unconditionally set values, as well as a weaker conditional atomic
52 * update operation {@code weakCompareAndSet} described below.
54 * <p>The specifications of these methods enable implementations to
55 * employ efficient machine-level atomic instructions that are available
56 * on contemporary processors. However on some platforms, support may
57 * entail some form of internal locking. Thus the methods are not
58 * strictly guaranteed to be non-blocking --
59 * a thread may block transiently before performing the operation.
61 * <p>Instances of classes
62 * {@link java.util.concurrent.atomic.AtomicBoolean},
63 * {@link java.util.concurrent.atomic.AtomicInteger},
64 * {@link java.util.concurrent.atomic.AtomicLong}, and
65 * {@link java.util.concurrent.atomic.AtomicReference}
66 * each provide access and updates to a single variable of the
67 * corresponding type. Each class also provides appropriate utility
68 * methods for that type. For example, classes {@code AtomicLong} and
69 * {@code AtomicInteger} provide atomic increment methods. One
70 * application is to generate sequence numbers, as in:
74 * private final AtomicLong sequenceNumber
75 * = new AtomicLong(0);
76 * public long next() {
77 * return sequenceNumber.getAndIncrement();
82 * <p>The memory effects for accesses and updates of atomics generally
83 * follow the rules for volatiles, as stated in section 17.4 of
84 * <cite>The Java™ Language Specification</cite>.
88 * <li> {@code get} has the memory effects of reading a
89 * {@code volatile} variable.
91 * <li> {@code set} has the memory effects of writing (assigning) a
92 * {@code volatile} variable.
94 * <li> {@code lazySet} has the memory effects of writing (assigning)
95 * a {@code volatile} variable except that it permits reorderings with
96 * subsequent (but not previous) memory actions that do not themselves
97 * impose reordering constraints with ordinary non-{@code volatile}
98 * writes. Among other usage contexts, {@code lazySet} may apply when
99 * nulling out, for the sake of garbage collection, a reference that is
100 * never accessed again.
102 * <li>{@code weakCompareAndSet} atomically reads and conditionally
103 * writes a variable but does <em>not</em>
104 * create any happens-before orderings, so provides no guarantees
105 * with respect to previous or subsequent reads and writes of any
106 * variables other than the target of the {@code weakCompareAndSet}.
108 * <li> {@code compareAndSet}
109 * and all other read-and-update operations such as {@code getAndIncrement}
110 * have the memory effects of both reading and
111 * writing {@code volatile} variables.
114 * <p>In addition to classes representing single values, this package
115 * contains <em>Updater</em> classes that can be used to obtain
116 * {@code compareAndSet} operations on any selected {@code volatile}
117 * field of any selected class.
119 * {@link java.util.concurrent.atomic.AtomicReferenceFieldUpdater},
120 * {@link java.util.concurrent.atomic.AtomicIntegerFieldUpdater}, and
121 * {@link java.util.concurrent.atomic.AtomicLongFieldUpdater} are
122 * reflection-based utilities that provide access to the associated
123 * field types. These are mainly of use in atomic data structures in
124 * which several {@code volatile} fields of the same node (for
125 * example, the links of a tree node) are independently subject to
126 * atomic updates. These classes enable greater flexibility in how
127 * and when to use atomic updates, at the expense of more awkward
128 * reflection-based setup, less convenient usage, and weaker
132 * {@link java.util.concurrent.atomic.AtomicIntegerArray},
133 * {@link java.util.concurrent.atomic.AtomicLongArray}, and
134 * {@link java.util.concurrent.atomic.AtomicReferenceArray} classes
135 * further extend atomic operation support to arrays of these types.
136 * These classes are also notable in providing {@code volatile} access
137 * semantics for their array elements, which is not supported for
140 * <a name="Spurious">
141 * <p>The atomic classes also support method {@code weakCompareAndSet},
142 * which has limited applicability. On some platforms, the weak version
143 * may be more efficient than {@code compareAndSet} in the normal case,
144 * but differs in that any given invocation of the
145 * {@code weakCompareAndSet} method may return {@code false}
146 * <em>spuriously</em> (that is, for no apparent reason)</a>. A
147 * {@code false} return means only that the operation may be retried if
148 * desired, relying on the guarantee that repeated invocation when the
149 * variable holds {@code expectedValue} and no other thread is also
150 * attempting to set the variable will eventually succeed. (Such
151 * spurious failures may for example be due to memory contention effects
152 * that are unrelated to whether the expected and current values are
153 * equal.) Additionally {@code weakCompareAndSet} does not provide
154 * ordering guarantees that are usually needed for synchronization
155 * control. However, the method may be useful for updating counters and
156 * statistics when such updates are unrelated to the other
157 * happens-before orderings of a program. When a thread sees an update
158 * to an atomic variable caused by a {@code weakCompareAndSet}, it does
159 * not necessarily see updates to any <em>other</em> variables that
160 * occurred before the {@code weakCompareAndSet}. This may be
161 * acceptable when, for example, updating performance statistics, but
164 * <p>The {@link java.util.concurrent.atomic.AtomicMarkableReference}
165 * class associates a single boolean with a reference. For example, this
166 * bit might be used inside a data structure to mean that the object
167 * being referenced has logically been deleted.
169 * The {@link java.util.concurrent.atomic.AtomicStampedReference}
170 * class associates an integer value with a reference. This may be
171 * used for example, to represent version numbers corresponding to
174 * <p>Atomic classes are designed primarily as building blocks for
175 * implementing non-blocking data structures and related infrastructure
176 * classes. The {@code compareAndSet} method is not a general
177 * replacement for locking. It applies only when critical updates for an
178 * object are confined to a <em>single</em> variable.
180 * <p>Atomic classes are not general purpose replacements for
181 * {@code java.lang.Integer} and related classes. They do <em>not</em>
182 * define methods such as {@code hashCode} and
183 * {@code compareTo}. (Because atomic variables are expected to be
184 * mutated, they are poor choices for hash table keys.) Additionally,
185 * classes are provided only for those types that are commonly useful in
186 * intended applications. For example, there is no atomic class for
187 * representing {@code byte}. In those infrequent cases where you would
188 * like to do so, you can use an {@code AtomicInteger} to hold
189 * {@code byte} values, and cast appropriately.
191 * You can also hold floats using
192 * {@link java.lang.Float#floatToIntBits} and
193 * {@link java.lang.Float#intBitsToFloat} conversions, and doubles using
194 * {@link java.lang.Double#doubleToLongBits} and
195 * {@link java.lang.Double#longBitsToDouble} conversions.
199 package java.util.concurrent.atomic;