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