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

[Roger Riggs]

On Wed, 21 May 2025 21:28:07 GMT, Chen Liang <liach at openjdk.org> wrote:

>> 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.

This unnecessary detail goes will beyond the description of the annotation and is more of a design doc for VM implementation so this is not really the best place for it.

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

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