P4
Background:
The option -XX:AOTMode=on is defined in JEP 483 as a way to diagnose inconsistency between AOT training- and production runs.
JEP 483 mentions: "The -XX:AOTMode=on option should be used for diagnostic purposes only and should be avoided in production environment. Otherwise, your application may fail to launch if an incompatible VM option is added outside of your control. E.g., a cloud provider may decide to run some of your JVMs with JVMTI/ClassFileLoadHook for monitoring purposes"
However, the word "on" is ambiguous, as it could be reads as "turn on the AOT cache". As a result, some users may inadvertently add -XX:AOTMode=on to their command-line without realizing the consequences mentioned above.
Proposal:
This REF adds -XX:AOTMode=required as an alias to -XX:AOTMode=on and further clarify the purpose and effects of this option. We intend to deprecate and eventually remove the -XX:AOTMode=on.
Specification:
When the options -XX:AOTMode=required -XX:AOTCache=<file> are given in the command-line, the JVM is required to be able to use <file> as an AOT cache. If the JVM is unable to use <file>, due to incompatible command-line parameters or incompatible user environments, the JVM will print an error message and exit without executing the application.
To enjoy the benefits of the AOT cache generated during a training run, the training run and all subsequent runs must be essentially similar.
- All runs must use the same JDK release and be on the same hardware architecture (e.g., x64 or aarch64) and operating system.
- All runs must have consistent class paths. A subsequent run may specify extra class-path entries, appended to the training class path; otherwise, the class paths must be identical. Class paths must contain only JAR files; directories in class paths are not supported because the JVM cannot efficiently check them for consistency.
- All runs must have consistent module options on the command line, and consistent module graphs. The arguments to the -m, --module, -p, --module-path, --add-modules, and --enable-native-access options, if present, must be identical. The --add-exports, --add-opens, --add-reads, --illegal-native-access, --limit-modules, --patch-module, and --upgrade-module-path options must not be used.
- All runs must not use JVMTI agents that can arbitrarily rewrite classfiles using ClassFileLoadHook.
- All runs must not use JVMTI agents that call the AddToBootstrapClassLoaderSearch and AddToSystemClassLoaderSearch APIs.
If any of these constraints are violated then the JVM, by default, issues a warning and ignores the cache. However, if -XX:AOTMode=required is specified, the JVM will print an error message, and exit.
-XX:AOTMode=required should be used for diagnostic purposes only and should be avoided in production environment. Otherwise, your application may fail to launch if an incompatible VM option is added outside of your control. E.g., a cloud provider may decide to run some of your JVMs with JVMTI/ClassFileLoadHook for monitoring purposes
-XX:AOTMode=required should only be used to diagnose potential command-line and environment incompatibilities. It is not intended to predict the performance benefit of the AOT cache.
Future Evolution:
Future AOT optimizations may impose more compatibility constraints between the training run and production runs. The behavior of -XX:AOTMode=required will be updated as appropriate.
In general, -XX:AOTMode=required will enforce the compatibility constraints strictly and eagerly. If any incompatibility is found, it will be reported and the JVM will exit.
The option -XX:AOTMode=on is defined in JEP 483 as a way to diagnose inconsistency between AOT training- and production runs.
JEP 483 mentions: "The -XX:AOTMode=on option should be used for diagnostic purposes only and should be avoided in production environment. Otherwise, your application may fail to launch if an incompatible VM option is added outside of your control. E.g., a cloud provider may decide to run some of your JVMs with JVMTI/ClassFileLoadHook for monitoring purposes"
However, the word "on" is ambiguous, as it could be reads as "turn on the AOT cache". As a result, some users may inadvertently add -XX:AOTMode=on to their command-line without realizing the consequences mentioned above.
Proposal:
This REF adds -XX:AOTMode=required as an alias to -XX:AOTMode=on and further clarify the purpose and effects of this option. We intend to deprecate and eventually remove the -XX:AOTMode=on.
Specification:
When the options -XX:AOTMode=required -XX:AOTCache=<file> are given in the command-line, the JVM is required to be able to use <file> as an AOT cache. If the JVM is unable to use <file>, due to incompatible command-line parameters or incompatible user environments, the JVM will print an error message and exit without executing the application.
To enjoy the benefits of the AOT cache generated during a training run, the training run and all subsequent runs must be essentially similar.
- All runs must use the same JDK release and be on the same hardware architecture (e.g., x64 or aarch64) and operating system.
- All runs must have consistent class paths. A subsequent run may specify extra class-path entries, appended to the training class path; otherwise, the class paths must be identical. Class paths must contain only JAR files; directories in class paths are not supported because the JVM cannot efficiently check them for consistency.
- All runs must have consistent module options on the command line, and consistent module graphs. The arguments to the -m, --module, -p, --module-path, --add-modules, and --enable-native-access options, if present, must be identical. The --add-exports, --add-opens, --add-reads, --illegal-native-access, --limit-modules, --patch-module, and --upgrade-module-path options must not be used.
- All runs must not use JVMTI agents that can arbitrarily rewrite classfiles using ClassFileLoadHook.
- All runs must not use JVMTI agents that call the AddToBootstrapClassLoaderSearch and AddToSystemClassLoaderSearch APIs.
If any of these constraints are violated then the JVM, by default, issues a warning and ignores the cache. However, if -XX:AOTMode=required is specified, the JVM will print an error message, and exit.
-XX:AOTMode=required should be used for diagnostic purposes only and should be avoided in production environment. Otherwise, your application may fail to launch if an incompatible VM option is added outside of your control. E.g., a cloud provider may decide to run some of your JVMs with JVMTI/ClassFileLoadHook for monitoring purposes
-XX:AOTMode=required should only be used to diagnose potential command-line and environment incompatibilities. It is not intended to predict the performance benefit of the AOT cache.
Future Evolution:
Future AOT optimizations may impose more compatibility constraints between the training run and production runs. The behavior of -XX:AOTMode=required will be updated as appropriate.
In general, -XX:AOTMode=required will enforce the compatibility constraints strictly and eagerly. If any incompatibility is found, it will be reported and the JVM will exit.