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.
[JEP 483]: <https://openjdk.org/jeps/483>
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 directional inflections, `AOTCacheOutput` and `AOTCacheInput`.
Then, adjust default behaviors (under `AOTMode=auto`) to implement a new invocation, when the user runs a Java application with `AOTCacheOutput`, to assist the user by orchestrating the steps necessary to creating an AOT cache.
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)or `AOTMode=record` (a training run). It is illegal to specify both `AOTCache` and `AOTCacheOutput` on the same command line.
[2] `AOTCacheOutput`, when no `AOTMode` option is present (or `AOTMode=auto` is explicitly present), requests the new behavior, of combined training and assembly.
[3] 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`.
[4] 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.
[5] During combined training and assembly, the training sub-command (`AOTMode=record`) ignore the `AOTCacheOutput`; it applies only to the sub-command (`AOTMode=create`).
[6] The new `ccstr` option `AOTCacheInput` supplies the same data as `AOTCache`, but is always interpreted in the input direction. As such, it is illegal for operation modes which write the contents of the `AOTCache` file, notably `AOTMode=create` (cache assembly) or `AOTMode=record` (a training run). It is illegal to specify both `AOTCache` and `AOTCacheInput` on the same command line.
_Rationale:_ The `AOTCacheInput` option is not strictly necessary at present, since all legal uses of it could be replaced simply by `AOTCache`. It may be used to emphasize the directional inflection of an AOT cache file argument, as an input. It may also play a role a future AOT technology, where (for example) a Java training run may itself have use an AOT cache. Note that the casual reviewer of an `AOTCache` option may find it difficult to prove whether the AOT cache file is to be read or written.
[7] 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.
[8] The new environment variable `JAVA_AOT_OPTIONS` is (logically) appended to the options passed to the assembly sub-command. In this way, an advanced user can adjust the configuration of the second sub-command, on top of the configuration options given to the first sub-command.
[9] In a directly-specified assembly operation, with `AOTMode=create`, the `JAVA_AOT_OPTIONS` environment variable is also consulted, after any `JAVA_TOOL_OPTIONS` and before any command line options. This makes it convenient to refactor between explicit sub-comamnds and implicit ones, without changing the role of any `JAVA_AOT_OPTIONS` setting.
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 `AOTCacheInput` and `AOTCacheOutput` fully disambiguate data flow direction into or out of AOT cache files, regardless of mode. Thus, `AOTCacheInput` will never cause creation of an AOT cache, while `AOTCacheOutput` always does so.
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, all options relevant to AOT assembly 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.
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>
-------
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.
[JEP 483]: <https://openjdk.org/jeps/483>
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 directional inflections, `AOTCacheOutput` and `AOTCacheInput`.
Then, adjust default behaviors (under `AOTMode=auto`) to implement a new invocation, when the user runs a Java application with `AOTCacheOutput`, to assist the user by orchestrating the steps necessary to creating an AOT cache.
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)or `AOTMode=record` (a training run). It is illegal to specify both `AOTCache` and `AOTCacheOutput` on the same command line.
[2] `AOTCacheOutput`, when no `AOTMode` option is present (or `AOTMode=auto` is explicitly present), requests the new behavior, of combined training and assembly.
[3] 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`.
[4] 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.
[5] During combined training and assembly, the training sub-command (`AOTMode=record`) ignore the `AOTCacheOutput`; it applies only to the sub-command (`AOTMode=create`).
[6] The new `ccstr` option `AOTCacheInput` supplies the same data as `AOTCache`, but is always interpreted in the input direction. As such, it is illegal for operation modes which write the contents of the `AOTCache` file, notably `AOTMode=create` (cache assembly) or `AOTMode=record` (a training run). It is illegal to specify both `AOTCache` and `AOTCacheInput` on the same command line.
_Rationale:_ The `AOTCacheInput` option is not strictly necessary at present, since all legal uses of it could be replaced simply by `AOTCache`. It may be used to emphasize the directional inflection of an AOT cache file argument, as an input. It may also play a role a future AOT technology, where (for example) a Java training run may itself have use an AOT cache. Note that the casual reviewer of an `AOTCache` option may find it difficult to prove whether the AOT cache file is to be read or written.
[7] 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.
[8] The new environment variable `JAVA_AOT_OPTIONS` is (logically) appended to the options passed to the assembly sub-command. In this way, an advanced user can adjust the configuration of the second sub-command, on top of the configuration options given to the first sub-command.
[9] In a directly-specified assembly operation, with `AOTMode=create`, the `JAVA_AOT_OPTIONS` environment variable is also consulted, after any `JAVA_TOOL_OPTIONS` and before any command line options. This makes it convenient to refactor between explicit sub-comamnds and implicit ones, without changing the role of any `JAVA_AOT_OPTIONS` setting.
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 `AOTCacheInput` and `AOTCacheOutput` fully disambiguate data flow direction into or out of AOT cache files, regardless of mode. Thus, `AOTCacheInput` will never cause creation of an AOT cache, while `AOTCacheOutput` always does so.
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, all options relevant to AOT assembly 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.
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>
- relates to
-
JDK-8350022 Ahead-of-time Command Line Ergonomics
-
- Draft
-