Estimate project
← All posts

Project Leyden Updates: JEP 514 and JEP 515 in a Nutshell

With JEP 514 and 515, JDK 25 takes Project Leyden further, improving JVM startup and warmup performance through Ahead-of-Time techniques.

4 min read
JavaJVMApplication PerformanceProject Leyden

Project Leyden is a long-running effort to cut down the startup and warmup time of the Java Virtual Machine. Its first finished JEP, numbered JEP 483, arrived in JDK 24. The forthcoming JDK 25 release brings two more JEPs:

In this post, I’d like to walk through both of these improvements.

JEP 514 – Ahead-of-Time Command-Line Ergonomics

First, a short clarification. I’ve written before that using Project Leyden only requires adding this one option to your application’s run command:

-XX:CacheDataStore=myapp.aot

That, however, applied only to the early access build of JDK 24 (build 24-leydenpremain+2-8). Things changed with the official JDK 24 release.

JDK 24 has no CacheDataStore flag. Several other flags are available instead:

  • AOTCache
  • AOTClassLinking
  • AOTConfiguration
  • AOTMode

Using Project Leyden was divided into three steps:

  1. A training run of the application was needed to record the AOT configuration:
java -XX:AOTMode=record -XX:AOTConfiguration=app.aotconf -jar my-app.jar
  1. Next, the recorded configuration was used to build the cache with this command:
java -XX:AOTMode=create -XX:AOTConfiguration=app.aotconf -XX:AOTCache=app.aot -jar my-app.jar
  1. Lastly, every later run can take advantage of the generated cache:
java -XX:AOTCache=app.aot -jar my-app.jar

JEP 514 streamlines this process. Rather than running three separate commands, we now need just two. The first one both records the AOT configuration and builds the cache. The second one stays the same and is used to start the application.

This is made possible by a new command-line option introduced in JDK 25: AOTCacheOutput. Used on its own, it in effect divides a single Java launcher invocation into two sub-invocations. The command looks like this:

java -XX:AOTCacheOutput=app.aot -jar my-app.jar

Under the hood, two separate commands are executed. The first runs with AOTMode=record and produces the AOT configuration. The second runs with AOTMode=create and uses the configuration produced by the first to build an AOT cache in the file given by the AOTCacheOutput option. The issue linked to this JEP describes the process in detail:

“Describing one command that splits into two sub-commands running in two already existing modes is far simpler than describing how a new combined mode would interact with every other VM feature. That’s why we decided against creating a new mode like record+create.”

An advantage of this approach is that the AOT configuration file is generated automatically and removed once the cache has been built. Previously, this had to be handled by hand. Here, the AOT configuration file gets its name by appending the ‘.config’ suffix to the file name passed in the AOTCacheOutput option. So, if the original file is called app.aot, the configuration file will be called app.aot.config.

This default naming can also be overridden if needed. Users can pass the AOTConfiguration option, just like before. The name given in that option is then used, and the file is not removed automatically.

Another notable addition is a new environment variable, JDK_AOT_VM_OPTIONS. It uses the same syntax as the existing JAVA_TOOL_OPTIONS. It lets us override the VM options passed to the sub-invocation that creates the cache. In other words, JAVA_TOOL_OPTIONS is passed on to both sub-invocations (record and create), whereas JDK_AOT_VM_OPTIONS applies only to the create sub-invocation.

To sum up, this JEP makes Project Leyden easier to use, while the earlier approach remains available when needed.

JEP 515 Ahead-of-Time Method Profiling

As noted above, Project Leyden’s main aim is to improve application startup and warmup time. This JEP focuses on warmup time in particular.

The JVM is able to detect the code that runs most often or uses the most CPU time, and it optimizes that code by compiling it to native code. This is called profiling. Put simply, a profile is a set of useful data tied to a method, such as how many times it has been run.

When an application runs the normal way (without an AOT cache), these profiles are collected at the beginning of its execution. The idea of this JEP is to gather profiles during a training run and then reuse them in later runs. As a result, later executions don’t need to collect profiles after startup, so code compilation can start right away.

Keep in mind that how good the training run is has a major impact on how much the application’s warmup time improves. The better the training run, the bigger the performance gain in later runs.

The Ahead-of-Time Method Profiling JEP doesn’t add new workflows; it relies on the existing ones. It doesn’t call for any codebase changes either. In essence, it moves some of the work from production runs to training runs.

Conclusion

It’s great to see that Project Leyden keeps moving forward. The two JEPs coming in JDK 25 bring improvements to both its usability and warmup time. Crucially, Project Leyden fits smoothly into existing code bases.

I’m looking forward to the features that come next.