Reference.reachabilityFence

[Paul Sandoz]

> On 7 Dec 2015, at 18:58, mark.reinhold at oracle.com wrote:
> 
> 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.

Thanks, moved.


> 
> 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
> 

Updated:

http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8133348-reachability-fence-jdk/webrev/src/java.base/share/classes/java/lang/ref/Reference.java.sdiff.html <http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8133348-reachability-fence-jdk/webrev/src/java.base/share/classes/java/lang/ref/Reference.java.sdiff.html>

I think there is an opportunity to add further examples, but i would like to take a swing at that later on.


>  - 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?
> 

I doubt there will be another kind of reference fence, but it could be used in conjunction with other memory fences (currently on VarHandles) and if static imports are used it might look rather out of place as to what fence “fence” actually refers to. That is why i prefer the longer more descriptive name.

Paul.