sample/java.util.concurrent.atomic.AtomicReferenceFieldUpdater.txt

   1 *java.util.concurrent.atomic.AtomicReferenceFieldUpdater* *AtomicReferenceFieldUpdater*
   2
   3 public abstract class AtomicReferenceFieldUpdater<T,V>
   4   extends    |java.lang.Object|
   5
   6 |java.util.concurrent.atomic.AtomicReferenceFieldUpdater_Description|
   7 |java.util.concurrent.atomic.AtomicReferenceFieldUpdater_Fields|
   8 |java.util.concurrent.atomic.AtomicReferenceFieldUpdater_Constructors|
   9 |java.util.concurrent.atomic.AtomicReferenceFieldUpdater_Methods|
  10
  11 ================================================================================
  12
  13 *java.util.concurrent.atomic.AtomicReferenceFieldUpdater_Constructors*
  14 |java.util.concurrent.atomic.AtomicReferenceFieldUpdater()|Protected do-nothing
  15
  16 *java.util.concurrent.atomic.AtomicReferenceFieldUpdater_Methods*
  17 |java.util.concurrent.atomic.AtomicReferenceFieldUpdater.compareAndSet(T,V,V)|A
  18 |java.util.concurrent.atomic.AtomicReferenceFieldUpdater.get(T)|Gets the curren
  19 |java.util.concurrent.atomic.AtomicReferenceFieldUpdater.getAndSet(T,V)|Atomica
  20 |java.util.concurrent.atomic.AtomicReferenceFieldUpdater.lazySet(T,V)|Eventuall
  21 |java.util.concurrent.atomic.AtomicReferenceFieldUpdater.newUpdater(Class<U>,Class<W>,String)|
  22 |java.util.concurrent.atomic.AtomicReferenceFieldUpdater.set(T,V)|Sets the fiel
  23 |java.util.concurrent.atomic.AtomicReferenceFieldUpdater.weakCompareAndSet(T,V,V)|
  24
  25 *java.util.concurrent.atomic.AtomicReferenceFieldUpdater_Description*
  26
  27 A reflection-based utility that enables atomic updates to
  28 designatedvolatilereference fields of designated classes. This class is
  29 designed for use in atomic data structures in which several reference fields of
  30 the same node are independently subject to atomic updates. For example, a tree
  31 node might be declared as
  32
  33
  34
  35 class Node { private volatile Node left, right;
  36
  37 private static final AtomicReferenceFieldUpdater<Node, Node> leftUpdater =
  38 AtomicReferenceFieldUpdater.newUpdater(Node.class, Node.class, "left"); private
  39 static AtomicReferenceFieldUpdater<Node, Node> rightUpdater =
  40 AtomicReferenceFieldUpdater.newUpdater(Node.class, Node.class, "right");
  41
  42 Node getLeft() { return left; } boolean compareAndSetLeft(Node expect, Node
  43 update) { return leftUpdater.compareAndSet(this, expect, update); } // ... and
  44 so on }
  45
  46 Note that the guarantees of thecompareAndSetmethod in this class are weaker
  47 than in other atomic classes. Because this class cannot ensure that all uses of
  48 the field are appropriate for purposes of atomic access, it can guarantee
  49 atomicity only with respect to other invocations ofcompareAndSetandseton the
  50 same updater.
  51
  52
  53
  54 *java.util.concurrent.atomic.AtomicReferenceFieldUpdater()*
  55
  56 protected AtomicReferenceFieldUpdater()
  57
  58 Protected do-nothing constructor for use by subclasses.
  59
  60
  61 *java.util.concurrent.atomic.AtomicReferenceFieldUpdater.compareAndSet(T,V,V)*
  62
  63 public abstract boolean compareAndSet(
  64   T obj,
  65   V expect,
  66   V update)
  67
  68 Atomically sets the field of the given object managed by this updater to the
  69 given updated value if the current value==the expected value. This method is
  70 guaranteed to be atomic with respect to other calls tocompareAndSetandset, but
  71 not necessarily with respect to other changes in the field.
  72
  73
  74     obj - An object whose field to conditionally set
  75     expect - the expected value
  76     update - the new value
  77
  78     Returns: true if successful.
  79
  80 *java.util.concurrent.atomic.AtomicReferenceFieldUpdater.get(T)*
  81
  82 public abstract |V| get(T obj)
  83
  84 Gets the current value held in the field of the given object managed by this
  85 updater.
  86
  87
  88     obj - An object whose field to get
  89
  90     Returns: the current value
  91
  92 *java.util.concurrent.atomic.AtomicReferenceFieldUpdater.getAndSet(T,V)*
  93
  94 public |V| getAndSet(
  95   T obj,
  96   V newValue)
  97
  98 Atomically sets the field of the given object managed by this updater to the
  99 given value and returns the old value.
 100
 101
 102     obj - An object whose field to get and set
 103     newValue - the new value
 104
 105     Returns: the previous value
 106
 107 *java.util.concurrent.atomic.AtomicReferenceFieldUpdater.lazySet(T,V)*
 108
 109 public abstract void lazySet(
 110   T obj,
 111   V newValue)
 112
 113 Eventually sets the field of the given object managed by this updater to the
 114 given updated value.
 115
 116
 117     obj - An object whose field to set
 118     newValue - the new value
 119
 120 *java.util.concurrent.atomic.AtomicReferenceFieldUpdater.newUpdater(Class<U>,Class<W>,String)*
 121
 122 public static |java.util.concurrent.atomic.AtomicReferenceFieldUpdater|<U,W> newUpdater(
 123   java.lang.Class<U> tclass,
 124   java.lang.Class<W> vclass,
 125   java.lang.String fieldName)
 126
 127 Creates and returns an updater for objects with the given field. The Class
 128 arguments are needed to check that reflective types and generic types match.
 129
 130
 131     tclass - the class of the objects holding the field.
 132     vclass - the class of the field
 133     fieldName - the name of the field to be updated.
 134
 135     Returns:
 136
 137 *java.util.concurrent.atomic.AtomicReferenceFieldUpdater.set(T,V)*
 138
 139 public abstract void set(
 140   T obj,
 141   V newValue)
 142
 143 Sets the field of the given object managed by this updater to the given updated
 144 value. This operation is guaranteed to act as a volatile store with respect to
 145 subsequent invocations ofcompareAndSet.
 146
 147
 148     obj - An object whose field to set
 149     newValue - the new value
 150
 151 *java.util.concurrent.atomic.AtomicReferenceFieldUpdater.weakCompareAndSet(T,V,V)*
 152
 153 public abstract boolean weakCompareAndSet(
 154   T obj,
 155   V expect,
 156   V update)
 157
 158 Atomically sets the field of the given object managed by this updater to the
 159 given updated value if the current value==the expected value. This method is
 160 guaranteed to be atomic with respect to other calls tocompareAndSetandset, but
 161 not necessarily with respect to other changes in the field.
 162
 163 May fail spuriously and does not provide ordering guarantees, so is only rarely
 164 an appropriate alternative tocompareAndSet.
 165
 166
 167     obj - An object whose field to conditionally set
 168     expect - the expected value
 169     update - the new value
 170
 171     Returns: true if successful.
 172
 173