8252529: Unsafe Documentation around Barrier Methods Inaccurate

Reviewed-by: psandoz

Author: Ian Graves

src/java.base/share/classes/jdk/internal/misc/Unsafe.java

@@ -3412,9 +3412,8 @@ public final long getAndBitwiseXorLongAcquire(Object o, long offset, long mask)
      * Corresponds to C11 atomic_thread_fence(memory_order_acquire)
      * (an "acquire fence").
      *
-     * A pure LoadLoad fence is not provided, since the addition of LoadStore
-     * is almost always desired, and most current hardware instructions that
-     * provide a LoadLoad barrier also provide a LoadStore barrier for free.
+     * Provides a LoadLoad barrier followed by a LoadStore barrier.
+     *
      * @since 1.8
      */
     @HotSpotIntrinsicCandidate
@@ -3427,9 +3426,9 @@ public final long getAndBitwiseXorLongAcquire(Object o, long offset, long mask)
      * Corresponds to C11 atomic_thread_fence(memory_order_release)
      * (a "release fence").
      *
-     * A pure StoreStore fence is not provided, since the addition of LoadStore
-     * is almost always desired, and most current hardware instructions that
-     * provide a StoreStore barrier also provide a LoadStore barrier for free.
+     * Provides a StoreStore barrier followed by a LoadStore barrier.
+     *
+     *
      * @since 1.8
      */
     @HotSpotIntrinsicCandidate
@@ -3450,6 +3449,11 @@ public final long getAndBitwiseXorLongAcquire(Object o, long offset, long mask)
     /**
      * Ensures that loads before the fence will not be reordered with
      * loads after the fence.
+     *
+     * @implNote
+     * This method is operationally equivalent to {@link #loadFence()}.
+     *
+     * @since 9
      */
     public final void loadLoadFence() {
         loadFence();
@@ -3458,6 +3462,11 @@ public final void loadLoadFence() {
     /**
      * Ensures that stores before the fence will not be reordered with
      * stores after the fence.
+     *
+     * @implNote
+     * This method is operationally equivalent to {@link #storeFence()}.
+     *
+     * @since 9
      */
     public final void storeStoreFence() {
         storeFence();