RFR: 8351565: Implement JEP 502: Stable Values (Preview) [v6]

[Maurizio Cimadamore]

On Thu, 13 Mar 2025 15:48:25 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> Per Minborg has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 246 commits:
>> 
>>  - Merge branch 'master' into implement-jep502
>>  - Clean up exception messages and fix comments
>>  - Rename field
>>  - Rename method and fix comment
>>  - Rework reenterant logic
>>  - Use acquire semantics for reading rather than volatile semantics
>>  - Add missing null check
>>  - Simplify handling of sentinel, wrap, and unwrap
>>  - Fix JavaDoc issues
>>  - Fix members in StableEnumFunction
>>  - ... and 236 more: https://git.openjdk.org/jdk/compare/4e51a8c9...d6e1573f
>
> src/java.base/share/classes/java/lang/StableValue.java line 45:
> 
>> 43: 
>> 44: /**
>> 45:  * A stable value is a shallowly immutable holder of deferred content.
> 
> Is this terminology a leftover from previous JEP iterations? The JEP now says: 
>>  stable values, which are objects that hold immutable data.

Maybe: `A stable value in an holder for shallowly immutable content`.

> src/java.base/share/classes/java/lang/StableValue.java line 330:
> 
>> 328:  * thread safe and guarantee at-most-once-per-input invocation.
>> 329:  *
>> 330:  * <h2 id="miscellaneous">Miscellaneous</h2>
> 
> I'm dubious about a section called "misc" :-)

We can probably move out some of the contents (I left some suggestions) - then move the remaining into api notes?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/23972#discussion_r1993822111
PR Review Comment: https://git.openjdk.org/jdk/pull/23972#discussion_r1993815323