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™ 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