RFR: 8314480: Memory ordering spec updates in java.lang.ref [v13]

[Brent Christian]

On Sat, 16 Mar 2024 04:20:44 GMT, Stuart Marks <smarks at openjdk.org> wrote:

>> Brent Christian has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   further tweaks to reachability
>
> src/java.base/share/classes/java/lang/ref/Reference.java line 402:
> 
>> 400:      * method is called, the garbage collector may already be in the process of
>> 401:      * (or already completed) clearing and/or enqueueing this reference.
>> 402:      *
> 
> Either this is an extra blank line, or you need a `<p>` here.

Removed the blank line; I thought it looked better for the API note to be a single paragraph.

> src/java.base/share/classes/java/lang/ref/Reference.java line 496:
> 
>> 494:      * Actions in a thread prior to calling
>> 495:      * {@code enqueue} <b><i>successfully</i></b>
>> 496:      * <a href="{@docRoot}/java.base/java/util/concurrent/package-summary.html#MemoryVisibility"><i>happen-before</i></a>
> 
> Editorial. The text here says
> 
>> Actions in a thread prior to calling `enqueue` successfully _happen-before_ the reference is removed...
> 
> This could be confusing, because "successfully" might be read to modify "happen-before". This raises questions such as "Is it possible for something to happen-before unsuccessfully?" Of course you want "successfully" to modify "enqueue" because you're relying on the definition of "successful" given previously. Suggest rewording:
> 
>> Actions in a thread prior to successful calls to `enqueue` _happen-before_ the reference is removed...

Updated, though I made it singular ("a successful call to enqueue"), since we talk about "the" reference being removed.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/16644#discussion_r1529365850
PR Review Comment: https://git.openjdk.org/jdk/pull/16644#discussion_r1529364758