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

[Stuart Marks]

On Mon, 13 Nov 2023 22:31:16 GMT, Brent Christian <bchristi at openjdk.org> wrote:

> Classes in the `java.lang.ref` package would benefit from an update to bring the spec in line with how the VM already behaves. The changes would focus on _happens-before_ edges at some key points during reference processing.
> 
> A couple key things we want to be able to say are:
> - `Reference.reachabilityFence(x)` _happens-before_ reference processing occurs for 'x'.
> - `Cleaner.register()` _happens-before_ the Cleaner thread runs the registered cleaning action.
> 
> This will bring Cleaner in line (or close) with the memory visibility guarantees made for finalizers in [JLS 17.4.5](https://docs.oracle.com/javase/specs/jls/se18/html/jls-17.html#jls-17.4.5):
> _"There is a happens-before edge from the end of a constructor of an object to the start of a finalizer (§12.6) for that object."_

src/java.base/share/classes/java/lang/ref/Reference.java line 564:

> 562:      * {@code reachabilityFence(x)}
> 563:      * <a href="{@docRoot}/java.base/java/util/concurrent/package-summary.html#MemoryVisibility"><i>happen-before</i></a>
> 564:      * the garbage collector clears any reference to {code x}.

This is a fairly low-level specification, so the relationship described here is "reachabilityFence **hb** clearing". The relationships "clearing **hb** enqueue" and "enqueue **hb** dequeue" are described elsewhere. Thus the mention of Cleaner above seems misplaced.

However, the whole chain of relationships

> RF **hb** clearing **hb** enqueue **hb** dequeue **hb** cleaning-action

is important. Should this be described somewhere?

src/java.base/share/classes/java/lang/ref/ReferenceQueue.java line 187:

> 185:      * {@link Reference#enqueue()} instead of by the garbage collector, its
> 186:      * former referent (which has since been cleared) could still be strongly
> 187:      * reachable.

See my comments on the corresponding Reference.enqueue() apiNote. I'm not sure we want to have this issue sprinkled around in the apiNotes for several methods, including others here on ReferenceQueue.

If we do want to address this issue -- and it's not clear to me that we do -- then perhaps we should do it in a central location?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16644#discussion_r1394941127
PR Review Comment: https://git.openjdk.org/jdk/pull/16644#discussion_r1394944893