RFR: 8355223: Improve documentation on @IntrinsicCandidate [v6]

[Chen Liang]

On Fri, 16 May 2025 19:45:16 GMT, John R Rose <jrose at openjdk.org> wrote:

> Or just: s/, unlike the other methods//

Removed mention of "the other methods".

> src/java.base/share/classes/jdk/internal/vm/annotation/IntrinsicCandidate.java line 90:
> 
>> 88:  * intrinsic.)  For example, the documentation can simply say that the result is
>> 89:  * undefined if a race happens.  However, race conditions must not lead to
>> 90:  * program failures or type safety breaches, as listed above.
> 
> Maybe add a teaching paragraph:
> 
>> Reasoning about such race conditions is difficult, but it is a necessary skill when working with intrinsics that can observe racing shared variables.  One example of a tolerable race is a repeated read of a shared reference.  This only works if the algorithm takes no action based on the first read, other than deciding to perform the second read; it must "forget what it saw" in the first read.  This is why the array-mismatch intrinsics can sometimes report a tentative search hit (maybe using vectorized code), which can then be confirmed (by scalar code) as the caller makes a fresh and independent observation. 
> 
> (This is done when the array mismatch logic performs NaN-folding.  I just noticed that the NaN-folding code in ArraysSupport is slightly incorrect with respect to races!)

I have appened this teaching paragraph also as a blockquote inlined note after this current paragraph.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/24777#discussion_r2101197921
PR Review Comment: https://git.openjdk.org/jdk/pull/24777#discussion_r2101199974