Mercurial > hg > openjdk > jdk9 > jdk
changeset 17219:9b69584ea554
8181104: Fix specs for updateAndGet and related methods
Reviewed-by: martin, psandoz, dholmes, chegar
line wrap: on
line diff
--- a/src/java.base/share/classes/java/lang/invoke/VarHandle.java Tue Jun 13 13:31:32 2017 +0100 +++ b/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/src/java.base/share/classes/java/util/concurrent/atomic/AtomicInteger.java Tue Jun 13 13:31:32 2017 +0100 +++ b/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/src/java.base/share/classes/java/util/concurrent/atomic/AtomicIntegerArray.java Tue Jun 13 13:31:32 2017 +0100 +++ b/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/src/java.base/share/classes/java/util/concurrent/atomic/AtomicIntegerFieldUpdater.java Tue Jun 13 13:31:32 2017 +0100 +++ b/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/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLong.java Tue Jun 13 13:31:32 2017 +0100 +++ b/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/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLongArray.java Tue Jun 13 13:31:32 2017 +0100 +++ b/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/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLongFieldUpdater.java Tue Jun 13 13:31:32 2017 +0100 +++ b/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/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReference.java Tue Jun 13 13:31:32 2017 +0100 +++ b/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/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceArray.java Tue Jun 13 13:31:32 2017 +0100 +++ b/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/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java Tue Jun 13 13:31:32 2017 +0100 +++ b/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