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

   1 *java.util.concurrent.atomic.AtomicReferenceFieldUpdater* *AtomicReferenceFieldUpdater*
   2
   3 public abstract class AtomicReferenceFieldUpdater
   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)|Get the current
  19 |java.util.concurrent.atomic.AtomicReferenceFieldUpdater.getAndSet(T,V)|Set to
  20 |java.util.concurrent.atomic.AtomicReferenceFieldUpdater.newUpdater(Class,Class,String)|
  21 |java.util.concurrent.atomic.AtomicReferenceFieldUpdater.set(T,V)|Set the field
  22 |java.util.concurrent.atomic.AtomicReferenceFieldUpdater.weakCompareAndSet(T,V,V)|
  23
  24 *java.util.concurrent.atomic.AtomicReferenceFieldUpdater_Description*
  25
  26 A reflection-based utility that enables atomic updates to designated volatile
  27 reference fields of designated classes. This class is designed for use in
  28 atomic data structures in which several reference fields of the same node are
  29 independently subject to atomic updates. For example, a tree node might be
  30 declared as
  31
  32
  33
  34 class Node { private volatile Node left, right;
  35
  36 private static final AtomicReferenceFieldUpdater<Node, Node> leftUpdater =
  37 AtomicReferenceFieldUpdater.newUpdater(Node.class, Node.class, "left"); private
  38 static AtomicReferenceFieldUpdater<Node, Node> rightUpdater =
  39 AtomicReferenceFieldUpdater.newUpdater(Node.class, Node.class, "right");
  40
  41 Node getLeft() { return left; } boolean compareAndSetLeft(Node expect, Node
  42 update) { return leftUpdater.compareAndSet(this, expect, update); } // ... and
  43 so on }
  44
  45 Note that the guarantees of the compareAndSet method in this class are weaker
  46 than in other atomic classes. Because this class cannot ensure that all uses of
  47 the field are appropriate for purposes of atomic access, it can guarantee
  48 atomicity and volatile semantics only with respect to other invocations of
  49 compareAndSet and set.
  50
  51
  52 *java.util.concurrent.atomic.AtomicReferenceFieldUpdater()*
  53
  54 protected AtomicReferenceFieldUpdater()
  55
  56 Protected do-nothing constructor for use by subclasses.
  57
  58
  59 *java.util.concurrent.atomic.AtomicReferenceFieldUpdater.compareAndSet(T,V,V)*
  60
  61 public abstract boolean compareAndSet(
  62   java.lang.Object obj,
  63   java.lang.Object expect,
  64   java.lang.Object update)
  65
  66 Atomically set the value of the field of the given object managed by this
  67 Updater to the given updated value if the current value == the expected value.
  68 This method is guaranteed to be atomic with respect to other calls to
  69 compareAndSet and set, but not necessarily with respect to other changes in the
  70 field.
  71
  72     obj - An object whose field to conditionally set
  73     expect - the expected value
  74     update - the new value
  75
  76     Returns: true if successful.
  77 *java.util.concurrent.atomic.AtomicReferenceFieldUpdater.get(T)*
  78
  79 public abstract |java.lang.Object| get(java.lang.Object obj)
  80
  81 Get the current value held in the field by the given object.
  82
  83     obj - An object whose field to get
  84
  85     Returns: the current value
  86 *java.util.concurrent.atomic.AtomicReferenceFieldUpdater.getAndSet(T,V)*
  87
  88 public |java.lang.Object| getAndSet(
  89   java.lang.Object obj,
  90   java.lang.Object newValue)
  91
  92 Set to the given value and return the old value.
  93
  94     obj - An object whose field to get and set
  95     newValue - the new value
  96
  97     Returns: the previous value
  98 *java.util.concurrent.atomic.AtomicReferenceFieldUpdater.newUpdater(Class,Class,String)*
  99
 100 public static |java.util.concurrent.atomic.AtomicReferenceFieldUpdater| newUpdater(
 101   java.lang.Class tclass,
 102   java.lang.Class vclass,
 103   java.lang.String fieldName)
 104
 105 Creates an updater for objects with the given field. The Class arguments are
 106 needed to check that reflective types and generic types match.
 107
 108     tclass - the class of the objects holding the field.
 109     vclass - the class of the field
 110     fieldName - the name of the field to be updated.
 111
 112     Returns:
 113 *java.util.concurrent.atomic.AtomicReferenceFieldUpdater.set(T,V)*
 114
 115 public abstract void set(
 116   java.lang.Object obj,
 117   java.lang.Object newValue)
 118
 119 Set the field of the given object managed by this updater. This operation is
 120 guaranteed to act as a volatile store with respect to subsequent invocations of
 121 compareAndSet.
 122
 123     obj - An object whose field to set
 124     newValue - the new value
 125
 126 *java.util.concurrent.atomic.AtomicReferenceFieldUpdater.weakCompareAndSet(T,V,V)*
 127
 128 public abstract boolean weakCompareAndSet(
 129   java.lang.Object obj,
 130   java.lang.Object expect,
 131   java.lang.Object update)
 132
 133 Atomically set the value of the field of the given object managed by this
 134 Updater to the given updated value if the current value == the expected value.
 135 This method is guaranteed to be atomic with respect to other calls to
 136 compareAndSet and set, but not necessarily with respect to other changes in the
 137 field, and may fail spuriously.
 138
 139     obj - An object whose field to conditionally set
 140     expect - the expected value
 141     update - the new value
 142
 143     Returns: true if successful.
 144