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

[John R Rose]

On Mon, 21 Apr 2025 20:12:19 GMT, Chen Liang <liach at openjdk.org> wrote:

>> In offline discussion, we noted that the documentation on this annotation does not recommend minimizing the intrinsified section and moving whatever can be done in Java to Java; thus I prepared this documentation update, to shrink a "TLDR" essay to something concise for readers, such as pointing to that list at `vmIntrinsics.hpp` instead of "a list".
>
> Chen Liang has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Refine validation and defensive copying

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.

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

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