Summary

Add flags to further control AOT operations, as initially defined in JEP 483. The new flags will allow a single command (invocation of the JVM) to perform a combined "train and assemble" function.

Problem

In JEP 483 an AOT cache must be requested by issuing a pair of commands (invocations of the JVM), which communicate by a temporary file which the user must name and manage (ie., delete after completion).

We define a new JVM invocation mode, a combined training and assembly operation.

The additional flags of this CSR are necessary to trigger the new combined operation, and to control its details.

See the JEP https://bugs.openjdk.org/browse/JDK-8350022 for more details on the new operation, including its motivation and envisioned usage.

See the CSR https://bugs.openjdk.org/browse/JDK-8338243 for details on the pre-existing flags of JEP 483.

Solution

Extend the existing AOTCache command option with one directional inflection, AOTCacheOutput.

Then, adjust default behaviors (under AOTMode=auto and AOTMode=record) to invoke an extra sub-command of the JVM (with AOTMode=create), when the user runs a Java application with AOTCacheOutput. This will assist the user by orchestrating the steps necessary to creating an AOT cache in one command invocation.

Also, add a new environment variable JAVA_AOT_OPTIONS, closely akin to JAVA_TOOL_OPTIONS, to control fine details of the second sub-command (AOT cache assembly). All initial VM options are passed to both sub-commands, and JAVA_AOT_OPTIONS is picked up only by the second sub-command.

Specification

[1] The new ccstr option AOTCacheOutput supplies the same data as AOTCache, but is always interpreted in the output direction. As such, it is illegal for operation modes which read an AOT cache file, notably AOTMode=on (a production run). It is illegal to specify both AOTCache and AOTCacheOutput on the same command line.

[2] AOTCacheOutput, when no AOTMode option is present (or either AOTMode=auto or AOTMode=record is explicitly present), requests the new behavior, of combined training and assembly. The presence of an AOT output option switches on AOTMode=record, which operates as before, after which a second sub-command operates with AOTMode=create.

During combined training and assembly, the VM invocation is automatically split (transparently to the user) into two VM invocations. One sub-command operates with AOTMode=record, and the second sub-commmand operates with AOTMode=create. They share all other options passed into the original command.

Rationale: It is much easier to explain one command splitting into two sub-commands running under two pre-existing modes, than to explain the interactions of a new combined mode with all other VM features. That is why we choose not to invent a new mode such as record+create.

[3] During combined training and assembly, any AOTConfiguration option present (from JEP 483) works as previously documented. That is, the named file is written, then read, and not deleted. But as a new behavior, if AOTConfiguration is not specified on the command line, the VM chooses a temporary file name, not interfering with any existing file, and uses it to transmit AOT configuration from the first sub-command to the second. This file is deleted after use. Indeed, the VM implementation is free to use any appropriate means, instead of a temporary file, for transmitting this data between sub-commands.

[4] During combined training and assembly, the training sub-command (AOTMode=record) does not act on the AOTCacheOutput; it applies only to the sub-command (AOTMode=create).

[5] The pre-existing environment variable JAVA_TOOL_OPTIONS takes effect as usual when the VM starts up. Sub-commands may be thought of as receiving edited versions of the original VM options, as if via JAVA_TOOL_OPTIONS, and debugging mechanisms (based on -Xlog) will provide a view of the flags being passed to the sub-commands. Note that only the training sub-command receives the Java application main class and arguments.

[6] If the new environment variable JAVA_AOT_OPTIONS is present and non-empty, and the option AOTMode=create is present in either the command line or JAVA_TOOL_OPTIONS, then JAVA_AOT_OPTIONS is scanned, as if it were (logically) appended to JAVA_TOOL_OPTIONS. In this way, an advanced user can adjust the configuration of the second sub-command, or (in fact) of any AOTMode=create command that may execute under the influence of that environment variable.

Rationale: Maintainers of the jruby launcher have requested that the JVM handle the details of AOT configuration management and sub-command launching, but launchers sometimes need fine control over sub-commands that they invoke directly or indirectly. This environment variable gives a necessary hook for such fine control. The same argument applies more generally to script-based use of the JVM, where both $JAVA_TOOL_OPTIONS and $JAVA_AOT_OPTIONS environment variables are likely to be useful for injecting common options used by the whole script. The specific use of $JAVA_AOT_OPTIONS is also likely to be useful for testing, diagnosis, and research related to AOT technologies.

[7] In many file options of the HotSpot JVM, the special string %p (percent-p) is replaced by a representation of the process identification number of the JVM which the user launches. (It is always the user’s job to find such unpredictably-named files after they are produced.) This replacement occurs on the AOTCache, AOTCacheOutput, and AOTConfiguration options as well. The replacement is done in the parent sub-command, not the child sub-command, so that the number N always corresponds to the JVM process that the user launched. This expansion rule applies to all AOT modes, not just the new behavior.

Note: This is a slightly incompatible change from JDK 24, in that some file names containing the substring %p are not currently expanded. This substring %p, standard to HotSpot, is chosen so as to be unlikely to occur unintentionally.

With these changes in place, the combined AOT story runs as follows.

If the AOTMode option is not mentioned, it starts with a default setting (of auto, as documented in JEP 483), and is then ergonomically reset to be consistent with the other AOT options. If AOTCacheOutput is present, the mode is ergonomically set to record and then create, implementing combined training and assembly. Also, in this case, if no AOTConfiguration name is given, the configuration output and input is managed as a temporary file.

Note that while AOTCache denotes either input or output (depending on AOTMode), the new options AOTCacheOutput fully disambiguate data flow direction into or out of AOT cache files, regardless of mode. Thus, AOTCacheOutput will always create an AOT cache.

Note also that in AOTMode=create only, the -XX:AOTCache=newcache.aot option specifies an output AOT cache file, not an input. In that mode, the output direction may be specified explicitly as well, using the new option -XX:AOTCacheOutput=newcache.aot.

If the -XX:AOTConfiguration option is present on the command line, that file name will be used, and the file will be retained after the Java launcher exits. Otherwise, it will be deleted (if it ever existed) after exit.

Thus, the AOTMode and AOTConfiguration options are not needed for simple AOT cache creation. At a minimum, with the given set of default behaviors, an AOTCacheOutput option suffices to trigger creation of an AOT cache from a training run.

In some advanced use cases, the AOT cache assembly process may need special assembly-specific command line options that differ from the training run. This is handled directly in the old two-command workflow, by simply handing the assembly-specific command line options to the second explicit command (assembly) but not the first (training). With the one-command workflow, assembly-specific options can be passed via the JAVA_AOT_OPTIONS environment variable.

There is currently no corresponding proposal for passing options only to the first sub-command (training run). That is because most options passed to the training run can be modified by subsequent settings (in JAVA_AOT_OPTIONS) of the same option.

A combined training and assembly command applies all command line options first to the training run. Then, the options are also passed to the AOT assembly phase, as if by JAVA_TOOL_OPTIONS. After these options are processed, any options in the environment string JAVA_AOT_OPTIONS are also applied to the AOT assembly phase.

A script or launcher may launch many JVM instances. If it is desired to create AOT caches for all of them, the option -XX:AOTCacheOutput=cache%p.aot can be added into the JAVA_TOOL_OPTIONS environment string.

The syntax of the JAVA_TOOL_OPTIONS (and thus JAVA_AOT_OPTIONS) environment variable is documented here:

https://docs.oracle.com/en/java/javase/24/docs/specs/jvmti.html#tooloptions