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

[John R Rose]

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

>> src/java.base/share/classes/jdk/internal/vm/annotation/IntrinsicCandidate.java line 58:
>> 
>>> 56:  * The HotSpot VM checks, when loading a class, the consistency of recognized
>>> 57:  * methods and {@code @IntrinsicCandidate} annotations, unless the {@code
>>> 58:  * CheckIntrinsics} VM flag is disabled.
>> 
>> <p>
>> Even if an intrinsic is available the VM is not obligated to use it.  For example,
>> the bytecodes of an intrinsic method may be executed by lower tiers of VM
>> execution, while higher tiers may replace the bytecodes with specialized
>> assembly code and/or compiler IR.  Therefore, intrinsic implementors must
>> ensure that non-bytecode execution has (in an application-specific sense)
>> the same results as execution of the actual Java code.  Also, persons not
>> directly involved with maintaining the Java libraries or the HotSpot VM can
>> usually ignore the {@code @IntrinsicCandidate} annotation, when reasoning
>> about the actions of the method.  Such persons must not assume, however,
>> that checks for nulls, out-of-bounds indexes, and wrong types will be performed
>> by the intrinsic, even though normal Java execution always performs such checks.
>
> 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.

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

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