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

[Jaikiran Pai]

On Wed, 30 Apr 2025 22:26:30 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 with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains eight additional commits since the last revision:
> 
>  - Move intrinsic to be a subsection; just one most common function of the annotation
>  - Merge branch 'master' of https://github.com/openjdk/jdk into doc/intrinsic-candidate
>  - Merge branch 'master' of https://github.com/openjdk/jdk into doc/intrinsic-candidate
>  - Update src/java.base/share/classes/jdk/internal/vm/annotation/IntrinsicCandidate.java
>    
>    Co-authored-by: Raffaello Giulietti <raffaello.giulietti at oracle.com>
>  - Shorter first sentence
>  - Updates, thanks to John
>  - Refine validation and defensive copying
>  - 8355223: Improve documentation on @IntrinsicCandidate

src/java.base/share/classes/jdk/internal/vm/annotation/IntrinsicCandidate.java line 50:

> 48:  * For example, the bytecodes of a candidate method may be executed by lower
> 49:  * compilation tiers of VM execution, while higher compilation tiers may replace
> 50:  * the bytecodes with specialized assembly code and/or compiler IR.  Therefore,

> while higher compilation tiers may replace the bytecodes with specialized assembly code and/or compiler IR

Is there ever a case, where for a `@IntrinsicCandidate` method, the runtime will choose to execute the instrinsic for that method for a certain duration and then at a later point in time replace the intrinsic with compiler generated code? In other words, once the runtime executes the intrinsic implementation for a `@IntrinsicCandidate` method, will the method's implementation be switched to anything else during the lifetime of an application?

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

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