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

[Ioi Lam]

On Fri, 29 Aug 2025 19:17:23 GMT, Chen Liang <liach 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.

I think it will be useful to describe how the Holder and Species classes are used to avoid bytecode generation. For example, where do we look up methods inside Holder? When we do a Class.forName() for a particular Species class?

src/java.base/share/classes/java/lang/invoke/GenerateJLIClassesHelper.java line 61:

> 59: /// which method types are used, so our generation matches the actual usage.
> 60: ///
> 61: /// This does not have comprehensive coverage of all lambda forms created in a

How about:

`This does not cover all lambda forms created in ...`

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).

src/java.base/share/classes/java/lang/invoke/GenerateJLIClassesHelper.java line 76:

> 74: /// the classes for linkage in assembly phase; see `regeneratedClasses.hpp`.
> 75: ///
> 76: /// VarHandle has a similar pre-generation system for its forms, except it is

`[VarHandle]` ?

src/java.base/share/classes/java/lang/invoke/GenerateJLIClassesHelper.java line 356:

> 354:     }
> 355: 
> 356:     /// Returns a map of class name in internal form to the corresponding class

`class name` -> `class names`

src/java.base/share/classes/java/lang/invoke/LambdaForm.java line 143:

> 141: 
> 142:     /// Represents the "basic" types that exist in the JVM linkage and stack/locals.
> 143:     /// All subwords (boolean, byte, char, short) are promoted to int.

Existing: a few lines below. I think the `// all primitive types` comment should be deleted.


D_TYPE('D', double.class, Wrapper.DOUBLE, TypeKind.DOUBLE), // all primitive types

src/java.base/share/classes/java/lang/invoke/LambdaForm.java line 1736:

> 1734: 
> 1735:     /// Holds pre-generated bytecode for common lambda forms.
> 1736:     /// This class may be substituted by a generated class from [GenerateJLIClassesHelper].

// This class may be substituted in the JDK's modules image, or in an AOT cache, by a version
// generated by [GenerateJLIClassesHelper].

src/java.base/share/classes/java/lang/invoke/LambdaForm.java line 1745:

> 1743:     /// ```
> 1744:     /// javap -c -p -v java.lang.invoke.LambdaForm\$Holder
> 1745:     /// ```

Unfortunately, there's currently no way to use `javap` to display the contents of the re-generated version of the Holder classes in an AOT code. You can use `-Xlog:aot+map=trace`, but the information is not very easy to parse.

I filed [JDK-8366485](https://bugs.openjdk.org/browse/JDK-8366485) - Display the contents of generated classes in AOT cache

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

PR Comment: https://git.openjdk.org/jdk/pull/27010#issuecomment-3240353292
PR Review Comment: https://git.openjdk.org/jdk/pull/27010#discussion_r2312585502
PR Review Comment: https://git.openjdk.org/jdk/pull/27010#discussion_r2312586114
PR Review Comment: https://git.openjdk.org/jdk/pull/27010#discussion_r2312586845
PR Review Comment: https://git.openjdk.org/jdk/pull/27010#discussion_r2312586972
PR Review Comment: https://git.openjdk.org/jdk/pull/27010#discussion_r2312573559
PR Review Comment: https://git.openjdk.org/jdk/pull/27010#discussion_r2312590553
PR Review Comment: https://git.openjdk.org/jdk/pull/27010#discussion_r2312584042