[RFR] Docfix for Unsafe RE Fence Methods (remake from [PATCH])

[Paul Sandoz]

If memory serves me correctly we added these methods for completeness when doing VarHandles, but we deferred any intrinsic work (do it when really needed).

This looks good to me. Minor tweak. I would recommend using an @implNote to be clear this not permanent behavior and could change e.g.:

* @implNote
* This implementation is operationally equivalent to {@link #loadFence()}

No need for another review, just send me the patch. I can sponsor it for you.

Paul. 

> On Sep 1, 2020, at 9:52 AM, Ian Graves <ian.graves at oracle.com> wrote:
> 
> All,
> 
> Per an earlier discussion submitted with a patch but without a JBS entry (my fault!).
> 
> This is an RFR to update the docs in Unsafe for some of the fence methods to better reflect the current state of affairs in the file. Updating the verbiage to make it less opinionated per some previous comments (thanks, Hans!). 
> 
> JBS Link: https://bugs.openjdk.java.net/browse/JDK-8252529
> 
> Patch follows my signature.
> 
> Thanks!
> 
> 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	Tue Sep 01 11:44:42 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,9 @@
>      * 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,10 @@
>     /**
>      * Ensures that loads before the fence will not be reordered with
>      * loads after the fence.
> +     *
> +     * This method is operationally equivalent to {@link #loadFence()}.
> +     *
> +     * @since 9
>      */
>     public final void loadLoadFence() {
>         loadFence();
> @@ -3458,6 +3461,10 @@
>     /**
>      * Ensures that stores before the fence will not be reordered with
>      * stores after the fence.
> +     *
> +     * This method is operationally equivalent to {@link #storeFence()}.
> +     *
> +     * @since 9
>      */
>     public final void storeStoreFence() {
>         storeFence();