8164814: Deprecate Atomic*.weakCompareAndSet and defer to Atomic*.weakCompareAndSetPlain
authorpsandoz
Mon, 10 Oct 2016 15:58:42 -0700
changeset 41415 9c298252e385
parent 41414 7fd4548e9733
child 41416 9c2e348c03c3
8164814: Deprecate Atomic*.weakCompareAndSet and defer to Atomic*.weakCompareAndSetPlain Reviewed-by: martin, dl
jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicBoolean.java
jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicInteger.java
jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicIntegerArray.java
jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLong.java
jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLongArray.java
jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReference.java
jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceArray.java
jdk/src/java.base/share/classes/java/util/stream/Stream.java
jdk/test/java/util/concurrent/tck/AtomicBoolean9Test.java
jdk/test/java/util/concurrent/tck/AtomicInteger9Test.java
jdk/test/java/util/concurrent/tck/AtomicIntegerArray9Test.java
jdk/test/java/util/concurrent/tck/AtomicLong9Test.java
jdk/test/java/util/concurrent/tck/AtomicLongArray9Test.java
jdk/test/java/util/concurrent/tck/AtomicReference9Test.java
jdk/test/java/util/concurrent/tck/AtomicReferenceArray9Test.java
--- a/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicBoolean.java	Mon Oct 10 15:46:14 2016 -0700
+++ b/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicBoolean.java	Mon Oct 10 15:58:42 2016 -0700
@@ -108,10 +108,18 @@
      * if the current value {@code == expectedValue},
      * with memory effects as specified by {@link VarHandle#weakCompareAndSetPlain}.
      *
+     * @deprecated This method has plain memory effects but the method
+     * name implies volatile memory effects (see methods such as
+     * {@link #compareAndExchange} and {@link #compareAndSet}).  To avoid
+     * confusion over plain or volatile memory effects it is recommended that
+     * the method {@link #weakCompareAndSetPlain} be used instead.
+     *
      * @param expectedValue the expected value
      * @param newValue the new value
      * @return {@code true} if successful
+     * @see #weakCompareAndSetPlain
      */
+    @Deprecated(since="9")
     public boolean weakCompareAndSet(boolean expectedValue, boolean newValue) {
         return VALUE.weakCompareAndSetPlain(this,
                                             (expectedValue ? 1 : 0),
@@ -119,6 +127,22 @@
     }
 
     /**
+     * Possibly atomically sets the value to {@code newValue}
+     * if the current value {@code == expectedValue},
+     * with memory effects as specified by {@link VarHandle#weakCompareAndSetPlain}.
+     *
+     * @param expectedValue the expected value
+     * @param newValue the new value
+     * @return {@code true} if successful
+     * @since 9
+     */
+    public boolean weakCompareAndSetPlain(boolean expectedValue, boolean newValue) {
+        return VALUE.weakCompareAndSetPlain(this,
+                                            (expectedValue ? 1 : 0),
+                                            (newValue ? 1 : 0));
+    }
+
+    /**
      * Sets the value to {@code newValue},
      * with memory effects as specified by {@link VarHandle#setVolatile}.
      *
--- a/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicInteger.java	Mon Oct 10 15:46:14 2016 -0700
+++ b/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicInteger.java	Mon Oct 10 15:58:42 2016 -0700
@@ -148,15 +148,37 @@
      * if the current value {@code == expectedValue},
      * with memory effects as specified by {@link VarHandle#weakCompareAndSetPlain}.
      *
+     * @deprecated This method has plain memory effects but the method
+     * name implies volatile memory effects (see methods such as
+     * {@link #compareAndExchange} and {@link #compareAndSet}).  To avoid
+     * confusion over plain or volatile memory effects it is recommended that
+     * the method {@link #weakCompareAndSetPlain} be used instead.
+     *
      * @param expectedValue the expected value
      * @param newValue the new value
      * @return {@code true} if successful
+     * @see #weakCompareAndSetPlain
      */
+    @Deprecated(since="9")
     public final boolean weakCompareAndSet(int expectedValue, int newValue) {
         return U.weakCompareAndSwapInt(this, VALUE, expectedValue, newValue);
     }
 
     /**
+     * Possibly atomically sets the value to {@code newValue}
+     * if the current value {@code == expectedValue},
+     * with memory effects as specified by {@link VarHandle#weakCompareAndSetPlain}.
+     *
+     * @param expectedValue the expected value
+     * @param newValue the new value
+     * @return {@code true} if successful
+     * @since 9
+     */
+    public final boolean weakCompareAndSetPlain(int expectedValue, int newValue) {
+        return U.weakCompareAndSwapInt(this, VALUE, expectedValue, newValue);
+    }
+
+    /**
      * Atomically increments the current value,
      * with memory effects as specified by {@link VarHandle#getAndAdd}.
      *
--- a/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicIntegerArray.java	Mon Oct 10 15:46:14 2016 -0700
+++ b/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicIntegerArray.java	Mon Oct 10 15:58:42 2016 -0700
@@ -151,16 +151,39 @@
      * {@code newValue} if the element's current value {@code == expectedValue},
      * with memory effects as specified by {@link VarHandle#weakCompareAndSetPlain}.
      *
+     * @deprecated This method has plain memory effects but the method
+     * name implies volatile memory effects (see methods such as
+     * {@link #compareAndExchange} and {@link #compareAndSet}).  To avoid
+     * confusion over plain or volatile memory effects it is recommended that
+     * the method {@link #weakCompareAndSetPlain} be used instead.
+     *
      * @param i the index
      * @param expectedValue the expected value
      * @param newValue the new value
      * @return {@code true} if successful
+     * @see #weakCompareAndSetPlain
      */
+    @Deprecated(since="9")
     public final boolean weakCompareAndSet(int i, int expectedValue, int newValue) {
         return AA.weakCompareAndSetPlain(array, i, expectedValue, newValue);
     }
 
     /**
+     * Possibly atomically sets the element at index {@code i} to
+     * {@code newValue} if the element's current value {@code == expectedValue},
+     * with memory effects as specified by {@link VarHandle#weakCompareAndSetPlain}.
+     *
+     * @param i the index
+     * @param expectedValue the expected value
+     * @param newValue the new value
+     * @return {@code true} if successful
+     * @since 9
+     */
+    public final boolean weakCompareAndSetPlain(int i, int expectedValue, int newValue) {
+        return AA.weakCompareAndSetPlain(array, i, expectedValue, newValue);
+    }
+
+    /**
      * Atomically increments the value of the element at index {@code i},
      * with memory effects as specified by {@link VarHandle#getAndAdd}.
      *
--- a/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLong.java	Mon Oct 10 15:46:14 2016 -0700
+++ b/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLong.java	Mon Oct 10 15:58:42 2016 -0700
@@ -164,15 +164,37 @@
      * if the current value {@code == expectedValue},
      * with memory effects as specified by {@link VarHandle#weakCompareAndSetPlain}.
      *
+     * @deprecated This method has plain memory effects but the method
+     * name implies volatile memory effects (see methods such as
+     * {@link #compareAndExchange} and {@link #compareAndSet}).  To avoid
+     * confusion over plain or volatile memory effects it is recommended that
+     * the method {@link #weakCompareAndSetPlain} be used instead.
+     *
      * @param expectedValue the expected value
      * @param newValue the new value
      * @return {@code true} if successful
+     * @see #weakCompareAndSetPlain
      */
+    @Deprecated(since="9")
     public final boolean weakCompareAndSet(long expectedValue, long newValue) {
         return U.weakCompareAndSwapLong(this, VALUE, expectedValue, newValue);
     }
 
     /**
+     * Possibly atomically sets the value to {@code newValue}
+     * if the current value {@code == expectedValue},
+     * with memory effects as specified by {@link VarHandle#weakCompareAndSetPlain}.
+     *
+     * @param expectedValue the expected value
+     * @param newValue the new value
+     * @return {@code true} if successful
+     * @since 9
+     */
+    public final boolean weakCompareAndSetPlain(long expectedValue, long newValue) {
+        return U.weakCompareAndSwapLong(this, VALUE, expectedValue, newValue);
+    }
+
+    /**
      * Atomically increments the current value,
      * with memory effects as specified by {@link VarHandle#getAndAdd}.
      *
--- a/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLongArray.java	Mon Oct 10 15:46:14 2016 -0700
+++ b/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLongArray.java	Mon Oct 10 15:58:42 2016 -0700
@@ -151,16 +151,39 @@
      * {@code newValue} if the element's current value {@code == expectedValue},
      * with memory effects as specified by {@link VarHandle#weakCompareAndSetPlain}.
      *
+     * @deprecated This method has plain memory effects but the method
+     * name implies volatile memory effects (see methods such as
+     * {@link #compareAndExchange} and {@link #compareAndSet}).  To avoid
+     * confusion over plain or volatile memory effects it is recommended that
+     * the method {@link #weakCompareAndSetPlain} be used instead.
+     *
      * @param i the index
      * @param expectedValue the expected value
      * @param newValue the new value
      * @return {@code true} if successful
+     * @see #weakCompareAndSetPlain
      */
+    @Deprecated(since="9")
     public final boolean weakCompareAndSet(int i, long expectedValue, long newValue) {
         return AA.weakCompareAndSetPlain(array, i, expectedValue, newValue);
     }
 
     /**
+     * Possibly atomically sets the element at index {@code i} to
+     * {@code newValue} if the element's current value {@code == expectedValue},
+     * with memory effects as specified by {@link VarHandle#weakCompareAndSetPlain}.
+     *
+     * @param i the index
+     * @param expectedValue the expected value
+     * @param newValue the new value
+     * @return {@code true} if successful
+     * @since 9
+     */
+    public final boolean weakCompareAndSetPlain(int i, long expectedValue, long newValue) {
+        return AA.weakCompareAndSetPlain(array, i, expectedValue, newValue);
+    }
+
+    /**
      * Atomically increments the value of the element at index {@code i},
      * with memory effects as specified by {@link VarHandle#getAndAdd}.
      *
--- a/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReference.java	Mon Oct 10 15:46:14 2016 -0700
+++ b/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReference.java	Mon Oct 10 15:58:42 2016 -0700
@@ -127,15 +127,37 @@
      * if the current value {@code == expectedValue},
      * with memory effects as specified by {@link VarHandle#weakCompareAndSetPlain}.
      *
+     * @deprecated This method has plain memory effects but the method
+     * name implies volatile memory effects (see methods such as
+     * {@link #compareAndExchange} and {@link #compareAndSet}).  To avoid
+     * confusion over plain or volatile memory effects it is recommended that
+     * the method {@link #weakCompareAndSetPlain} be used instead.
+     *
      * @param expectedValue the expected value
      * @param newValue the new value
      * @return {@code true} if successful
+     * @see #weakCompareAndSetPlain
      */
+    @Deprecated(since="9")
     public final boolean weakCompareAndSet(V expectedValue, V newValue) {
         return VALUE.weakCompareAndSetPlain(this, expectedValue, newValue);
     }
 
     /**
+     * Possibly atomically sets the value to {@code newValue}
+     * if the current value {@code == expectedValue},
+     * with memory effects as specified by {@link VarHandle#weakCompareAndSetPlain}.
+     *
+     * @param expectedValue the expected value
+     * @param newValue the new value
+     * @return {@code true} if successful
+     * @since 9
+     */
+    public final boolean weakCompareAndSetPlain(V expectedValue, V newValue) {
+        return VALUE.weakCompareAndSetPlain(this, expectedValue, newValue);
+    }
+
+    /**
      * Atomically sets the value to {@code newValue} and returns the old value,
      * with memory effects as specified by {@link VarHandle#getAndSet}.
      *
--- a/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceArray.java	Mon Oct 10 15:46:14 2016 -0700
+++ b/jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceArray.java	Mon Oct 10 15:58:42 2016 -0700
@@ -157,16 +157,39 @@
      * {@code newValue} if the element's current value {@code == expectedValue},
      * with memory effects as specified by {@link VarHandle#weakCompareAndSetPlain}.
      *
+     * @deprecated This method has plain memory effects but the method
+     * name implies volatile memory effects (see methods such as
+     * {@link #compareAndExchange} and {@link #compareAndSet}).  To avoid
+     * confusion over plain or volatile memory effects it is recommended that
+     * the method {@link #weakCompareAndSetPlain} be used instead.
+     *
      * @param i the index
      * @param expectedValue the expected value
      * @param newValue the new value
      * @return {@code true} if successful
+     * @see #weakCompareAndSetPlain
      */
+    @Deprecated(since="9")
     public final boolean weakCompareAndSet(int i, E expectedValue, E newValue) {
         return AA.weakCompareAndSetPlain(array, i, expectedValue, newValue);
     }
 
     /**
+     * Possibly atomically sets the element at index {@code i} to
+     * {@code newValue} if the element's current value {@code == expectedValue},
+     * with memory effects as specified by {@link VarHandle#weakCompareAndSetPlain}.
+     *
+     * @param i the index
+     * @param expectedValue the expected value
+     * @param newValue the new value
+     * @return {@code true} if successful
+     * @since 9
+     */
+    public final boolean weakCompareAndSetPlain(int i, E expectedValue, E newValue) {
+        return AA.weakCompareAndSetPlain(array, i, expectedValue, newValue);
+    }
+
+    /**
      * 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
--- a/jdk/src/java.base/share/classes/java/util/stream/Stream.java	Mon Oct 10 15:46:14 2016 -0700
+++ b/jdk/src/java.base/share/classes/java/util/stream/Stream.java	Mon Oct 10 15:58:42 2016 -0700
@@ -282,7 +282,7 @@
      */
     <R> Stream<R> flatMap(Function<? super T, ? extends Stream<? extends R>> mapper);
 
-    /**
+    /**:
      * Returns an {@code IntStream} consisting of the results of replacing each
      * element of this stream with the contents of a mapped stream produced by
      * applying the provided mapping function to each element.  Each mapped
--- a/jdk/test/java/util/concurrent/tck/AtomicBoolean9Test.java	Mon Oct 10 15:46:14 2016 -0700
+++ b/jdk/test/java/util/concurrent/tck/AtomicBoolean9Test.java	Mon Oct 10 15:58:42 2016 -0700
@@ -162,6 +162,19 @@
     }
 
     /**
+     * repeated weakCompareAndSetPlain succeeds in changing value when equal
+     * to expected
+     */
+    public void testWeakCompareAndSetPlain() {
+        AtomicBoolean ai = new AtomicBoolean(true);
+        do {} while (!ai.weakCompareAndSetPlain(true, false));
+        do {} while (!ai.weakCompareAndSetPlain(false, false));
+        assertFalse(ai.get());
+        do {} while (!ai.weakCompareAndSetPlain(false, true));
+        assertTrue(ai.get());
+    }
+
+    /**
      * repeated weakCompareAndSetVolatile succeeds in changing value when equal
      * to expected
      */
--- a/jdk/test/java/util/concurrent/tck/AtomicInteger9Test.java	Mon Oct 10 15:46:14 2016 -0700
+++ b/jdk/test/java/util/concurrent/tck/AtomicInteger9Test.java	Mon Oct 10 15:58:42 2016 -0700
@@ -162,6 +162,19 @@
     }
 
     /**
+     * repeated weakCompareAndSetPlain succeeds in changing value when equal
+     * to expected
+     */
+    public void testWeakCompareAndSetPlain() {
+        AtomicInteger ai = new AtomicInteger(1);
+        do {} while (!ai.weakCompareAndSetPlain(1, 2));
+        do {} while (!ai.weakCompareAndSetPlain(2, -4));
+        assertEquals(-4, ai.get());
+        do {} while (!ai.weakCompareAndSetPlain(-4, 7));
+        assertEquals(7, ai.get());
+    }
+
+    /**
      * repeated weakCompareAndSetVolatile succeeds in changing value when equal
      * to expected
      */
--- a/jdk/test/java/util/concurrent/tck/AtomicIntegerArray9Test.java	Mon Oct 10 15:46:14 2016 -0700
+++ b/jdk/test/java/util/concurrent/tck/AtomicIntegerArray9Test.java	Mon Oct 10 15:58:42 2016 -0700
@@ -62,6 +62,7 @@
                 () -> aa.compareAndExchange(j, 1, 2),
                 () -> aa.compareAndExchangeAcquire(j, 1, 2),
                 () -> aa.compareAndExchangeRelease(j, 1, 2),
+                () -> aa.weakCompareAndSetPlain(j, 1, 2),
                 () -> aa.weakCompareAndSetVolatile(j, 1, 2),
                 () -> aa.weakCompareAndSetAcquire(j, 1, 2),
                 () -> aa.weakCompareAndSetRelease(j, 1, 2),
@@ -216,6 +217,22 @@
     }
 
     /**
+     * repeated weakCompareAndSetPlain succeeds in changing value when equal
+     * to expected
+     */
+    public void testWeakCompareAndSetPlain() {
+        AtomicIntegerArray aa = new AtomicIntegerArray(SIZE);
+        for (int i = 0; i < SIZE; i++) {
+            aa.set(i, 1);
+            do {} while (!aa.weakCompareAndSetPlain(i, 1, 2));
+            do {} while (!aa.weakCompareAndSetPlain(i, 2, -4));
+            assertEquals(-4, aa.get(i));
+            do {} while (!aa.weakCompareAndSetPlain(i, -4, 7));
+            assertEquals(7, aa.get(i));
+        }
+    }
+
+    /**
      * repeated weakCompareAndSetVolatile succeeds in changing value when equal
      * to expected
      */
--- a/jdk/test/java/util/concurrent/tck/AtomicLong9Test.java	Mon Oct 10 15:46:14 2016 -0700
+++ b/jdk/test/java/util/concurrent/tck/AtomicLong9Test.java	Mon Oct 10 15:58:42 2016 -0700
@@ -162,6 +162,19 @@
     }
 
     /**
+     * repeated weakCompareAndSetPlain succeeds in changing value when equal
+     * to expected
+     */
+    public void testWeakCompareAndSetPlain() {
+        AtomicLong ai = new AtomicLong(1);
+        do {} while (!ai.weakCompareAndSetPlain(1, 2));
+        do {} while (!ai.weakCompareAndSetPlain(2, -4));
+        assertEquals(-4, ai.get());
+        do {} while (!ai.weakCompareAndSetPlain(-4, 7));
+        assertEquals(7, ai.get());
+    }
+
+    /**
      * repeated weakCompareAndSetVolatile succeeds in changing value when equal
      * to expected
      */
--- a/jdk/test/java/util/concurrent/tck/AtomicLongArray9Test.java	Mon Oct 10 15:46:14 2016 -0700
+++ b/jdk/test/java/util/concurrent/tck/AtomicLongArray9Test.java	Mon Oct 10 15:58:42 2016 -0700
@@ -61,6 +61,7 @@
                 () -> aa.compareAndExchange(j, 1, 2),
                 () -> aa.compareAndExchangeAcquire(j, 1, 2),
                 () -> aa.compareAndExchangeRelease(j, 1, 2),
+                () -> aa.weakCompareAndSetPlain(j, 1, 2),
                 () -> aa.weakCompareAndSetVolatile(j, 1, 2),
                 () -> aa.weakCompareAndSetAcquire(j, 1, 2),
                 () -> aa.weakCompareAndSetRelease(j, 1, 2),
@@ -215,6 +216,22 @@
     }
 
     /**
+     * repeated weakCompareAndSetPlain succeeds in changing value when equal
+     * to expected
+     */
+    public void testWeakCompareAndSetPlain() {
+        AtomicLongArray aa = new AtomicLongArray(SIZE);
+        for (int i = 0; i < SIZE; i++) {
+            aa.set(i, 1);
+            do {} while (!aa.weakCompareAndSetPlain(i, 1, 2));
+            do {} while (!aa.weakCompareAndSetPlain(i, 2, -4));
+            assertEquals(-4, aa.get(i));
+            do {} while (!aa.weakCompareAndSetPlain(i, -4, 7));
+            assertEquals(7, aa.get(i));
+        }
+    }
+
+    /**
      * repeated weakCompareAndSetVolatile succeeds in changing value when equal
      * to expected
      */
--- a/jdk/test/java/util/concurrent/tck/AtomicReference9Test.java	Mon Oct 10 15:46:14 2016 -0700
+++ b/jdk/test/java/util/concurrent/tck/AtomicReference9Test.java	Mon Oct 10 15:58:42 2016 -0700
@@ -162,6 +162,19 @@
     }
 
     /**
+     * repeated weakCompareAndSetPlain succeeds in changing value when equal
+     * to expected
+     */
+    public void testWeakCompareAndSetPlain() {
+        AtomicReference<Integer> ai = new AtomicReference<>(one);
+        do {} while (!ai.weakCompareAndSetPlain(one, two));
+        do {} while (!ai.weakCompareAndSetPlain(two, m4));
+        assertEquals(m4, ai.get());
+        do {} while (!ai.weakCompareAndSetPlain(m4, seven));
+        assertEquals(seven, ai.get());
+    }
+
+    /**
      * repeated weakCompareAndSetVolatile succeeds in changing value when equal
      * to expected
      */
