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

[Chen Liang]

On Tue, 20 May 2025 06:08:37 GMT, Jaikiran Pai <jpai at openjdk.org> wrote:

>> 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 39:
> 
>> 37:  * <h2 id="intrinsification">Intrinsification</h2>
>> 38:  * The most frequently special treatment is intrinsification, which replaces a
>> 39:  * candidate method's body, bytecode or native, with handwritten platform
> 
> Is this sentence missing the word "code" after "native"? Should it have been:
> 
>> bytecode or native code, ...

This is referring to native method's bodies. I think "bytecode or native" is sufficient to summarize the executable method body in the Java Language/Virtual Machine Specification.

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

We cannot rule it out, but this sentence begins "for example" meaning this is just one scenario and is not exhaustive.

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

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