Reference.reachabilityFence

[mark.reinhold at oracle.com]

2015/12/4 5:47 -0800, paul.sandoz at oracle.com:
>> On 3 Dec 2015, at 22:33, Mandy Chung <mandy.chung at oracle.com> wrote:
>>> On Nov 26, 2015, at 8:22 AM, Paul Sandoz <paul.sandoz at oracle.com> wrote:
>>> http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8133348-reachability-fence-jdk/webrev/
>>> http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8133348-reachability-fence-hotspot/webrev/
>>> 
>>> There is now more documentation on Reference (copied and suitable
>>> rearranged from 166 Fences.java). The method name remains the same.
>> 
>> I think the addition to the Reference class specification should
>> belong to the reachabilityFence method specification.  Any reason why
>> not?
> 
> I thought it would be more visible in the JavaDoc, as it’s there
> upfront. The api note may get larger if we include some additional
> real world examples. I don’t have a strong opinion on this, if yours
> is stronger i will move it :-)

I agree with Mandy -- the new text about fences belongs in the method
doc, not the class doc.

Further comments, mostly minor:

  - In the opening sentence, s/strongly reachability/strong reachability/.

  - I'd remove the phrase "As illustrated in the sample usages of the
    api note below" from the normative text.  The API note follows
    immediately; there's no need to point to it.

  - s/a Java Virtual Machine/the virtual machine/

  - s/A garbage collector/The garbage collector/

  - s/call to/invocation of/

  - s/ for example /, for example,/

  - s/if it were OK/if it were acceptable/  ("OK" is a bit too informal)

  - s!<em>in general</em>!, in general,!

  - s/Fences.reachabilityFence/Reference.reachabilityFence/ in the examples

  - I now agree with you and Doug about calling this a "fence".  Can we
    just name it "fence" rather than the wordier "reachabilityFence"?
    Looking at a typical invocation,

        Reference.reachabilityFence();

    seems a bit redundant while

        Reference.fence();

    reads quite nicely.  Is there, or will there ever be, any other kind
    of reference-related fence?

- Mark