2015/12/4 5:47 -0800, paul.san...@oracle.com:
>> On 3 Dec 2015, at 22:33, Mandy Chung <mandy.ch...@oracle.com> wrote:
>>> On Nov 26, 2015, at 8:22 AM, Paul Sandoz <paul.san...@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
