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/licenses/publicdomain
7 package java.util.concurrent.atomic;
8 import sun.misc.Unsafe;
9 import java.lang.reflect.*;
12 * A reflection-based utility that enables atomic updates to
13 * designated <tt>volatile</tt> reference fields of designated
14 * classes. This class is designed for use in atomic data structures
15 * in which several reference fields of the same node are
16 * independently subject to atomic updates. For example, a tree node
17 * might be declared as
21 * private volatile Node left, right;
23 * private static final AtomicReferenceFieldUpdater<Node, Node> leftUpdater =
24 * AtomicReferenceFieldUpdater.newUpdater(Node.class, Node.class, "left");
25 * private static AtomicReferenceFieldUpdater<Node, Node> rightUpdater =
26 * AtomicReferenceFieldUpdater.newUpdater(Node.class, Node.class, "right");
28 * Node getLeft() { return left; }
29 * boolean compareAndSetLeft(Node expect, Node update) {
30 * return leftUpdater.compareAndSet(this, expect, update);
36 * <p>Note that the guarantees of the {@code compareAndSet}
37 * method in this class are weaker than in other atomic classes.
38 * Because this class cannot ensure that all uses of the field
39 * are appropriate for purposes of atomic access, it can
40 * guarantee atomicity only with respect to other invocations of
41 * {@code compareAndSet} and {@code set} on the same updater.
45 * @param <T> The type of the object holding the updatable field
46 * @param <V> The type of the field
48 public abstract class AtomicReferenceFieldUpdater<T, V> {
51 * Creates and returns an updater for objects with the given field.
52 * The Class arguments are needed to check that reflective types and
53 * generic types match.
55 * @param tclass the class of the objects holding the field.
56 * @param vclass the class of the field
57 * @param fieldName the name of the field to be updated.
59 * @throws IllegalArgumentException if the field is not a volatile reference type.
60 * @throws RuntimeException with a nested reflection-based
61 * exception if the class does not hold field or is the wrong type.
63 public static <U, W> AtomicReferenceFieldUpdater<U,W> newUpdater(Class<U> tclass, Class<W> vclass, String fieldName) {
64 return new AtomicReferenceFieldUpdaterImpl<U,W>(tclass,
70 * Protected do-nothing constructor for use by subclasses.
72 protected AtomicReferenceFieldUpdater() {
76 * Atomically sets the field of the given object managed by this updater
77 * to the given updated value if the current value <tt>==</tt> the
78 * expected value. This method is guaranteed to be atomic with respect to
79 * other calls to <tt>compareAndSet</tt> and <tt>set</tt>, but not
80 * necessarily with respect to other changes in the field.
82 * @param obj An object whose field to conditionally set
83 * @param expect the expected value
84 * @param update the new value
85 * @return true if successful.
87 public abstract boolean compareAndSet(T obj, V expect, V update);
90 * Atomically sets the field of the given object managed by this updater
91 * to the given updated value if the current value <tt>==</tt> the
92 * expected value. This method is guaranteed to be atomic with respect to
93 * other calls to <tt>compareAndSet</tt> and <tt>set</tt>, but not
94 * necessarily with respect to other changes in the field.
95 * May fail spuriously and does not provide ordering guarantees,
96 * so is only rarely an appropriate alternative to <tt>compareAndSet</tt>.
98 * @param obj An object whose field to conditionally set
99 * @param expect the expected value
100 * @param update the new value
101 * @return true if successful.
103 public abstract boolean weakCompareAndSet(T obj, V expect, V update);
106 * Sets the field of the given object managed by this updater to the
107 * given updated value. This operation is guaranteed to act as a volatile
108 * store with respect to subsequent invocations of
109 * <tt>compareAndSet</tt>.
111 * @param obj An object whose field to set
112 * @param newValue the new value
114 public abstract void set(T obj, V newValue);
117 * Eventually sets the field of the given object managed by this
118 * updater to the given updated value.
120 * @param obj An object whose field to set
121 * @param newValue the new value
124 public abstract void lazySet(T obj, V newValue);
127 * Gets the current value held in the field of the given object managed
130 * @param obj An object whose field to get
131 * @return the current value
133 public abstract V get(T obj);
136 * Atomically sets the field of the given object managed by this updater
137 * to the given value and returns the old value.
139 * @param obj An object whose field to get and set
140 * @param newValue the new value
141 * @return the previous value
143 public V getAndSet(T obj, V newValue) {
145 V current = get(obj);
146 if (compareAndSet(obj, current, newValue))
151 private static final class AtomicReferenceFieldUpdaterImpl<T,V>
152 extends AtomicReferenceFieldUpdater<T,V> {
153 private static final Unsafe unsafe = Unsafe.getUnsafe();
154 private final long offset;
155 private final Class<T> tclass;
156 private final Class<V> vclass;
157 private final Class cclass;
160 * Internal type checks within all update methods contain
161 * internal inlined optimizations checking for the common
162 * cases where the class is final (in which case a simple
163 * getClass comparison suffices) or is of type Object (in
164 * which case no check is needed because all objects are
165 * instances of Object). The Object case is handled simply by
166 * setting vclass to null in constructor. The targetCheck and
167 * updateCheck methods are invoked when these faster
171 AtomicReferenceFieldUpdaterImpl(Class<T> tclass,
175 Class fieldClass = null;
179 field = tclass.getDeclaredField(fieldName);
180 caller = sun.reflect.Reflection.getCallerClass(3);
181 modifiers = field.getModifiers();
182 sun.reflect.misc.ReflectUtil.ensureMemberAccess(
183 caller, tclass, null, modifiers);
184 sun.reflect.misc.ReflectUtil.checkPackageAccess(tclass);
185 fieldClass = field.getType();
186 } catch (Exception ex) {
187 throw new RuntimeException(ex);
190 if (vclass != fieldClass)
191 throw new ClassCastException();
193 if (!Modifier.isVolatile(modifiers))
194 throw new IllegalArgumentException("Must be volatile type");
196 this.cclass = (Modifier.isProtected(modifiers) &&
197 caller != tclass) ? caller : null;
198 this.tclass = tclass;
199 if (vclass == Object.class)
202 this.vclass = vclass;
203 offset = unsafe.objectFieldOffset(field);
206 void targetCheck(T obj) {
207 if (!tclass.isInstance(obj))
208 throw new ClassCastException();
210 ensureProtectedAccess(obj);
213 void updateCheck(T obj, V update) {
214 if (!tclass.isInstance(obj) ||
215 (update != null && vclass != null && !vclass.isInstance(update)))
216 throw new ClassCastException();
218 ensureProtectedAccess(obj);
221 public boolean compareAndSet(T obj, V expect, V update) {
222 if (obj == null || obj.getClass() != tclass || cclass != null ||
223 (update != null && vclass != null &&
224 vclass != update.getClass()))
225 updateCheck(obj, update);
226 return unsafe.compareAndSwapObject(obj, offset, expect, update);
229 public boolean weakCompareAndSet(T obj, V expect, V update) {
230 // same implementation as strong form for now
231 if (obj == null || obj.getClass() != tclass || cclass != null ||
232 (update != null && vclass != null &&
233 vclass != update.getClass()))
234 updateCheck(obj, update);
235 return unsafe.compareAndSwapObject(obj, offset, expect, update);
238 public void set(T obj, V newValue) {
239 if (obj == null || obj.getClass() != tclass || cclass != null ||
240 (newValue != null && vclass != null &&
241 vclass != newValue.getClass()))
242 updateCheck(obj, newValue);
243 unsafe.putObjectVolatile(obj, offset, newValue);
246 public void lazySet(T obj, V newValue) {
247 if (obj == null || obj.getClass() != tclass || cclass != null ||
248 (newValue != null && vclass != null &&
249 vclass != newValue.getClass()))
250 updateCheck(obj, newValue);
251 unsafe.putOrderedObject(obj, offset, newValue);
254 public V get(T obj) {
255 if (obj == null || obj.getClass() != tclass || cclass != null)
257 return (V)unsafe.getObjectVolatile(obj, offset);
260 private void ensureProtectedAccess(T obj) {
261 if (cclass.isInstance(obj)) {
264 throw new RuntimeException (
265 new IllegalAccessException("Class " +
267 " can not access a protected member of class " +
269 " using an instance of " +
270 obj.getClass().getName()