ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/jdk8/java/util/concurrent/atomic/package-info.java
Revision: 1.1
Committed: Sat Mar 26 06:22:51 2016 UTC (8 years, 2 months ago) by jsr166
Branch: MAIN
CVS Tags: HEAD
Log Message: 
fork jdk8 maintenance branch for source and jtreg tests

File Contents

# Content
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;