8181104: Fix specs for updateAndGet and related methods
Reviewed-by: martin, psandoz, dholmes, chegar
--- a/jdk/src/java.base/share/classes/java/lang/invoke/VarHandle.java Tue Jun 13 13:31:32 2017 +0100
+++ b/jdk/src/java.base/share/classes/java/lang/invoke/VarHandle.java Tue Jun 13 09:13:28 2017 -0700
@@ -110,6 +110,20 @@
* boolean r = avh.compareAndSet(sa, 10, "expected", "new");
* }</pre>
*
+ * <p>Access modes control atomicity and consistency properties.
+ * <em>Plain</em> read ({@code get}) and write ({@code set})
+ * accesses are guaranteed to be bitwise atomic only for references
+ * and for primitive values of at most 32 bits, and impose no observable
+ * ordering constraints with respect to threads other than the
+ * executing thread. <em>Opaque</em> operations are bitwise atomic and
+ * coherently ordered with respect to accesses to the same variable.
+ * In addition to obeying Opaque properties, <em>Acquire</em> mode
+ * reads and their subsequent accesses are ordered after matching
+ * <em>Release</em> mode writes and their previous accesses. In
+ * addition to obeying Acquire and Release properties, all
+ * <em>Volatile</em> operations are totally ordered with respect to
+ * each other.
+ *
* <p>Access modes are grouped into the following categories:
* <ul>
* <li>read access modes that get the value of a variable under specified
--- a/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicInteger.java Tue Jun 13 13:31:32 2017 +0100
+++ b/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicInteger.java Tue Jun 13 09:13:28 2017 -0700
@@ -249,7 +249,8 @@
}
/**
- * Atomically updates the current value with the results of
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the current value with the results of
* applying the given function, returning the previous value. The
* function should be side-effect-free, since it may be re-applied
* when attempted updates fail due to contention among threads.
@@ -270,7 +271,8 @@
}
/**
- * Atomically updates the current value with the results of
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the current value with the results of
* applying the given function, returning the updated value. The
* function should be side-effect-free, since it may be re-applied
* when attempted updates fail due to contention among threads.
@@ -291,13 +293,14 @@
}
/**
- * Atomically updates the current value with the results of
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the current value with the results of
* applying the given function to the current and given values,
* returning the previous value. The function should be
* side-effect-free, since it may be re-applied when attempted
- * updates fail due to contention among threads. The function
- * is applied with the current value as its first argument,
- * and the given update as the second argument.
+ * updates fail due to contention among threads. The function is
+ * applied with the current value as its first argument, and the
+ * given update as the second argument.
*
* @param x the update value
* @param accumulatorFunction a side-effect-free function of two arguments
@@ -317,13 +320,14 @@
}
/**
- * Atomically updates the current value with the results of
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the current value with the results of
* applying the given function to the current and given values,
* returning the updated value. The function should be
* side-effect-free, since it may be re-applied when attempted
- * updates fail due to contention among threads. The function
- * is applied with the current value as its first argument,
- * and the given update as the second argument.
+ * updates fail due to contention among threads. The function is
+ * applied with the current value as its first argument, and the
+ * given update as the second argument.
*
* @param x the update value
* @param accumulatorFunction a side-effect-free function of two arguments
--- a/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicIntegerArray.java Tue Jun 13 13:31:32 2017 +0100
+++ b/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicIntegerArray.java Tue Jun 13 09:13:28 2017 -0700
@@ -260,10 +260,12 @@
}
/**
- * Atomically updates the element at index {@code i} with the results
- * of applying the given function, returning the previous value. The
- * function should be side-effect-free, since it may be re-applied
- * when attempted updates fail due to contention among threads.
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the element at index {@code i} with
+ * the results of applying the given function, returning the
+ * previous value. The function should be side-effect-free, since
+ * it may be re-applied when attempted updates fail due to
+ * contention among threads.
*
* @param i the index
* @param updateFunction a side-effect-free function
@@ -282,10 +284,12 @@
}
/**
- * Atomically updates the element at index {@code i} with the results
- * of applying the given function, returning the updated value. The
- * function should be side-effect-free, since it may be re-applied
- * when attempted updates fail due to contention among threads.
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the element at index {@code i} with
+ * the results of applying the given function, returning the
+ * updated value. The function should be side-effect-free, since it
+ * may be re-applied when attempted updates fail due to contention
+ * among threads.
*
* @param i the index
* @param updateFunction a side-effect-free function
@@ -304,10 +308,11 @@
}
/**
- * Atomically updates the element at index {@code i} with the
- * results of applying the given function to the current and given
- * values, returning the previous value. The function should be
- * side-effect-free, since it may be re-applied when attempted
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the element at index {@code i} with
+ * the results of applying the given function to the current and
+ * given values, returning the previous value. The function should
+ * be side-effect-free, since it may be re-applied when attempted
* updates fail due to contention among threads. The function is
* applied with the current value of the element at index {@code i}
* as its first argument, and the given update as the second
@@ -332,10 +337,11 @@
}
/**
- * Atomically updates the element at index {@code i} with the
- * results of applying the given function to the current and given
- * values, returning the updated value. The function should be
- * side-effect-free, since it may be re-applied when attempted
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the element at index {@code i} with
+ * the results of applying the given function to the current and
+ * given values, returning the updated value. The function should
+ * be side-effect-free, since it may be re-applied when attempted
* updates fail due to contention among threads. The function is
* applied with the current value of the element at index {@code i}
* as its first argument, and the given update as the second
--- a/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicIntegerFieldUpdater.java Tue Jun 13 13:31:32 2017 +0100
+++ b/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicIntegerFieldUpdater.java Tue Jun 13 09:13:28 2017 -0700
@@ -46,6 +46,7 @@
import jdk.internal.misc.Unsafe;
import jdk.internal.reflect.CallerSensitive;
import jdk.internal.reflect.Reflection;
+import java.lang.invoke.VarHandle;
/**
* A reflection-based utility that enables atomic updates to
@@ -275,10 +276,12 @@
}
/**
- * Atomically updates the field of the given object managed by this updater
- * with the results of applying the given function, returning the previous
- * value. The function should be side-effect-free, since it may be
- * re-applied when attempted updates fail due to contention among threads.
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the field of the given object managed
+ * by this updater with the results of applying the given
+ * function, returning the previous value. The function should be
+ * side-effect-free, since it may be re-applied when attempted
+ * updates fail due to contention among threads.
*
* @param obj An object whose field to get and set
* @param updateFunction a side-effect-free function
@@ -295,10 +298,12 @@
}
/**
- * Atomically updates the field of the given object managed by this updater
- * with the results of applying the given function, returning the updated
- * value. The function should be side-effect-free, since it may be
- * re-applied when attempted updates fail due to contention among threads.
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the field of the given object managed
+ * by this updater with the results of applying the given
+ * function, returning the updated value. The function should be
+ * side-effect-free, since it may be re-applied when attempted
+ * updates fail due to contention among threads.
*
* @param obj An object whose field to get and set
* @param updateFunction a side-effect-free function
@@ -315,13 +320,14 @@
}
/**
- * Atomically updates the field of the given object managed by this
- * updater with the results of applying the given function to the
- * current and given values, returning the previous value. The
- * function should be side-effect-free, since it may be re-applied
- * when attempted updates fail due to contention among threads. The
- * function is applied with the current value as its first argument,
- * and the given update as the second argument.
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the field of the given object managed
+ * by this updater with the results of applying the given function
+ * to the current and given values, returning the previous value.
+ * The function should be side-effect-free, since it may be
+ * re-applied when attempted updates fail due to contention among
+ * threads. The function is applied with the current value as its
+ * first argument, and the given update as the second argument.
*
* @param obj An object whose field to get and set
* @param x the update value
@@ -340,13 +346,14 @@
}
/**
- * Atomically updates the field of the given object managed by this
- * updater with the results of applying the given function to the
- * current and given values, returning the updated value. The
- * function should be side-effect-free, since it may be re-applied
- * when attempted updates fail due to contention among threads. The
- * function is applied with the current value as its first argument,
- * and the given update as the second argument.
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the field of the given object managed
+ * by this updater with the results of applying the given function
+ * to the current and given values, returning the updated value.
+ * The function should be side-effect-free, since it may be
+ * re-applied when attempted updates fail due to contention among
+ * threads. The function is applied with the current value as its
+ * first argument, and the given update as the second argument.
*
* @param obj An object whose field to get and set
* @param x the update value
--- a/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLong.java Tue Jun 13 13:31:32 2017 +0100
+++ b/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLong.java Tue Jun 13 09:13:28 2017 -0700
@@ -118,8 +118,7 @@
* @param newValue the new value
*/
public final void set(long newValue) {
- // Use putLongVolatile instead of ordinary volatile store when
- // using compareAndSetLong, for sake of some 32bit systems.
+ // See JDK-8180620: Clarify VarHandle mixed-access subtleties
U.putLongVolatile(this, VALUE, newValue);
}
@@ -265,7 +264,8 @@
}
/**
- * Atomically updates the current value with the results of
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the current value with the results of
* applying the given function, returning the previous value. The
* function should be side-effect-free, since it may be re-applied
* when attempted updates fail due to contention among threads.
@@ -286,7 +286,8 @@
}
/**
- * Atomically updates the current value with the results of
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the current value with the results of
* applying the given function, returning the updated value. The
* function should be side-effect-free, since it may be re-applied
* when attempted updates fail due to contention among threads.
@@ -307,13 +308,14 @@
}
/**
- * Atomically updates the current value with the results of
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the current value with the results of
* applying the given function to the current and given values,
* returning the previous value. The function should be
* side-effect-free, since it may be re-applied when attempted
- * updates fail due to contention among threads. The function
- * is applied with the current value as its first argument,
- * and the given update as the second argument.
+ * updates fail due to contention among threads. The function is
+ * applied with the current value as its first argument, and the
+ * given update as the second argument.
*
* @param x the update value
* @param accumulatorFunction a side-effect-free function of two arguments
@@ -333,13 +335,14 @@
}
/**
- * Atomically updates the current value with the results of
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the current value with the results of
* applying the given function to the current and given values,
* returning the updated value. The function should be
* side-effect-free, since it may be re-applied when attempted
- * updates fail due to contention among threads. The function
- * is applied with the current value as its first argument,
- * and the given update as the second argument.
+ * updates fail due to contention among threads. The function is
+ * applied with the current value as its first argument, and the
+ * given update as the second argument.
*
* @param x the update value
* @param accumulatorFunction a side-effect-free function of two arguments
--- a/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLongArray.java Tue Jun 13 13:31:32 2017 +0100
+++ b/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLongArray.java Tue Jun 13 09:13:28 2017 -0700
@@ -260,10 +260,12 @@
}
/**
- * Atomically updates the element at index {@code i} with the results
- * of applying the given function, returning the previous value. The
- * function should be side-effect-free, since it may be re-applied
- * when attempted updates fail due to contention among threads.
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the element at index {@code i} with
+ * the results of applying the given function, returning the
+ * previous value. The function should be side-effect-free, since
+ * it may be re-applied when attempted updates fail due to
+ * contention among threads.
*
* @param i the index
* @param updateFunction a side-effect-free function
@@ -282,10 +284,12 @@
}
/**
- * Atomically updates the element at index {@code i} with the results
- * of applying the given function, returning the updated value. The
- * function should be side-effect-free, since it may be re-applied
- * when attempted updates fail due to contention among threads.
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the element at index {@code i} with
+ * the results of applying the given function, returning the
+ * updated value. The function should be side-effect-free, since it
+ * may be re-applied when attempted updates fail due to contention
+ * among threads.
*
* @param i the index
* @param updateFunction a side-effect-free function
@@ -304,10 +308,11 @@
}
/**
- * Atomically updates the element at index {@code i} with the
- * results of applying the given function to the current and given
- * values, returning the previous value. The function should be
- * side-effect-free, since it may be re-applied when attempted
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the element at index {@code i} with
+ * the results of applying the given function to the current and
+ * given values, returning the previous value. The function should
+ * be side-effect-free, since it may be re-applied when attempted
* updates fail due to contention among threads. The function is
* applied with the current value of the element at index {@code i}
* as its first argument, and the given update as the second
@@ -332,10 +337,11 @@
}
/**
- * Atomically updates the element at index {@code i} with the
- * results of applying the given function to the current and given
- * values, returning the updated value. The function should be
- * side-effect-free, since it may be re-applied when attempted
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the element at index {@code i} with
+ * the results of applying the given function to the current and
+ * given values, returning the updated value. The function should
+ * be side-effect-free, since it may be re-applied when attempted
* updates fail due to contention among threads. The function is
* applied with the current value of the element at index {@code i}
* as its first argument, and the given update as the second
--- a/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLongFieldUpdater.java Tue Jun 13 13:31:32 2017 +0100
+++ b/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLongFieldUpdater.java Tue Jun 13 09:13:28 2017 -0700
@@ -46,6 +46,7 @@
import jdk.internal.misc.Unsafe;
import jdk.internal.reflect.CallerSensitive;
import jdk.internal.reflect.Reflection;
+import java.lang.invoke.VarHandle;
/**
* A reflection-based utility that enables atomic updates to
@@ -278,10 +279,12 @@
}
/**
- * Atomically updates the field of the given object managed by this updater
- * with the results of applying the given function, returning the previous
- * value. The function should be side-effect-free, since it may be
- * re-applied when attempted updates fail due to contention among threads.
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the field of the given object managed
+ * by this updater with the results of applying the given
+ * function, returning the previous value. The function should be
+ * side-effect-free, since it may be re-applied when attempted
+ * updates fail due to contention among threads.
*
* @param obj An object whose field to get and set
* @param updateFunction a side-effect-free function
@@ -298,10 +301,12 @@
}
/**
- * Atomically updates the field of the given object managed by this updater
- * with the results of applying the given function, returning the updated
- * value. The function should be side-effect-free, since it may be
- * re-applied when attempted updates fail due to contention among threads.
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the field of the given object managed
+ * by this updater with the results of applying the given
+ * function, returning the updated value. The function should be
+ * side-effect-free, since it may be re-applied when attempted
+ * updates fail due to contention among threads.
*
* @param obj An object whose field to get and set
* @param updateFunction a side-effect-free function
@@ -318,13 +323,14 @@
}
/**
- * Atomically updates the field of the given object managed by this
- * updater with the results of applying the given function to the
- * current and given values, returning the previous value. The
- * function should be side-effect-free, since it may be re-applied
- * when attempted updates fail due to contention among threads. The
- * function is applied with the current value as its first argument,
- * and the given update as the second argument.
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the field of the given object managed
+ * by this updater with the results of applying the given function
+ * to the current and given values, returning the previous value.
+ * The function should be side-effect-free, since it may be
+ * re-applied when attempted updates fail due to contention among
+ * threads. The function is applied with the current value as its
+ * first argument, and the given update as the second argument.
*
* @param obj An object whose field to get and set
* @param x the update value
@@ -343,13 +349,14 @@
}
/**
- * Atomically updates the field of the given object managed by this
- * updater with the results of applying the given function to the
- * current and given values, returning the updated value. The
- * function should be side-effect-free, since it may be re-applied
- * when attempted updates fail due to contention among threads. The
- * function is applied with the current value as its first argument,
- * and the given update as the second argument.
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the field of the given object managed
+ * by this updater with the results of applying the given function
+ * to the current and given values, returning the updated value.
+ * The function should be side-effect-free, since it may be
+ * re-applied when attempted updates fail due to contention among
+ * threads. The function is applied with the current value as its
+ * first argument, and the given update as the second argument.
*
* @param obj An object whose field to get and set
* @param x the update value
--- a/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReference.java Tue Jun 13 13:31:32 2017 +0100
+++ b/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReference.java Tue Jun 13 09:13:28 2017 -0700
@@ -170,7 +170,8 @@
}
/**
- * Atomically updates the current value with the results of
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the current value with the results of
* applying the given function, returning the previous value. The
* function should be side-effect-free, since it may be re-applied
* when attempted updates fail due to contention among threads.
@@ -191,7 +192,8 @@
}
/**
- * Atomically updates the current value with the results of
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the current value with the results of
* applying the given function, returning the updated value. The
* function should be side-effect-free, since it may be re-applied
* when attempted updates fail due to contention among threads.
@@ -212,13 +214,14 @@
}
/**
- * Atomically updates the current value with the results of
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the current value with the results of
* applying the given function to the current and given values,
* returning the previous value. The function should be
* side-effect-free, since it may be re-applied when attempted
- * updates fail due to contention among threads. The function
- * is applied with the current value as its first argument,
- * and the given update as the second argument.
+ * updates fail due to contention among threads. The function is
+ * applied with the current value as its first argument, and the
+ * given update as the second argument.
*
* @param x the update value
* @param accumulatorFunction a side-effect-free function of two arguments
@@ -238,13 +241,14 @@
}
/**
- * Atomically updates the current value with the results of
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the current value with the results of
* applying the given function to the current and given values,
* returning the updated value. The function should be
* side-effect-free, since it may be re-applied when attempted
- * updates fail due to contention among threads. The function
- * is applied with the current value as its first argument,
- * and the given update as the second argument.
+ * updates fail due to contention among threads. The function is
+ * applied with the current value as its first argument, and the
+ * given update as the second argument.
*
* @param x the update value
* @param accumulatorFunction a side-effect-free function of two arguments
--- a/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceArray.java Tue Jun 13 13:31:32 2017 +0100
+++ b/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceArray.java Tue Jun 13 09:13:28 2017 -0700
@@ -190,10 +190,12 @@
}
/**
- * Atomically updates the element at index {@code i} with the results
- * of applying the given function, returning the previous value. The
- * function should be side-effect-free, since it may be re-applied
- * when attempted updates fail due to contention among threads.
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the element at index {@code i} with
+ * the results of applying the given function, returning the
+ * previous value. The function should be side-effect-free, since
+ * it may be re-applied when attempted updates fail due to
+ * contention among threads.
*
* @param i the index
* @param updateFunction a side-effect-free function
@@ -212,10 +214,12 @@
}
/**
- * Atomically updates the element at index {@code i} with the results
- * of applying the given function, returning the updated value. The
- * function should be side-effect-free, since it may be re-applied
- * when attempted updates fail due to contention among threads.
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the element at index {@code i} with
+ * the results of applying the given function, returning the
+ * updated value. The function should be side-effect-free, since it
+ * may be re-applied when attempted updates fail due to contention
+ * among threads.
*
* @param i the index
* @param updateFunction a side-effect-free function
@@ -234,10 +238,11 @@
}
/**
- * Atomically updates the element at index {@code i} with the
- * results of applying the given function to the current and given
- * values, returning the previous value. The function should be
- * side-effect-free, since it may be re-applied when attempted
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the element at index {@code i} with
+ * the results of applying the given function to the current and
+ * given values, returning the previous value. The function should
+ * be side-effect-free, since it may be re-applied when attempted
* updates fail due to contention among threads. The function is
* applied with the current value of the element at index {@code i}
* as its first argument, and the given update as the second
@@ -262,10 +267,11 @@
}
/**
- * Atomically updates the element at index {@code i} with the
- * results of applying the given function to the current and given
- * values, returning the updated value. The function should be
- * side-effect-free, since it may be re-applied when attempted
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the element at index {@code i} with
+ * the results of applying the given function to the current and
+ * given values, returning the updated value. The function should
+ * be side-effect-free, since it may be re-applied when attempted
* updates fail due to contention among threads. The function is
* applied with the current value of the element at index {@code i}
* as its first argument, and the given update as the second
--- a/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java Tue Jun 13 13:31:32 2017 +0100
+++ b/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java Tue Jun 13 09:13:28 2017 -0700
@@ -46,6 +46,7 @@
import jdk.internal.misc.Unsafe;
import jdk.internal.reflect.CallerSensitive;
import jdk.internal.reflect.Reflection;
+import java.lang.invoke.VarHandle;
/**
* A reflection-based utility that enables atomic updates to
@@ -199,10 +200,12 @@
}
/**
- * Atomically updates the field of the given object managed by this updater
- * with the results of applying the given function, returning the previous
- * value. The function should be side-effect-free, since it may be
- * re-applied when attempted updates fail due to contention among threads.
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the field of the given object managed
+ * by this updater with the results of applying the given
+ * function, returning the previous value. The function should be
+ * side-effect-free, since it may be re-applied when attempted
+ * updates fail due to contention among threads.
*
* @param obj An object whose field to get and set
* @param updateFunction a side-effect-free function
@@ -219,10 +222,12 @@
}
/**
- * Atomically updates the field of the given object managed by this updater
- * with the results of applying the given function, returning the updated
- * value. The function should be side-effect-free, since it may be
- * re-applied when attempted updates fail due to contention among threads.
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the field of the given object managed
+ * by this updater with the results of applying the given
+ * function, returning the updated value. The function should be
+ * side-effect-free, since it may be re-applied when attempted
+ * updates fail due to contention among threads.
*
* @param obj An object whose field to get and set
* @param updateFunction a side-effect-free function
@@ -239,13 +244,14 @@
}
/**
- * Atomically updates the field of the given object managed by this
- * updater with the results of applying the given function to the
- * current and given values, returning the previous value. The
- * function should be side-effect-free, since it may be re-applied
- * when attempted updates fail due to contention among threads. The
- * function is applied with the current value as its first argument,
- * and the given update as the second argument.
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the field of the given object managed
+ * by this updater with the results of applying the given function
+ * to the current and given values, returning the previous value.
+ * The function should be side-effect-free, since it may be
+ * re-applied when attempted updates fail due to contention among
+ * threads. The function is applied with the current value as its
+ * first argument, and the given update as the second argument.
*
* @param obj An object whose field to get and set
* @param x the update value
@@ -264,13 +270,14 @@
}
/**
- * Atomically updates the field of the given object managed by this
- * updater with the results of applying the given function to the
- * current and given values, returning the updated value. The
- * function should be side-effect-free, since it may be re-applied
- * when attempted updates fail due to contention among threads. The
- * function is applied with the current value as its first argument,
- * and the given update as the second argument.
+ * Atomically updates (with memory effects as specified by {@link
+ * VarHandle#compareAndSet}) the field of the given object managed
+ * by this updater with the results of applying the given function
+ * to the current and given values, returning the updated value.
+ * The function should be side-effect-free, since it may be
+ * re-applied when attempted updates fail due to contention among
+ * threads. The function is applied with the current value as its
+ * first argument, and the given update as the second argument.
*
* @param obj An object whose field to get and set
* @param x the update value