001: /*
002: * Written by Doug Lea with assistance from members of JCP JSR-166
003: * Expert Group and released to the public domain, as explained at
004: * http://creativecommons.org/licenses/publicdomain
005: */
006:
007: package java.util.concurrent.atomic;
008:
009: import sun.misc.Unsafe;
010: import java.lang.reflect.*;
011:
012: /**
013: * A reflection-based utility that enables atomic updates to
014: * designated <tt>volatile</tt> reference fields of designated
015: * classes. This class is designed for use in atomic data structures
016: * in which several reference fields of the same node are
017: * independently subject to atomic updates. For example, a tree node
018: * might be declared as
019: *
020: * <pre>
021: * class Node {
022: * private volatile Node left, right;
023: *
024: * private static final AtomicReferenceFieldUpdater<Node, Node> leftUpdater =
025: * AtomicReferenceFieldUpdater.newUpdater(Node.class, Node.class, "left");
026: * private static AtomicReferenceFieldUpdater<Node, Node> rightUpdater =
027: * AtomicReferenceFieldUpdater.newUpdater(Node.class, Node.class, "right");
028: *
029: * Node getLeft() { return left; }
030: * boolean compareAndSetLeft(Node expect, Node update) {
031: * return leftUpdater.compareAndSet(this, expect, update);
032: * }
033: * // ... and so on
034: * }
035: * </pre>
036: *
037: * <p> Note that the guarantees of the <tt>compareAndSet</tt>
038: * method in this class are weaker than in other atomic classes. Because this
039: * class cannot ensure that all uses of the field are appropriate for
040: * purposes of atomic access, it can guarantee atomicity and volatile
041: * semantics only with respect to other invocations of
042: * <tt>compareAndSet</tt> and <tt>set</tt>.
043: * @since 1.5
044: * @author Doug Lea
045: * @param <T> The type of the object holding the updatable field
046: * @param <V> The type of the field
047: */
048: public abstract class AtomicReferenceFieldUpdater<T, V> {
049:
050: /**
051: * Creates an updater for objects with the given field. The Class
052: * arguments are needed to check that reflective types and generic
053: * types match.
054: * @param tclass the class of the objects holding the field.
055: * @param vclass the class of the field
056: * @param fieldName the name of the field to be updated.
057: * @return the updater
058: * @throws IllegalArgumentException if the field is not a volatile reference type.
059: * @throws RuntimeException with a nested reflection-based
060: * exception if the class does not hold field or is the wrong type.
061: */
062: public static <U, W> AtomicReferenceFieldUpdater<U, W> newUpdater(
063: Class<U> tclass, Class<W> vclass, String fieldName) {
064: // Currently rely on standard intrinsics implementation
065: return new AtomicReferenceFieldUpdaterImpl<U, W>(tclass,
066: vclass, fieldName);
067: }
068:
069: /**
070: * Protected do-nothing constructor for use by subclasses.
071: */
072: protected AtomicReferenceFieldUpdater() {
073: }
074:
075: /**
076: * Atomically set the value of the field of the given object managed
077: * by this Updater to the given updated value if the current value
078: * <tt>==</tt> the expected value. This method is guaranteed to be
079: * atomic with respect to other calls to <tt>compareAndSet</tt> and
080: * <tt>set</tt>, but not necessarily with respect to other
081: * changes in the field.
082: * @param obj An object whose field to conditionally set
083: * @param expect the expected value
084: * @param update the new value
085: * @return true if successful.
086: */
087:
088: public abstract boolean compareAndSet(T obj, V expect, V update);
089:
090: /**
091: * Atomically set the value of the field of the given object managed
092: * by this Updater to the given updated value if the current value
093: * <tt>==</tt> the expected value. This method is guaranteed to be
094: * atomic with respect to other calls to <tt>compareAndSet</tt> and
095: * <tt>set</tt>, but not necessarily with respect to other
096: * changes in the field, and may fail spuriously.
097: * @param obj An object whose field to conditionally set
098: * @param expect the expected value
099: * @param update the new value
100: * @return true if successful.
101: */
102: public abstract boolean weakCompareAndSet(T obj, V expect, V update);
103:
104: /**
105: * Set the field of the given object managed by this updater. This
106: * operation is guaranteed to act as a volatile store with respect
107: * to subsequent invocations of <tt>compareAndSet</tt>.
108: * @param obj An object whose field to set
109: * @param newValue the new value
110: */
111: public abstract void set(T obj, V newValue);
112:
113: /**
114: * Get the current value held in the field by the given object.
115: * @param obj An object whose field to get
116: * @return the current value
117: */
118: public abstract V get(T obj);
119:
120: /**
121: * Set to the given value and return the old value.
122: *
123: * @param obj An object whose field to get and set
124: * @param newValue the new value
125: * @return the previous value
126: */
127: public V getAndSet(T obj, V newValue) {
128: for (;;) {
129: V current = get(obj);
130: if (compareAndSet(obj, current, newValue))
131: return current;
132: }
133: }
134:
135: /**
136: * Standard hotspot implementation using intrinsics
137: */
138: private static class AtomicReferenceFieldUpdaterImpl<T, V> extends
139: AtomicReferenceFieldUpdater<T, V> {
140: private static final Unsafe unsafe = Unsafe.getUnsafe();
141: private final long offset;
142: private final Class<T> tclass;
143: private final Class<V> vclass;
144:
145: AtomicReferenceFieldUpdaterImpl(Class<T> tclass,
146: Class<V> vclass, String fieldName) {
147: Field field = null;
148: Class fieldClass = null;
149: try {
150: field = tclass.getDeclaredField(fieldName);
151: fieldClass = field.getType();
152: } catch (Exception ex) {
153: throw new RuntimeException(ex);
154: }
155:
156: if (vclass != fieldClass)
157: throw new ClassCastException();
158:
159: if (!Modifier.isVolatile(field.getModifiers()))
160: throw new IllegalArgumentException(
161: "Must be volatile type");
162:
163: this .tclass = tclass;
164: this .vclass = vclass;
165: offset = unsafe.objectFieldOffset(field);
166: }
167:
168: public boolean compareAndSet(T obj, V expect, V update) {
169: if (!tclass.isInstance(obj)
170: || (update != null && !vclass.isInstance(update)))
171: throw new ClassCastException();
172: return unsafe.compareAndSwapObject(obj, offset, expect,
173: update);
174: }
175:
176: public boolean weakCompareAndSet(T obj, V expect, V update) {
177: // same implementation as strong form for now
178: if (!tclass.isInstance(obj)
179: || (update != null && !vclass.isInstance(update)))
180: throw new ClassCastException();
181: return unsafe.compareAndSwapObject(obj, offset, expect,
182: update);
183: }
184:
185: public void set(T obj, V newValue) {
186: if (!tclass.isInstance(obj)
187: || (newValue != null && !vclass
188: .isInstance(newValue)))
189: throw new ClassCastException();
190: unsafe.putObjectVolatile(obj, offset, newValue);
191: }
192:
193: public V get(T obj) {
194: if (!tclass.isInstance(obj))
195: throw new ClassCastException();
196: return (V) unsafe.getObjectVolatile(obj, offset);
197: }
198: }
199: }
|