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

@@ -108,16 +108,40 @@ public class AtomicBoolean implements java.io.Serializable {
      * 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),
                                             (newValue ? 1 : 0));
     }
 
+    /**
+     * 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}.

jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicInteger.java

@@ -148,14 +148,36 @@ public class AtomicInteger extends Number implements java.io.Serializable {
      * 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}.

jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicIntegerArray.java

@@ -151,15 +151,38 @@ public class AtomicIntegerArray implements java.io.Serializable {
      * {@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}.

jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLong.java

@@ -164,14 +164,36 @@ public class AtomicLong extends Number implements java.io.Serializable {
      * 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}.

jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLongArray.java

@@ -151,15 +151,38 @@ public class AtomicLongArray implements java.io.Serializable {
      * {@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}.

jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReference.java

@@ -127,14 +127,36 @@ public class AtomicReference<V> implements java.io.Serializable {
      * 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}.

jdk/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceArray.java

@@ -157,15 +157,38 @@ public class AtomicReferenceArray<E> implements java.io.Serializable {
      * {@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

jdk/src/java.base/share/classes/java/util/stream/Stream.java

@@ -282,7 +282,7 @@ public interface Stream<T> extends BaseStream<T, Stream<T>> {
      */
     <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

jdk/test/java/util/concurrent/tck/AtomicBoolean9Test.java

@@ -161,6 +161,19 @@ public class AtomicBoolean9Test extends JSR166TestCase {
         assertEquals(true, ai.get());
     }
 
+    /**
+     * 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

jdk/test/java/util/concurrent/tck/AtomicInteger9Test.java

@@ -161,6 +161,19 @@ public class AtomicInteger9Test extends JSR166TestCase {
         assertEquals(7, ai.get());
     }
 
+    /**
+     * 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

jdk/test/java/util/concurrent/tck/AtomicIntegerArray9Test.java

@@ -62,6 +62,7 @@ public class AtomicIntegerArray9Test extends JSR166TestCase {
                 () -> 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 @@ public class AtomicIntegerArray9Test extends JSR166TestCase {
         }
     }
 
+    /**
+     * 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

jdk/test/java/util/concurrent/tck/AtomicLong9Test.java

@@ -161,6 +161,19 @@ public class AtomicLong9Test extends JSR166TestCase {
         assertEquals(7, ai.get());
     }
 
+    /**
+     * 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

jdk/test/java/util/concurrent/tck/AtomicLongArray9Test.java

@@ -61,6 +61,7 @@ public class AtomicLongArray9Test extends JSR166TestCase {
                 () -> 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),
@@ -214,6 +215,22 @@ public class AtomicLongArray9Test extends JSR166TestCase {
         }
     }
 
+    /**
+     * 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

jdk/test/java/util/concurrent/tck/AtomicReference9Test.java

@@ -161,6 +161,19 @@ public class AtomicReference9Test extends JSR166TestCase {
         assertEquals(seven, ai.get());
     }
 
+    /**
+     * 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

jdk/test/java/util/concurrent/tck/AtomicReferenceArray9Test.java

@@ -61,6 +61,7 @@ public class AtomicReferenceArray9Test extends JSR166TestCase {
                 () -> 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),
@@ -214,6 +215,22 @@ public class AtomicReferenceArray9Test extends JSR166TestCase {
         }
     }
 
+    /**
+     * 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