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

[Chen Liang]

On Tue, 22 Apr 2025 18:42:01 GMT, John R Rose <jrose at openjdk.org> wrote:

>> And for arrays, a footnote might be appropriate:
>> 
>> 
>> <p>
>> For some highly optimized algorithms, it may be impractical to ensure that array
>> data is read or written only once by the intrinsic.  If the caller of the intrinsic
>> cannot guarantee that such array data is unshared, then the caller must also
>> document the effects of race conditions on it.  (Such a race occurs when another
>> thread writes the array data during the execution of the intrinsic.)  For example,
>> the documentation can simply say that the result is undefined if a race happens.
>> 
>> 
>> And maybe, after that, something more about type safety:
>> 
>> 
>> <p>
>> In no case may any intrinsic be allowed to perform an operation that fails to be
>> type safe.  It must not indirect a null pointer; it must not access a field or method
>> on an object which does not possess that field or method; it must not access
>> an element of an array not actually present in the array; and it must not
>> manipulate managed references in a way that prevents the GC from managing
>> them.  The caller of the intrinsic is fully responsible for preventing every kind
>> of type safety violation, in the case (the common case) that the intrinsic itself
>> does not itself somehow prevent the violation.
>
> In the new design, the above "footnotes" go at the bottom.  They explain why the rules prescribed at the top are important.  In effect, inform aggressive implementors how far they may bend those rules.  Sometimes the rules do get bent, sometimes to allow unspecified behavior, but never so far as to allow a type safety violation.

I still believe these information are important and better kept inline; inlined them with blockquote tags.

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

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