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