AppCDS
This reference guide explains how to enable Application Class Data Sharing in your Quarkus applications.
What is Application Class Data Sharing (AppCDS)?
Application Class Data Sharing is a JVM feature that helps reduce the startup time and memory footprint of a JVM application. This is achieved by having the JVM create a pre-processed shared archived of classes that are loaded at startup time. As these classes are loaded every time the application starts, AppCDS is a conceptually simple way of improving the application startup time, without the application itself having to be coded or configured in a specific way. How much of an improvement depends on many factors, such as the number of classes loaded, the underlying hardware etc.
Vanilla AppCDS generation
The main downside of creating AppCDS manually for an application is that their generation requires launching the application with special flags and obtaining the archive in a step before the application is deployed to production.
| The exact process depends on the JVM version being used as newer JVM have incrementally made the process easier. |
This fact makes AppCDS difficult to use for real world deployments where a CI pipeline is responsible for building and deploying applications.
AppCDS in Quarkus
Creating the archive
Quarkus makes AppCDS generation as simple as setting the quarkus.package.jar.appcds.enabled configuration property to true.
For an example Quarkus application using Maven (assuming it is located in /tmp/code-with-quarkus), the AppCDS archive can be generated by simply building the application like so:
./mvnw package -Dquarkus.package.jar.appcds.enabled=trueWhen the build completes, the output will contain (among other things) the following:
[INFO] [io.quarkus.deployment.pkg.steps.AppCDSBuildStep] Launching AppCDS creation process.
[INFO] [io.quarkus.deployment.pkg.steps.AppCDSBuildStep] AppCDS successfully created at: '/tmp/code-with-quarkus/target/quarkus-app/app-cds.jsa'.
[INFO] [io.quarkus.deployment.pkg.steps.AppCDSBuildStep] To ensure they are loaded properly, run the application jar from its directory and also add the '-XX:SharedArchiveFile=app-cds.jsa' JVM flag.
Moreover, make sure to use the exact same Java version (x.y.z) to run the application as was used to build it.If we take a look at /tmp/code-with-quarkus/target/quarkus-app, among the other files, we see app-cds.jsa, which is the generated AppCDS archive.
Using the archive
Using the archive is done by using the -XX:SharedArchiveFile flag. However, a few caveats apply:
-
The paths to the Quarkus jar file and the AppCDS archive need to be exactly the same as those Quarkus used to build the archive
-
The version of the JVM used to run the application must be exactly the same as the one used to build the Quarkus application.
Assuming we are using the same JVM to run the application as we used to build the application, we can launch the application like so:
cd target/quarkus-app
java -XX:SharedArchiveFile=app-cds.jsa -jar quarkus-run.jar|
The JVM is resilient. Faced with a situation where the archive file is not usable (for whatever reason) it will simply disable the AppCDS feature. If it is desirable to simply halt the execution when the archive is not usable, the following command line invocation can be used: |
|
Given what was mentioned above about how the application needs to be launched in order for the archive to be built, the question arises of how Quarkus deals with this situation. The answer is that at application build time, right after the application archive is built, Quarkus launches the application, but only the parts of the launch process that are safe are run. More specifically, the application is run up until the steps that actually open sockets or run application logic. This results in an archive generation process that on one hand is completely safe, but on the other hand is unable to archive every single class that the application might need at boot time. As a result, users are expected to get a slightly more effective archive if they manually go through the hoops of generating the AppCDS archive. |
|
AppCDS has improved significantly in the latest JDK releases. This means that to ensure the best possible improvements from it, make sure your projects targets the highest possible Java version (ideally 17 or 21). |
Usage in containers
When building container images using the quarkus-container-image-jib extension, Quarkus automatically takes care of all the steps needed to generate the archive and make it usable at runtime in the container.
This way, by simply setting quarkus.package.jar.appcds.enabled to true, containers using the generated image can benefit from a slight reduction in startup time and memory usage.
You may see that Quarkus starts a container to generate the AppCDS archive.
It does this to ensure that the Java version of the build align with that of the generated container image.
It is possible to opt out of this by setting quarkus.package.jar.appcds.use-container to false.
In that case, it is your responsibility to ensure that the Java version that will run the Quarkus application matches that of the machine building it.
