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

• Substantially simplify the process of creating an AOT cache, with no loss of expressiveness.

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

Non-Goals

• It is not a goal to introduce any new AOT optimizations at this point; rather, we will simplify access to all AOT optimizations, both existing and future ones.

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.

In JDK 24, the user creates an AOT cache by means of two java commands that specify distinct AOT modes. The first command specifies record mode, requesting the VM to observe and record of the dynamics of a training run of the user's Java application. The second command specifies create mode, requesting the creation of an AOT cache based on the data recorded from the training run. This data is referred to as an AOT configuration.

Here is an example of these two commands, taken from JEP 483:

$ java -XX:AOTMode=record -XX:AOTConfiguration=app.aotconf \
       -cp app.jar com.example.App ...

$ java -XX:AOTMode=create -XX:AOTConfiguration=app.aotconf \
       -XX:AOTCache=app.aot

Subsequently, the user runs the application specifying just the AOT cache. This production run of the application will start much faster because the application's classes do not need to be discovered, loaded, and linked; they are available instantly from the cache. For example:

$ java -XX:AOTCache=app.aot -cp app.jar com.example.App ...

It is inconvenient to have to run java twice in order to create an AOT cache. It is also inconvenient to have the AOT configuration left over: it is a temporary file that is not needed for production runs, and users generally want to delete it.

According to some reports, these inconveniences also make it harder to implement some JVM-based languages such as jruby.

The user experience would be improved if only one java command were needed to perform a training run and create an AOT cache. This would be efficient for end users, and also convenient for tools that coordinate their own training against custom workloads (e.g., JRuby, according to some reports). The ability to specify AOT modes and AOT configurations explicitly can remain for advanced users.

Description

The java launcher will be extended with a new option that creates an AOT cache at the end of the training run. It will no longer be necessary to run java twice, once with AOTMode=record and once with AOTMode=create. For example, the two commands shown earlier can be replaced by one command that performs the training run and creates the AOT cache:

$ java -XX:AOTCacheOutput=app.aot \
       -cp app.jar com.example.App ...

This dual effect is called combined training and creation. The original invocation of the java launcher is effectively split into two sub-commands, a training run (AOTMode=record), and then the creation of an AOT cache (AOTMode=create). No AOT configuration file is left behind.

The production run that uses the AOT cache is started the same way as before:

$ java -XX:AOTCache=app.aot -cp app.jar com.example.App ...

To aid readability, there is also a new AOTCacheInput option that mirrors the form of AOTCacheOutput. It can be used instead of AOTCache when starting a production run:

$ java -XX:AOTCacheInput=app.aot -cp app.jar com.example.App ...

The use of AOTCacheInput or AOTCache, when starting a training run, is reserved for possible future AOT features, and is currently illegal (per JEP 483).

A new environment variable JAVA_AOT_OPTIONS is supported for passing command line options to apply specifically to the cache creation sub-command, without affecting the training sub-command. The syntax is the same as for the [<code class="prettyprint" >JAVA_TOOL_OPTIONS</code> environment variable]. This feature is present in order to make the one-command workflow apply even to use cases where it might seem that two explicit commands were necessary, because of differences in the command line options.

Orchestration of training and cache creation

The AOTMode setting, as documented in JEP 483, continues to determine the orchestration of training, creation, and production commands. There are a few cases where it may be preferable to mention the mode setting explicitly.

In a cloud setting, a user may choose to control the orchestration of training and cache creation manually. For example, if a training run takes place on a cloud server instance of limited size, the user may decide to create the AOT cache on a "bigger" machine, dedicated to build tasks. In the "small" cloud machine the training run might look like this:

$ java -XX:AOTMode=record \
       -XX:AOTConfiguration=/var/aotout/app.aotconf \
       -cp app.jar com.example.App ...

A shared file system (a writable binding of /var/aotout/) might be required for the "small" machine to deliver the named AOT configuration file for further processing. A "bigger" machine would then finish the job:

$ java -XX:AOTMode=create \
       -XX:AOTConfiguration=/var/aotin/app.aotconf \
       -XX:AOTCache=app.aot

Controlling AOT cache creation in this way is possible because both the AOTMode and AOTConfiguration options can be set explicitly.

As Leyden AOT optimizations get more complex, such a division of labor may become more important. For example, a future feature for AOT code might require minutes of time to assemble a cache on a single-threaded cloud instance, but seconds on a build machine.

When the user decides to combined both training and creation on a single "big" machine, the mode and configuration options may be omitted from the command line. The user simply mentions AOTCacheOutput, and the launcher will perform all necessary steps (training, then creation) to create the new AOT cache.

For full specification details, see https://bugs.openjdk.org/browse/JDK-8354350.

Alternatives

We could have invented a new combined AOT mode such as AOTMode=record+create to request the combined activity. But that would still leave ambiguity as to whether the -XX:AOTCache=myapp.aot file were to be read by training or not. In this hypothetical setting, the existing option -XX:AOTCache=myapp.aot would be insufficient to express the user's intentions. For AOTMode=record, the option AOTCache=myapp.aot is illegal, but seems tocauses the training run to use a previously existing AOT cache. We wish to reserve this possibility for future work. With AOTMode=create, the AOTCache=myapp.aot option overwrites a pre-existing AOT cache with the newly created cache. These two meanings of AOTCache are incompatible, only because they differ in direction.

Thus, having an explicit AOT output option is both necessary and sufficient to request the new behavior. Given that, we do not need a new AOTMode setting. Also, AOTMode=auto is a flexible default, that can readily support the new behavior.

There is no strong current need for AOTCacheInput (an explicitly read-only use a an AOT cache), but it seems reasonable to introduce it at the same time as AOTCacheOutput, as a way for users to make the intention of the their commands more explicit. In the future, AOT workflows may require simultaneous input and output of two AOT caches, or even the same AOT cache (in an incremental update mode). We could delay introduction of AOTCacheInput until those workflows. However, it seems reasonable to train users now to use both directionally inflected versions of AOTCache, since they must learn one.