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

[John R Rose]

On Thu, 13 Mar 2025 15:22:43 GMT, Per Minborg <pminborg at openjdk.org> wrote:

>> Implement JEP 502.
>> 
>> The PR passes tier1-tier3 tests.
>
> 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

(I am reading the patch, not playing with javadoc or live API, so I might be mis-reading what's going on, so apologies in advance if this is beside the point.)

Comments on visual noise and side effects in `toString`.

`renderWrapped` is clever for a single stable value, but it makes for a very noisy display string, with confusing doubly-nested `[]`, for composite stable values.  I'm talking about `StableFunction` mainly, I guess.

I suggest omitting the inner `[]` for such composites.  A simple boolean on `renderWrapped` will do that trick.  In that case, `renderWrapped` has the job of either presenting a fixed (recognizable) sentinel string, or else forwards, without further editorial comment, to the `toString` of the contained value.

I see that, probably due to prior `java.util` contracts, a stable list or map cannot present a `toString` with unset component values.  A stable list or map uses a “canned” `toString` method that calls `get`, which must force all component values to be evaluated before the `toString` can be printed.

This may greatly annoy users of IDEs, which invoke `toString` (via JVMTI) to display program states.  IDE users don’t expect mere observation of program states to change program states.  This may be a blocker for some would-be adopters of `StableValue`.

Just as `WeakHashMap` bends the `Map` API (regarding `equals`), I think `StableValue` composites should bend the `List` and `Map` APIs, regarding `toString`.  Sometimes the contracts have to be bent for the whole design to fit together.

I think the basic rule should be that the `toString` of stable-whatever should have a little "noise" around the outside, to show that it is not just a bare value, but wherever a wrapped value is, that wrapped value should be presented as directly as possible.  Also, the wrapped value should not be forced, but rather a set, recognizable string (such as `<unset>` or `.unset`) should appear in place of the value string.

At the very least, the presence of side effects in `toString`, an unusual condition, needs to be documented prominently, where applicable.

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

PR Comment: https://git.openjdk.org/jdk/pull/23972#issuecomment-2727094395