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/licenses/publicdomain 5 */ 6 7 package java.util.concurrent.atomic; 8 import sun.misc.Unsafe; 9 import java.lang.reflect.*; 10 11 /** 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 18 * 19 * <pre> 20 * class Node { 21 * private volatile Node left, right; 22 * 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"); 27 * 28 * Node getLeft() { return left; } 29 * boolean compareAndSetLeft(Node expect, Node update) { 30 * return leftUpdater.compareAndSet(this, expect, update); 31 * } 32 * // ... and so on 33 * } 34 * </pre> 35 * 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. 42 * 43 * @since 1.5 44 * @author Doug Lea 45 * @param <T> The type of the object holding the updatable field 46 * @param <V> The type of the field 47 */ 48 public abstract class AtomicReferenceFieldUpdater<T, V> { 49 50 /** 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. 54 * 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. 58 * @return the updater 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. 62 */ newUpdater(Class<U> tclass, Class<W> vclass, String fieldName)63 public static <U, W> AtomicReferenceFieldUpdater<U,W> newUpdater(Class<U> tclass, Class<W> vclass, String fieldName) { 64 return new AtomicReferenceFieldUpdaterImpl<U,W>(tclass, 65 vclass, 66 fieldName); 67 } 68 69 /** 70 * Protected do-nothing constructor for use by subclasses. 71 */ AtomicReferenceFieldUpdater()72 protected AtomicReferenceFieldUpdater() { 73 } 74 75 /** 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. 81 * 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. 86 */ compareAndSet(T obj, V expect, V update)87 public abstract boolean compareAndSet(T obj, V expect, V update); 88 89 /** 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>. 97 * 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. 102 */ weakCompareAndSet(T obj, V expect, V update)103 public abstract boolean weakCompareAndSet(T obj, V expect, V update); 104 105 /** 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>. 110 * 111 * @param obj An object whose field to set 112 * @param newValue the new value 113 */ set(T obj, V newValue)114 public abstract void set(T obj, V newValue); 115 116 /** 117 * Eventually sets the field of the given object managed by this 118 * updater to the given updated value. 119 * 120 * @param obj An object whose field to set 121 * @param newValue the new value 122 * @since 1.6 123 */ lazySet(T obj, V newValue)124 public abstract void lazySet(T obj, V newValue); 125 126 /** 127 * Gets the current value held in the field of the given object managed 128 * by this updater. 129 * 130 * @param obj An object whose field to get 131 * @return the current value 132 */ get(T obj)133 public abstract V get(T obj); 134 135 /** 136 * Atomically sets the field of the given object managed by this updater 137 * to the given value and returns the old value. 138 * 139 * @param obj An object whose field to get and set 140 * @param newValue the new value 141 * @return the previous value 142 */ getAndSet(T obj, V newValue)143 public V getAndSet(T obj, V newValue) { 144 for (;;) { 145 V current = get(obj); 146 if (compareAndSet(obj, current, newValue)) 147 return current; 148 } 149 } 150 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; 158 159 /* 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 168 * screenings fail. 169 */ 170 AtomicReferenceFieldUpdaterImpl(Class<T> tclass, Class<V> vclass, String fieldName)171 AtomicReferenceFieldUpdaterImpl(Class<T> tclass, 172 Class<V> vclass, 173 String fieldName) { 174 Field field = null; 175 Class fieldClass = null; 176 Class caller = null; 177 int modifiers = 0; 178 try { 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); 188 } 189 190 if (vclass != fieldClass) 191 throw new ClassCastException(); 192 193 if (!Modifier.isVolatile(modifiers)) 194 throw new IllegalArgumentException("Must be volatile type"); 195 196 this.cclass = (Modifier.isProtected(modifiers) && 197 caller != tclass) ? caller : null; 198 this.tclass = tclass; 199 if (vclass == Object.class) 200 this.vclass = null; 201 else 202 this.vclass = vclass; 203 offset = unsafe.objectFieldOffset(field); 204 } 205 targetCheck(T obj)206 void targetCheck(T obj) { 207 if (!tclass.isInstance(obj)) 208 throw new ClassCastException(); 209 if (cclass != null) 210 ensureProtectedAccess(obj); 211 } 212 updateCheck(T obj, V update)213 void updateCheck(T obj, V update) { 214 if (!tclass.isInstance(obj) || 215 (update != null && vclass != null && !vclass.isInstance(update))) 216 throw new ClassCastException(); 217 if (cclass != null) 218 ensureProtectedAccess(obj); 219 } 220 compareAndSet(T obj, V expect, V update)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); 227 } 228 weakCompareAndSet(T obj, V expect, V 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); 236 } 237 set(T obj, V newValue)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); 244 } 245 lazySet(T obj, V 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); 252 } 253 get(T obj)254 public V get(T obj) { 255 if (obj == null || obj.getClass() != tclass || cclass != null) 256 targetCheck(obj); 257 return (V)unsafe.getObjectVolatile(obj, offset); 258 } 259 ensureProtectedAccess(T obj)260 private void ensureProtectedAccess(T obj) { 261 if (cclass.isInstance(obj)) { 262 return; 263 } 264 throw new RuntimeException ( 265 new IllegalAccessException("Class " + 266 cclass.getName() + 267 " can not access a protected member of class " + 268 tclass.getName() + 269 " using an instance of " + 270 obj.getClass().getName() 271 ) 272 ); 273 } 274 } 275 } 276