@@ -4011,12 +4011,12 @@ The values for these options (if specified), should be identical when creating a
40114011CDS archive. Otherwise, if there is a mismatch of any of these options, the CDS archive may be
40124012partially or completely disabled, leading to lower performance.
40134013
4014- - If the -XX:+ AOTClassLinking options * was* used during CDS archive creation, the CDS archive
4014+ - If the ` AOTClassLinking ` option (see below) * was* enabled during CDS archive creation, the CDS archive
40154015 cannot be used, and the following error message is printed:
40164016
40174017 ` CDS archive has aot-linked classes. It cannot be used when archived full module graph is not used `
40184018
4019- - If the -XX:+ AOTClassLinking options * was not* used during CDS archive creation, the CDS archive
4019+ - If the ` AOTClassLinking ` option * was not* enabled during CDS archive creation, the CDS archive
40204020 can be used, but the "archived module graph" feature will be disabled. This can lead to increased
40214021 start-up time.
40224022
@@ -4037,6 +4037,115 @@ JVM will execute without loading any CDS archives. In addition, if
40374037you try to create a CDS archive with any of these 3 options specified,
40384038the JVM will report an error.
40394039
4040+ ## Ahead-of-Time Cache
4041+
4042+ The JDK supports ahead-of-time (AOT) optimizations that can be performed before an
4043+ application is executed. One example is Class Data Sharing (CDS), as described above,
4044+ that parses classes ahead of time. AOT optimizations can improve the start-up and
4045+ warm-up performance of Java applications.
4046+
4047+ The Ahead-of-Time Cache (AOT cache) is a container introduced in JDK 24 for
4048+ storing artifacts produced by AOT optimizations. The AOT cache currently contains
4049+ Java classes and heap objects. In future JDK releases, the AOT cache may contain additional
4050+ artifacts, such as execution profiles and compiled methods.
4051+
4052+ An AOT cache is specific to a combination of the following:
4053+
4054+ - A particular application (as expressed by ` -classpath ` , ` -jar ` , or ` --module-path ` .)
4055+ - A particular JDK release.
4056+ - A particular OS and CPU architecture.
4057+
4058+ If any of the above changes, you must recreate the AOT cache.
4059+
4060+ The deployment of the AOT cache is divided into three phases:
4061+
4062+ - ** Training:** We execute the application with a representative work-load
4063+ to gather statistical data that tell us what artifacts should be included
4064+ into the AOT cache. The data are saved in an * AOT Configuration* file.
4065+
4066+ - ** Assembly:** We use the AOT Configuration file to produce an AOT cache.
4067+
4068+ - ** Production:** We execute the application with the AOT cache for better
4069+ start-up and warm-up performance.
4070+
4071+ The AOT cache can be used with the following command-line options:
4072+
4073+ ` -XX:AOTCache:= ` * cachefile*
4074+ : Specifies the location of the AOT cache. The standard extension for * cachefile* is ` .aot ` .
4075+ If ` -XX:AOTCache ` is specified but ` -XX:AOTMode ` is not specified,
4076+ then ` AOTMode ` will be given the value of ` auto ` .
4077+
4078+ ` -XX:AOTConfiguration:= ` * configfile*
4079+ : Specifies the AOT Configuration file for the JVM to write to or read from.
4080+ This option can be used only with ` -XX:AOTMode=record ` and ` -XX:AOTMode=create ` .
4081+ The standard extension for * configfile* is ` .aotconfig ` .
4082+
4083+ ` -XX:+AOTMode:= ` * mode*
4084+ : * mode* must be one of the following: ` off ` , ` record ` , ` create ` , ` auto ` , or ` on ` .
4085+
4086+ - ` off ` : no AOT cache is used.
4087+
4088+ - ` record ` : Execute the application in the Training phase.
4089+ ` -XX:AOTConfiguration= ` * configfile* must be specified. The JVM gathers
4090+ statistical data and stores them into * configfile* .
4091+
4092+ - ` create ` : Perform the Assembly phase. ` -XX:AOTConfiguration= ` * configfile*
4093+ and ` -XX:AOTCache= ` * cachefile* must be specified. The JVM reads the statistical
4094+ data from * configfile* and writes the optimization artifacts into * cachefile* .
4095+ Note that the application itself is not executed in this phase.
4096+
4097+ - ` auto ` or ` on ` : These modes should be used in the Production phase.
4098+ If ` -XX:AOTCache= ` * cachefile* is specified, the JVM tries to
4099+ load * cachefile* as the AOT cache. Otherwise, the JVM tries to load
4100+ a * default CDS archive* from the JDK installation directory as the AOT cache.
4101+
4102+ The loading of an AOT cache can fail for a number of reasons:
4103+
4104+ - You are trying to use the AOT cache with an incompatible application, JDK release,
4105+ or OS/CPU.
4106+
4107+ - The specified * cachefile* does not exist or is not accessible.
4108+
4109+ - Incompatible JVM options are used (for example, certain JVMTI options).
4110+
4111+ Since the AOT cache is an optimization feature, there's no guarantee that it will be
4112+ compatible with all possible JVM options. See [ JEP 483] ( https://openjdk.org/jeps/483 ) ,
4113+ section ** Consistency of training and subsequent runs** for a representative
4114+ list of scenarios that may be incompatible with the AOT cache for JDK 24.
4115+
4116+ These scenarios usually involve arbitrary modification of classes for diagnostic
4117+ purposes and are typically not relevant for production environments.
4118+
4119+ When the AOT cache fails to load:
4120+
4121+ - If ` AOTMode ` is ` auto ` , the JVM will continue execution without using the
4122+ AOT cache. This is the recommended mode for production environments, especially
4123+ when you may not have complete control of the command-line (e.g., your
4124+ application's launch script may allow users to inject options to the command-line).
4125+ This allows your application to function correctly, although sometimes it may not
4126+ benefit from the AOT cache.
4127+
4128+ - If ` AOTMode ` is ` on ` , the JVM will print an error message and exit immediately. This
4129+ mode should be used only as a "fail-fast" debugging aid to check if your command-line
4130+ options are compatible with the AOT cache. An alternative is to run your application with
4131+ ` -XX:AOTMode=auto -Xlog:cds ` to see if the AOT cache can be used or not.
4132+
4133+ ` -XX:+AOTClassLinking `
4134+ : If this option is enabled, the JVM will perform more advanced optimizations (such
4135+ as ahead-of-time resolution of invokedynamic instructions)
4136+ when creating the AOT cache. As a result, the application will see further improvements
4137+ in start-up and warm-up performance. However, an AOT cache created with this option
4138+ cannot be used when certain command-line parameters are specified in
4139+ the Production phase. Please see [ JEP 483] ( https://openjdk.org/jeps/483 ) for a
4140+ detailed discussion of ` -XX:+AOTClassLinking ` and its restrictions.
4141+
4142+ When `-XX:AOTMode` *is used* in the command-line, `AOTClassLinking` is automatically
4143+ enabled. To disable it, you must explicitly pass the `-XX:-AOTClassLinking` option.
4144+
4145+ When `-XX:AOTMode` *is not used* in the command-line, `AOTClassLinking` is disabled by
4146+ default to provide full compatibility with traditional CDS options such as `-Xshare:dump.
4147+
4148+
40404149## Performance Tuning Examples
40414150
40424151You can use the Java advanced runtime options to optimize the performance of
0 commit comments