RFR: 8365428: Unclear comments on java.lang.invoke Holder classes

[Ioi Lam]

On Sun, 31 Aug 2025 18:49:20 GMT, Ioi Lam <iklam at openjdk.org> wrote:

>> java.lang.invoke has a few Holder classes in DirectMethodHandle, DelegatingMethodHandle, Invokers, and LambdaForm.
>> 
>> Currently, the comments simply refer to "Placeholder for xxx generated ahead-of-time".
>> 
>> However, they carry executed bytecode and show up in flame graphs. The current comments are definitely not sufficient for their details and purposes.
>> 
>> To address these shortcomings, I improved the comments on the Holder classes and GenerateJLIClassesHelper to briefly describe the generation process. In addition, I improved the comments on BoundMethodHandle to provide a more efficient overview.
>
> src/java.base/share/classes/java/lang/invoke/GenerateJLIClassesHelper.java line 66:
> 
>> 64: ///
>> 65: /// Currently, `GenerateJLIClassesPlugin` and the AOT process pre-generate with
>> 66: /// `GenerateJLIClassesHelper`. `GenerateJLIClassesPlugin` runs for JDK builds;
> 
> How about:
> 
> 
> // Currently, `GenerateJLIClassesHelper` is invoked by `GenerateJLIClassesPlugin` when 
> // creating a modular JDK image. It it also invoked when generating an AOT cache.
> 
> 
> ("Creating a modular JDK image" covers both the case when the JDK is built, or when you use jlink to create a custom JDK image).

I think we can add the following to tie the difference pieces together.


// When creating a modular JDK image, the generation of the Holder and Species classes
// are controlled by the file `jdk/tools/jlink/internal/plugins/default_jli_trace.txt` in
// `$JAVA_HOME/lib/modules`. `default_jli_trace.txt` itself is generated in the build
// process of the JDK.
//
// To list all the Species classes in a JDK image
//
// jimage list $JAVA_HOME/lib/modules | grep MethodHandle.Species
//
// The following 4 classes are also generated by `GenerateJLIClassesHelper`
//  -  java.lang.invoke.Invokers$Holder
//  -  java.lang.invoke.DirectMethodHandle$Holder
//  -  java.lang.invoke.DelegatingMethodHandle$Holder
//  -  java.lang.invoke.LambdaForm$Holder
//
// When creating an AOT cache, information for generating the Holder and Species classes
// are captured and stored inside the AOT configuration file (with similar data as captured
// in the `default_jli_trace.txt` file), and are accessed with the C++ `FinalImageRecipes` class.


I think just mentioning `FinalImageRecipes` is enough. For people who want to dig deeper, they
can read up the implementation of `FinalImageRecipes`.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/27010#discussion_r2312590058