RFR: 8367387: Add @AOTInitialize annotation [v4]

[Ioi Lam]

On Tue, 16 Sep 2025 17:40:48 GMT, Ioi Lam <iklam at openjdk.org> wrote:

>> This PR adds a new annotation, `@AOTInitialize` that forces a class to be (a) initialized in the AOT assembly phase, and (b) stored in the AOT cache in an already initialized state. This means that all the static fields in this class will be immediately available upon JVM bootstrap when the AOT cache is used in an application's production run.
>> 
>> This PR annotates a single class, `jdk.internal.math.MathUtils` (also the object hierarchy root class, `Object.class`, which has no associated AOT initialization but is required for completeness). More classes will be added in future PRs.
>> 
>> If a class `K` has the `@AOTInitialize` annotation, the same annotation must be also added to
>> - All of `K`'s super classes
>> - All of `K`'s super interfaces that require to be initialized when `K` is initialized (see JVMS 5.5. Initialization, step 7; also C++ function `InstanceKlass::interface_needs_clinit_execution_as_super()`
>> 
>> Note, the check of the above requirement has been moved to `AOTClassInitializer::check_aot_annotations()`. The previous check in `ClassFileParser` was not executed because the class is loaded in the AOT training run, where `CDSConfig::is_initing_classes_at_dump_time()` returns `false` (this function returns `true` only in the AOT assembly phase).
>> 
>> This annotation is awfully similar to `@AOTSafeClassInitializer`, and I am not sure if we need both. Please see the javadoc in `@AOTInitialize` to see the difference between the two annotations.
>
> Ioi Lam has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Added logging about @AOTSafeClassInitializer classes that have not been initialized

> > This annotation is awfully similar to @AOTSafeClassInitializer, and I am not sure if we need both
> 
> Maybe we do want both. @AOTSafeClassInitializer is weaker than @AOTInitialize because the former only initializes classes optionally when we find it is needed. If we only had @AOTInitialize then we would lose that optionality. It may not make much difference now -- we probably only have these annotations for JDK classes that would need to be class-inited whatever the training regime. However, as we expand use of the annotation might we risk initing classes and including their state in the archive without necessarily seeing any benefit?

Yes, I think we can experiment with having both annotations for now.

I added logging and found:


java.util.stream.Collectors is annotated with @AOTSafeClassInitializer but has not been initialized
java.lang.invoke.BoundMethodHandle$Species_LLL is annotated with @AOTSafeClassInitializer but has not been initialized
java.lang.invoke.BoundMethodHandle$Species_D is annotated with @AOTSafeClassInitializer but has not been initialized
java.lang.invoke.BoundMethodHandle$Species_I is annotated with @AOTSafeClassInitializer but has not been initialized
java.lang.invoke.BoundMethodHandle$Species_LLLLL is annotated with @AOTSafeClassInitializer but has not been initialized
java.lang.invoke.BoundMethodHandle$Species_DL is annotated with @AOTSafeClassInitializer but has not been initialized
java.lang.invoke.BoundMethodHandle$Species_LLLL is annotated with @AOTSafeClassInitializer but has not been initialized
java.lang.invoke.BoundMethodHandle$Species_IL is annotated with @AOTSafeClassInitializer but has not been initialized
java.lang.invoke.VarHandleGuards is annotated with @AOTSafeClassInitializer but has not been initialized


So I think the rules for choosing the annotations for class `C` is:
- If it's certain that AOT-initialization of `C` is safe and beneficial (considering space/speed tradeoffs), use `@AOTInitialize`
- If it's certain that AOT-initialization of `C` is safe, and it's necessary to preserve the effect of `C.<clinit>` for correctness, use `@AOTSafeClassInitializer`

We might prefer `@AOTSafeClassInitializer` if `C.<init>` executes quickly (so there's no start-up benefit for AOT-initialization) but would produce a large amount of data that would increase the footprint of the AOT cache.

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

PR Comment: https://git.openjdk.org/jdk/pull/27024#issuecomment-3299749941