RFR: 8345836: stable annotation documentation is incomplete

[Alex Buckley]

Hi John, a few comments.

> A field may be annotated as "stable" to indicate that it is a
> <em>stable variable</em>, expected to change value at most once.

Saying "at most once" suggests that changing the value zero times is A+ 
reasonable behavior. But it's not reasonable, given the policy of 
treating only non-default values of stable variables as foldable. I 
think it would be better to say: "expected to change value exactly 
once." The strictness of this phrase (versus the looser "at most once") 
sets the stage as firmly as possible for the exhortations, later, 
against multiple assignment.

> Fields which are declared {@code final} may also be annotated as
> stable. Since final fields already behave as stable values,
(The phrase "stables values" should be "stable variables"; later, the 
phrase "stable value" should be "stable variable".)

I got a sense here that stable variables are the fundamental construct, 
but aren't they more limited? `static final int x = 0;` would be 
eligible for constant folding but `@Stable int y = 0;` would not. Zero 
may be an uninteresting value, but it's not quite as uninteresting and 
un-fold-worthy as false.

> As very simple example, a boolean variable is constant-folded only
> when it is set to {@code true}.  Even this simple behavior is
> sometimes useful for recording a permanent one-shot state change,

It's a little hard to figure out if "behavior" refers to the constant 
folding or the assignment-to-true. I also got the sense that the 
constant folding occurs _as an immediate result of_ the assignment. It 
might be better to spell out the perspective: "As a simple example of 
constant folding, the HotSpot VM may constant fold a boolean variable if 
the variable is `true`. This means that application code can record a 
permanent one-shot state change in such a way that the compiler can 
remove dead code associated with the initial state." I would also place 
this paragraph ahead of the story for array-typed stable variables.

Alex

On 12/9/2024 3:58 PM, John R Rose wrote:
> The javadoc for jdk.internal.vm.annotation.Stable is incomplete.
> 
> The existing documentation gives an over-simple user model,
> and does not explain how it is implemented.
> Proposed new documentation will detail how the annotation
> is implemented, and how it may be used correctly.
> 
> The improved documentation will makes it easier for JDK programmers
> to use the annotation more aggressively, and more confidently.
> 
> This is a first cut.  Please comment…
> 
> -------------
> 
> Commit messages:
>   - 8345836: stable annotation documentation is incomplete
> 
> Changes: https://git.openjdk.org/leyden/pull/26/files
>    Webrev: https://webrevs.openjdk.org/?repo=leyden&pr=26&range=00
>    Issue: https://bugs.openjdk.org/browse/JDK-8345836
>    Stats: 172 lines in 1 file changed: 135 ins; 0 del; 37 mod
>    Patch: https://git.openjdk.org/leyden/pull/26.diff
>    Fetch: git fetch https://git.openjdk.org/leyden.git pull/26/head:pull/26
> 
> PR: https://git.openjdk.org/leyden/pull/26