JEP draft: Ahead-of-time Command Line Ergonomics

Summary

Make it easier to create an ahead-of-time cache (as defined by JEP 483) for a Java application, by simplifying the commands required by some common use cases.

Goals

• Make it possible to create an AOT cache in one simple command line.

• Do not introduce fundamentally new AOT workflows, but rather make it easier to access existing one.

Non-Goals

• It is not a goal to introduce any new AOT optimizations at this point; rather, we are making existing and future optimizations easier to access.

Motivation

Java application start-up is accelerated by use of an ahead-of-time cache, as defined by JEP 483, and the benefits are expected to grow as new AOT-related optimizations are added to the VM.

Currently, the user creates an AOT cache by means of two commands. The first command specifies the option -XX:AOTMode=record, which requests observation of the dynamics of the user's Java application. The second command specifies -XX:AOTMode=create, which requests creation of an actual AOT cache, whose name is specified by a second command line option such as -XX:AOTCache=myapp.aot.

The accelerated application will then be deployed into production by a third command which specifies the same AOT cacheusing an option like -XX:AOTCache=myapp.aot. This can be executed as many times as desired, since the AOT cache is indefinitely reusable. Note that this production command also has an "AOT mode", -XX:AOTMode=auto, but it is the default setting of the command line option and so does not need to be mentioned explicitly on the command line. The production run only needs the option that specifies the AOT cache, -XX:AOTCache=myapp.aot.

The first two commands work together, splitting responsibility for creating the AOT cache file. The first makes a training run of the application recording dynamic information about it, and the second takes that information and assembles the AOT cache. Those two commands communicate, not via an AOT cache file, but rather by a special file (of an undocumented format and limited usefulness) called an AOT configuration. The name of this file must be chosen by the user using a command line option such as -XX:AOTConfiguration=app.aotconf, and the same command line option must be supplied to both cooperating commands. Note that the second command does not re-run the user's application; it merely takes the configuration file and assembles the requested AOT cache. This second command line is often a simple reformulation of the first command line. The user is responsible for deleting the temporary AOT configuration file.

Having all these explicit commands and runs of the Java virtual machine, with the explicit AOT configuration file, gives some users extra flexibility for complex AOT workflows. For example, a user may perform cascading training runs, where an initial AOT cache, created by a first training run, is used as input to a second training run, which then accumulates more information, ultimately leading to the creation of a second AOT cache that contains a superset of the information in the initial AOT cache.

But the flexibility and explicitness of the pair of commands comes with a cost: The simplest use case must pick a temporary file name, run the two required commands, and delete the temporary file.

Description

We extend the meaning of the "automatic" AOT mode (present by default or explicitly requested as -XX:AOTMode=auto) to cover the most common workflow.

If a user runs a Java application in the automatic AOT mode, and the user also specifies an AOT cache output file (as an explicit command option), then the Java virtual machine automatically orchestrates a training run and also assembles an AOT cache when that training run exits, into the requested file. The temporary configuration information (communicated between the two activities) is managed

Thus, the AOTMode and AOTConfiguration options are not needed for this command and simple use case. The user can ignore the fleeting presence of a temporary AOT configuration file.

The new flag -XX:AOTCacheOutput=myapp.aot is necessary to request this mode of operation.

Note that the existing flag -XX:AOTCache=myapp.aot is insufficient, since it would cause a production run from a previously existing AOT cache, and if the AOT cache file does not exist, the option is ignored, under the default automatic setting of the AOT mode.

A second new flag -XX:AOTCacheInput=myapp.aot is also defined, in order to fully disambiguate references to AOT cache files. Note that the existing option -XX:AOTCache=myapp.aot works for both input or output, depending on mode. Specifying -XX:AOTCacheInput=myapp.aot for a file which does not exist causes the Java virtual machine to report an error explicitly.