JDK-8338243 : Add AOT command-line flag aliases
  • Type: CSR
  • Component: hotspot
  • Sub-Component: runtime
  • Priority: P3
  • Status: Provisional
  • Resolution: Unresolved
  • Fix Versions: 24
  • Submitted: 2024-08-12
  • Updated: 2024-08-30
Related Reports
CSR :  
JDK-8338017 - Add AOT command-line flag aliases
Description
Summary
-------

We create aliases for existing CDS command-line flags under the "AOT" umbrella to
make them more intuitive to users of upcoming AOT optimizations.

Problem
-------

Many of planned AOT (ahead-of-time) optimization in Project Leyden are based
on the existing [CDS technology in HotSpot](https://docs.oracle.com/en/java/javase/22/vm/class-data-sharing.html). However, many command-line flags related
to CDS, as well as the name CDS itself (which ostensibly stands for Class Data Sharing)
look out of place. It's better to have alternative names for these options that are
grouped under "AOT", so that they will be consistent with future command-line
options that will be introduced by Project Leyden.


Solution
--------

Add new command options that are mapped to existing options:

- `-XX:AOTCache=<file>.aot`
- `-XX:AOTMode=off/auto/on/record/create`
- `-XX:AOTConfiguration=<file>.aotconfig`

Specification
-------------

[1] The three options listed above are all of the type `ccstr`, which means they can be assigned in the command-line to a text string.

[2] `AOTMode` can have the values of  `off`, `auto`, `on`, `record`, or `create`. The other two options can be assigned to arbitrary file names (provided the current user has read and/or write access to these files). It's recommended (but not required) to use `.aot` and `.aotconfig` as file extensions for `AOTCache` and `AOTConfiguration`, respectively.

[3] If `AOTMode` is not assigned, it has the default value of `auto`.

[4] When `-XX:AOTCache=<file>.aot` is specified, and `AOTMode` is `auto`, the JVM behaves as if "`-Xshare:auto -XX:SharedArchiveFile=<file>.aot`" are specified. I.e., the JVM tries to load `<file>.aot` as a CDS archive. If the loading fails (e.g., we have a mismatch in the classpath), the JVM prints a warning and continues execution without using `<file>.aot`

[5] When "`-XX:AOTCache=<file>.aot -XX:AOTMode=on`" are specified, the JVM behaves as if "`-Xshare:on -XX:SharedArchiveFile=<file>.aot`" are specified. I.e., the JVM tries to load `<file>.aot` as a CDS archive. If the loading fails (e.g., we have a mismatch in the classpath), the JVM prints an error message and exits.

[6] When `-XX:AOTMode=off` is specified, the JVM behaves as if "`-Xshare:off` is specified. No CDS archive will be loaded by the JVM.

[7] When `-XX:AOTMode=record` is specified, `-XX:AOTConfiguration=<file>.aotconfig` must be specified and `-XX:AOTCache=<file>.aot` must NOT be specified. The JVM behaves as if "`-Xshare:off -XX:DumpLoadedClassList=<file>.aotconfig`" are specified. I.e., we perform a training run and record profiling information into `<file>.aotconfig`.

[8] When `-XX:AOTMode=create` is specified, both `-XX:AOTConfiguration=<file>.aotconfig` and  `-XX:AOTCache=<file>.aot` must be specified. The JVM behaves as if "`-Xshare:dump -XX:SharedClassListFile=<file>.aotconfig -XX:SharedArchiveFile=<file>.aot`" are specified. I.e., we create the AOT cache `<file>.aot` using the profiling information stored in `<file>.aotconfig`.

[9] To avoid confusion, we forbid the simultaneous use of the new flag with the corresponding "old" flags. I.e., if any of the three flags listed above are used in the command-line, then none of the following flags can appear anywhere in the command-line

- `-Xshare:on`
- `-Xshare:auto`
- `-Xshare:off`
- `-Xshare:dump`
- `-XX:DumpLoadedClassList=<file>`
- `-XX:SharedClassListFile=<file>`
- `-XX:SharedArchiveFile=<file>`
Comments
We decided to use -XX flags because - It's much easier to implement than adding new command-line processing logic in the launcher (src/java.base/share/native/libjli/java.c) - We are still early in Leyden development, so we might need to change/extend the command-line processing down the road. There's a clear process for adding/changing/removing -XX flags, whereas doing that in the launcher would involve a more heavy weight process.
30-08-2024
There is some question as to whether these flags belong in the -XX category. The existing CDS flags are -X flags, which means the launcher is aware of them, whereas -XX are hotspot implementation flags. So having -XX flags alias to -X related flags causes a problem with terminal options in the launcher. It is unclear to me what the status of this AOT technology will be in regards to the overall platform specification and thus whether these should be full launcher (and invocation API) flags (like the module system flags), -X flags (like existing CDS flags), or hotspot specific -XX flags (though as I said this creates a problem with the launcher). Btw new -X options are not supposed to be created under JEP 293 - https://openjdk.org/jeps/293
29-08-2024
Thank you, Ioi! Reviewed.
20-08-2024
I added specification for `-XX:AOTMode=off`
20-08-2024
Moving to Provisional, not Approved.
19-08-2024
You missed specification for -XX:AOTMode=off
17-08-2024
The file suffixes are not required, but I added > It's recommended (but not required) to use `.aot` and `.aotconfig` as file extensions for `AOTCache` and `AOTConfiguration`, respectively.
17-08-2024
I agree to not specify messages.
17-08-2024
Are `.aot` and `.aotconfig` file's suffixes required?
17-08-2024
Since AOTMode is auto by default you need to list -XX:AOTMode=on in command line: [5] When "-XX:AOTMode=on -XX:AOTCache=file.aot" is specified
17-08-2024
What warning/error messages will be for all cases?
17-08-2024