--- a/jdk/test/java/util/concurrent/tck/AtomicReferenceArray9Test.java	Mon Oct 10 15:46:14 2016 -0700
+++ b/jdk/test/java/util/concurrent/tck/AtomicReferenceArray9Test.java	Mon Oct 10 15:58:42 2016 -0700
@@ -61,6 +61,7 @@
                 () -> aa.compareAndExchange(j, null, null),
                 () -> aa.compareAndExchangeAcquire(j, null, null),
                 () -> aa.compareAndExchangeRelease(j, null, null),
+                () -> aa.weakCompareAndSetPlain(j, null, null),
                 () -> aa.weakCompareAndSetVolatile(j, null, null),
                 () -> aa.weakCompareAndSetAcquire(j, null, null),
                 () -> aa.weakCompareAndSetRelease(j, null, null),
@@ -215,6 +216,22 @@
     }
 
     /**
+     * repeated weakCompareAndSetPlain succeeds in changing value when equal
+     * to expected
+     */
+    public void testWeakCompareAndSetPlain() {
+        AtomicReferenceArray<Integer> aa = new AtomicReferenceArray<>(SIZE);
+        for (int i = 0; i < SIZE; i++) {
+            aa.set(i, one);
+            do {} while (!aa.weakCompareAndSetPlain(i, one, two));
+            do {} while (!aa.weakCompareAndSetPlain(i, two, m4));
+            assertEquals(m4, aa.get(i));
+            do {} while (!aa.weakCompareAndSetPlain(i, m4, seven));
+            assertEquals(seven, aa.get(i));
+        }
+    }
+
+    /**
      * repeated weakCompareAndSetVolatile succeeds in changing value when equal
      * to expected
      */