RFR: 8345836: stable annotation documentation is incomplete

[Per Minborg]

On Mon, 9 Dec 2024 23:53:31 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…

It might be worth mentioning that primitive types could be held in a wrapper class (rather than as a primitive value) if the default values are important to capture and constant-fold.

Another thing that we could talk about when it comes to stable variables initialized outside `<init>` and `<clinit>` in a multi-threaded scenario is that code can use CAS operations when initializing the stable variable to uphold the update-at-most-once invariant and that readers can use acquire/release or volatile semantics when reading the stable variable. This ensures consistency across threads while still allowing VM optimizations.

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

PR Comment: https://git.openjdk.org/leyden/pull/26#issuecomment-2530704189