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

[Per Minborg]

On Wed, 2 Apr 2025 08:29:54 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> Per Minborg has updated the pull request incrementally with two additional commits since the last revision:
>> 
>>  - Add lazy toSting for StableMap::values
>>  - Make toString for reversed and sublist lazy
>
> src/java.base/share/classes/java/lang/StableValue.java line 2:
> 
>> 1: /*
>> 2:  * Copyright (c) 2024, 2025, Oracle and/or its affiliates. All rights reserved.
> 
> Should this be 2024 or both 2024, 2025 ?

The files that were created in 2024 and were changed in 2025 have both.

> src/java.base/share/classes/java/lang/StableValue.java line 52:
> 
>> 50:  * A stable value is a deferred holder of shallowly immutable content.
>> 51:  * <p>
>> 52:  * A {@code StableValue<T>} can be created using the factory method
> 
> s/can be/is (more direct) -- here and elsewhere

The reason we use the notion "can be" rather than "is" is that a `StableValue` can alternately be created via the `StableValue.of(initialValue)` method. In the latter case, it is already set.

> src/java.base/share/classes/java/lang/StableValue.java line 95:
> 
>> 93:  * <p>
>> 94:  * Note that the holder value can only be set at most once.
>> 95:  * In the example above, the {@code logger} field is declared {@code final} which is
> 
> This is not 100% true -- a final non-static field is not treated as a constant by the VM (at least not yet). Again, I suggest to keep this discussion focused on the fact that `logger` is a `final` stable value field. The holder is created eagerly, but the _content_ is initialized lazily (in the `getLogger` method). So, same similar to `final` (can only be set once) -- but more flexible.

Now that we have removed the VM-specific handling of fields declared as `StableValue`, this is true. I will take a look at improving the wording.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/23972#discussion_r2024403082
PR Review Comment: https://git.openjdk.org/jdk/pull/23972#discussion_r2024424746
PR Review Comment: https://git.openjdk.org/jdk/pull/23972#discussion_r2024431748