On Wed, 30 Apr 2025 22:26:30 GMT, Chen Liang <li...@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.giulie...@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 33: > 31: * The {@code @IntrinsicCandidate} indicates that an annotated method is > 32: * recognized by {@code vmIntrinsics.hpp} for special treatment by the > HotSpot > 33: * VM, unlike the other methods. The HotSpot VM checks, when loading a > class, /, unlike the other methods/s/the other/other/ If you want something at the top that teaches about "the other methods", maybe say something like: > Normally, the VM executes methods using only their bytecodes (or JNI > definitions), but the VM is (in addition) allowed to use specialized code or > analysis logic for methods marked as intrinsics. Thus, intrinsic calls can > be replaced or modified or specially optimized by the VM. But those points will be covered further down, so maybe not. More concisely: s/, unlike the other methods/, unlike normal methods, which depend only on bytecodes or native entry points for their meaning to the VM/ Or just: s/, unlike the other methods// Also, s/The HotSpot VM checks, when loading a class,/When loading a class, the HotSpot VM checks/ (fewer commas, better logical flow) ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/24777#discussion_r2093593792
