RFR: 8345836: stable annotation documentation is incomplete [v6]

[Jorn Vernee]

On Thu, 9 Jan 2025 07:29:05 GMT, John R Rose <jrose at openjdk.org> 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…
>
> John R Rose has updated the pull request incrementally with one additional commit since the last revision:
> 
>   remove stray word

src/java.base/share/classes/jdk/internal/vm/annotation/Stable.java line 41:

> 39:  * to assume that no more significant changes will occur.  This in
> 40:  * turn enables the VM to optimize uses of the stable variable, treating
> 41:  * them as constant values.  This behavior is a useful building block

> This in turn enables the VM to optimize uses of the stable variable, treating them as constant values.

A mistake I often see people make, is thinking that `@Stable` will always allow the JIT to directly use the value of an instance field. But, this of course depends on the instance holding the field being a constant as well. I feel like this could be stated more explicitly in this text.

Maybe something along the lines of: A instance field load operation has as input an object instance, and as output the value of a particular field. There are two requirements for constant folding such a load operation: 1) the object instance is a constant. 2) the field's value will not change in the future. The `@Stable` annotation influences _only_ the second condition. It is the responsibility of the user of this annotation to make sure that a load operation on a field annotated with `@Stable` has a constant object instance as input, if constant folding of the load operation is desired as a result.

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

PR Review Comment: https://git.openjdk.org/leyden/pull/26#discussion_r1908718864