[PATCH] Docfix for Unsafe regarding fence methods

[Ian Graves]

Looks like the patch attachment was stripped. I’ll include it inline:
—Ian


diff -r 3e9d813ff918 src/java.base/share/classes/jdk/internal/misc/Unsafe.java
--- a/src/java.base/share/classes/jdk/internal/misc/Unsafe.java	Thu Aug 27 20:20:39 2020 +0200
+++ b/src/java.base/share/classes/jdk/internal/misc/Unsafe.java	Fri Aug 28 15:21:01 2020 -0500
@@ -3412,9 +3412,8 @@
      * 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,8 @@
      * 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 +3448,12 @@
     /**
      * Ensures that loads before the fence will not be reordered with
      * loads after the fence.
+     *
+     * This method is operationally equivalent to {@link #loadFence()}
+     * as most hardware instructions that provide a LoadLoad barrier
+     * provide a LoadStore barrier for free.
+     *
+     * @since 9
      */
     public final void loadLoadFence() {
         loadFence();
@@ -3458,6 +3462,12 @@
     /**
      * Ensures that stores before the fence will not be reordered with
      * stores after the fence.
+     *
+     * This method is operationally equivalent to {@link #storeFence()}
+     * as most hardware instructions that provide a StoreStore barrier
+     * provide a LoadStore barrier for free.
+     *
+     * @since 9
      */
     public final void storeStoreFence() {
         storeFence();


> On Aug 28, 2020, at 3:12 PM, Ian Graves <ian.graves at oracle.com> wrote:
> 
> Hello,
> 
> When reviewing some of the documentation in jdk.internal.misc.Unsafe, it appears that there is some dated information regarding the availability of “pure barrier” methods (i.e. pure StoreStoreFence sans a LoadStore barrier). When the storeFence() and loadFence() methods were implemented the pure variations (loadLoadFence(), storeStoreFence()) were not implemented and the documentation indicated as much. This is no longer the case. 
> 
> I’ve included a patch with this email that updates the docs to reflect the new state of affairs here as well as indicate some implementation details as to how the pure variants utilize the impure original methods.
> 
> Thanks!
> 
> Ian
>