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

[Brent Christian]

On Thu, 22 Feb 2024 23:14:37 GMT, Brent Christian <bchristi at openjdk.org> wrote:

>> I note that the adjective(s) (un)successful and the adverb(s) (un)successfully are used at several places in these comments, it might makes sense to use those terms here as well such that the documentation in internally consistent in its use of success or failure of actions. In particular, if this terminology is consistent with precedent in the official JLS spec.
>> 
>> However, I note that there are places where these terms are italicized and places where they aren't. I am not sure I follow the convention for italicization. In general, the first use (i.e. introduction) of a term that the reader might want to pay attention to calls for italicization when documents are read sequentially, such as in research papers. These javadoc specs will usually not be read in sequentially. But considering that someone does read them in order, I'd suggest italicizing only the first use of the term or, if not, then perhaps none. Alternatively, you might want to italicize all uses (but why?).
>
> Thanks for finding my misspelling, djelinski. 👍

The use of "(un)successful(ly)" in relation to `Reference.enqueue()` is quite deliberate (and builds on the previous wording, "successful").

The intention was to use it consistently (is that not the case somewhere?). For example, it's also used in the new **Memory Consistency Properties** section of the `java.lang.ref` package docs ("The enqueueing of a reference...by a successful call to `Reference.enqueue()`...").

A "successful call to `enqueue()`" is meant to be shorthand for:
"the reference has been enqueued, and the enqueuing was performed by the `enqueue()` method (rather than by the garbage collector). Therefore there is a _happens-before_ edge between the `enqueue()` method call and the dequeuing of the Reference (whereas there would not be this _happens-before_ if the GC had already enqueued the Reference at the time of the `enqueue()` call)."

The text emphasis with italics is to indicate this added significance of the result of the `enqueue()` call -- ala `happens-before`.

I'm not aware of a similar scenario covered in the JLS, so AFAIK there is not precedent to be consistent with in that regard.

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

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