RFR: 8345836: stable annotation documentation is incomplete

[Chen Liang]

On Tue, 10 Dec 2024 10:02:04 GMT, Maurizio Cimadamore <mcimadamore 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…
>
> src/java.base/share/classes/jdk/internal/vm/annotation/Stable.java line 196:
> 
>> 194:  * recent" value observed by the interpreter or less-optimized code.
>> 195:  * <p>
>> 196:  * For all these reasons, a user who bends the rules for a stable
> 
> I've cases in the JDK where a stable fields could, under race, be assigned to objects that are semantically equivalent, but whose identity is distinct. Would you say this is a good use of `@Stable` ? In FFM we took extra precaution and deduplicated the identity by using a concurrent hash map -- but is this required?

I think so; we have benign races for non-stable fields like `Class.reflectionFactory`. However, sometimes sharing the same object avoids redundant cache computation. It is ultimately a tradeoff between synchronization and lock overheads and the applicability of cache.

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

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