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