| .\" Copyright (c) 1994, 2021, Oracle and/or its affiliates. All rights reserved. |
| .\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| .\" |
| .\" This code is free software; you can redistribute it and/or modify it |
| .\" under the terms of the GNU General Public License version 2 only, as |
| .\" published by the Free Software Foundation. |
| .\" |
| .\" This code is distributed in the hope that it will be useful, but WITHOUT |
| .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| .\" version 2 for more details (a copy is included in the LICENSE file that |
| .\" accompanied this code). |
| .\" |
| .\" You should have received a copy of the GNU General Public License version |
| .\" 2 along with this work; if not, write to the Free Software Foundation, |
| .\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| .\" |
| .\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| .\" or visit www.oracle.com if you need additional information or have any |
| .\" questions. |
| .\" |
| .\"t |
| .\" Automatically generated by Pandoc 2.3.1 |
| .\" |
| .TH "JAVA" "1" "2021" "JDK 17" "JDK Commands" |
| .hy |
| .SH NAME |
| .PP |
| java \- launch a Java application |
| .SH SYNOPSIS |
| .PP |
| To launch a class file: |
| .PP |
| \f[CB]java\f[R] [\f[I]options\f[R]] \f[I]mainclass\f[R] [\f[I]args\f[R] ...] |
| .PP |
| To launch the main class in a JAR file: |
| .PP |
| \f[CB]java\f[R] [\f[I]options\f[R]] \f[CB]\-jar\f[R] \f[I]jarfile\f[R] |
| [\f[I]args\f[R] ...] |
| .PP |
| To launch the main class in a module: |
| .PP |
| \f[CB]java\f[R] [\f[I]options\f[R]] \f[CB]\-m\f[R] |
| \f[I]module\f[R][\f[CB]/\f[R]\f[I]mainclass\f[R]] [\f[I]args\f[R] ...] |
| .PP |
| or |
| .PP |
| \f[CB]java\f[R] [\f[I]options\f[R]] \f[CB]\-\-module\f[R] |
| \f[I]module\f[R][\f[CB]/\f[R]\f[I]mainclass\f[R]] [\f[I]args\f[R] ...] |
| .PP |
| To launch a single source\-file program: |
| .PP |
| \f[CB]java\f[R] [\f[I]options\f[R]] \f[I]source\-file\f[R] [\f[I]args\f[R] |
| \&...] |
| .TP |
| .B \f[I]options\f[R] |
| Optional: Specifies command\-line options separated by spaces. |
| See \f[B]Overview of Java Options\f[R] for a description of available |
| options. |
| .RS |
| .RE |
| .TP |
| .B \f[I]mainclass\f[R] |
| Specifies the name of the class to be launched. |
| Command\-line entries following \f[CB]classname\f[R] are the arguments for |
| the main method. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-jar\f[R] \f[I]jarfile\f[R] |
| Executes a program encapsulated in a JAR file. |
| The \f[I]jarfile\f[R] argument is the name of a JAR file with a manifest |
| that contains a line in the form \f[CB]Main\-Class:\f[R]\f[I]classname\f[R] |
| that defines the class with the |
| \f[CB]public\ static\ void\ main(String[]\ args)\f[R] method that serves |
| as your application\[aq]s starting point. |
| When you use \f[CB]\-jar\f[R], the specified JAR file is the source of all |
| user classes, and other class path settings are ignored. |
| If you\[aq]re using JAR files, then see \f[B]jar\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-m\f[R] or \f[CB]\-\-module\f[R] \f[I]module\f[R][\f[CB]/\f[R]\f[I]mainclass\f[R]] |
| Executes the main class in a module specified by \f[I]mainclass\f[R] if |
| it is given, or, if it is not given, the value in the \f[I]module\f[R]. |
| In other words, \f[I]mainclass\f[R] can be used when it is not specified |
| by the module, or to override the value when it is specified. |
| .RS |
| .PP |
| See \f[B]Standard Options for Java\f[R]. |
| .RE |
| .TP |
| .B \f[I]source\-file\f[R] |
| Only used to launch a single source\-file program. |
| Specifies the source file that contains the main class when using |
| source\-file mode. |
| See \f[B]Using Source\-File Mode to Launch Single\-File Source\-Code |
| Programs\f[R] |
| .RS |
| .RE |
| .TP |
| .B \f[I]args\f[R] ... |
| Optional: Arguments following \f[I]mainclass\f[R], \f[I]source\-file\f[R], |
| \f[CB]\-jar\f[R] \f[I]jarfile\f[R], and \f[CB]\-m\f[R] or \f[CB]\-\-module\f[R] |
| \f[I]module\f[R]\f[CB]/\f[R]\f[I]mainclass\f[R] are passed as arguments to |
| the main class. |
| .RS |
| .RE |
| .SH DESCRIPTION |
| .PP |
| The \f[CB]java\f[R] command starts a Java application. |
| It does this by starting the Java Virtual Machine (JVM), loading the |
| specified class, and calling that class\[aq]s \f[CB]main()\f[R] method. |
| The method must be declared \f[CB]public\f[R] and \f[CB]static\f[R], it must |
| not return any value, and it must accept a \f[CB]String\f[R] array as a |
| parameter. |
| The method declaration has the following form: |
| .RS |
| .PP |
| \f[CB]public\ static\ void\ main(String[]\ args)\f[R] |
| .RE |
| .PP |
| In source\-file mode, the \f[CB]java\f[R] command can launch a class |
| declared in a source file. |
| See \f[B]Using Source\-File Mode to Launch Single\-File Source\-Code |
| Programs\f[R] for a description of using the source\-file mode. |
| .RS |
| .PP |
| \f[B]Note:\f[R] You can use the \f[CB]JDK_JAVA_OPTIONS\f[R] launcher |
| environment variable to prepend its content to the actual command line |
| of the \f[CB]java\f[R] launcher. |
| See \f[B]Using the JDK_JAVA_OPTIONS Launcher Environment Variable\f[R]. |
| .RE |
| .PP |
| By default, the first argument that isn\[aq]t an option of the |
| \f[CB]java\f[R] command is the fully qualified name of the class to be |
| called. |
| If \f[CB]\-jar\f[R] is specified, then its argument is the name of the JAR |
| file containing class and resource files for the application. |
| The startup class must be indicated by the \f[CB]Main\-Class\f[R] manifest |
| header in its manifest file. |
| .PP |
| Arguments after the class file name or the JAR file name are passed to |
| the \f[CB]main()\f[R] method. |
| .SS \f[CB]javaw\f[R] |
| .PP |
| \f[B]Windows:\f[R] The \f[CB]javaw\f[R] command is identical to |
| \f[CB]java\f[R], except that with \f[CB]javaw\f[R] there\[aq]s no associated |
| console window. |
| Use \f[CB]javaw\f[R] when you don\[aq]t want a command prompt window to |
| appear. |
| The \f[CB]javaw\f[R] launcher will, however, display a dialog box with |
| error information if a launch fails. |
| .SH USING SOURCE\-FILE MODE TO LAUNCH SINGLE\-FILE SOURCE\-CODE PROGRAMS |
| .PP |
| To launch a class declared in a source file, run the \f[CB]java\f[R] |
| launcher in source\-file mode. |
| Entering source\-file mode is determined by two items on the |
| \f[CB]java\f[R] command line: |
| .IP \[bu] 2 |
| The first item on the command line that is not an option or part of an |
| option. |
| In other words, the item in the command line that would otherwise be the |
| main class name. |
| .IP \[bu] 2 |
| The \f[CB]\-\-source\f[R] \f[I]version\f[R] option, if present. |
| .PP |
| If the class identifies an existing file that has a \f[CB]\&.java\f[R] |
| extension, or if the \f[CB]\-\-source\f[R] option is specified, then |
| source\-file mode is selected. |
| The source file is then compiled and run. |
| The \f[CB]\-\-source\f[R] option can be used to specify the source |
| \f[I]version\f[R] or \f[I]N\f[R] of the source code. |
| This determines the API that can be used. |
| When you set \f[CB]\-\-source\f[R] \f[I]N\f[R], you can only use the public |
| API that was defined in JDK \f[I]N\f[R]. |
| .RS |
| .PP |
| \f[B]Note:\f[R] The valid values of \f[I]N\f[R] change for each release, |
| with new values added and old values removed. |
| You\[aq]ll get an error message if you use a value of \f[I]N\f[R] that is |
| no longer supported. |
| The supported values of \f[I]N\f[R] are the current Java SE release |
| (\f[CB]17\f[R]) and a limited number of previous releases, detailed in the |
| command\-line help for \f[CB]javac\f[R], under the \f[CB]\-\-source\f[R] and |
| \f[CB]\-\-release\f[R] options. |
| .RE |
| .PP |
| If the file does not have the \f[CB]\&.java\f[R] extension, the |
| \f[CB]\-\-source\f[R] option must be used to tell the \f[CB]java\f[R] |
| command to use the source\-file mode. |
| The \f[CB]\-\-source\f[R] option is used for cases when the source file is |
| a "script" to be executed and the name of the source file does not |
| follow the normal naming conventions for Java source files. |
| .PP |
| In source\-file mode, the effect is as though the source file is |
| compiled into memory, and the first class found in the source file is |
| executed. |
| Any arguments placed after the name of the source file in the original |
| command line are passed to the compiled class when it is executed. |
| .PP |
| For example, if a file were named \f[CB]HelloWorld.java\f[R] and contained |
| a class named \f[CB]hello.World\f[R], then the source\-file mode command |
| to launch the class would be: |
| .RS |
| .PP |
| \f[CB]java\ HelloWorld.java\f[R] |
| .RE |
| .PP |
| The example illustrates that the class can be in a named package, and |
| does not need to be in the unnamed package. |
| This use of source\-file mode is informally equivalent to using the |
| following two commands where \f[CB]hello.World\f[R] is the name of the |
| class in the package: |
| .IP |
| .nf |
| \f[CB] |
| javac\ \-d\ <memory>\ HelloWorld.java |
| java\ \-cp\ <memory>\ hello.World |
| \f[R] |
| .fi |
| .PP |
| \f[B]In source\-file mode, any additional command\-line options are |
| processed as follows:\f[R] |
| .IP \[bu] 2 |
| The launcher scans the options specified before the source file for any |
| that are relevant in order to compile the source file. |
| .RS 2 |
| .PP |
| This includes: \f[CB]\-\-class\-path\f[R], \f[CB]\-\-module\-path\f[R], |
| \f[CB]\-\-add\-exports\f[R], \f[CB]\-\-add\-modules\f[R], |
| \f[CB]\-\-limit\-modules\f[R], \f[CB]\-\-patch\-module\f[R], |
| \f[CB]\-\-upgrade\-module\-path\f[R], and any variant forms of those |
| options. |
| It also includes the new \f[CB]\-\-enable\-preview\f[R] option, described |
| in JEP 12. |
| .RE |
| .IP \[bu] 2 |
| No provision is made to pass any additional options to the compiler, |
| such as \f[CB]\-processor\f[R] or \f[CB]\-Werror\f[R]. |
| .IP \[bu] 2 |
| Command\-line argument files (\f[CB]\@\f[R]\-files) may be used in the |
| standard way. |
| Long lists of arguments for either the VM or the program being invoked |
| may be placed in files specified on the command\-line by prefixing the |
| filename with an \f[CB]\@\f[R] character. |
| .PP |
| \f[B]In source\-file mode, compilation proceeds as follows:\f[R] |
| .IP \[bu] 2 |
| Any command\-line options that are relevant to the compilation |
| environment are taken into account. |
| .IP \[bu] 2 |
| No other source files are found and compiled, as if the source path is |
| set to an empty value. |
| .IP \[bu] 2 |
| Annotation processing is disabled, as if \f[CB]\-proc:none\f[R] is in |
| effect. |
| .IP \[bu] 2 |
| If a version is specified, via the \f[CB]\-\-source\f[R] option, the value |
| is used as the argument for an implicit \f[CB]\-\-release\f[R] option for |
| the compilation. |
| This sets both the source version accepted by compiler and the system |
| API that may be used by the code in the source file. |
| .IP \[bu] 2 |
| The source file is compiled in the context of an unnamed module. |
| .IP \[bu] 2 |
| The source file should contain one or more top\-level classes, the first |
| of which is taken as the class to be executed. |
| .IP \[bu] 2 |
| The compiler does not enforce the optional restriction defined at the |
| end of JLS ??7.6, that a type in a named package should exist in a file |
| whose name is composed from the type name followed by the |
| \f[CB]\&.java\f[R] extension. |
| .IP \[bu] 2 |
| If the source file contains errors, appropriate error messages are |
| written to the standard error stream, and the launcher exits with a |
| non\-zero exit code. |
| .PP |
| \f[B]In source\-file mode, execution proceeds as follows:\f[R] |
| .IP \[bu] 2 |
| The class to be executed is the first top\-level class found in the |
| source file. |
| It must contain a declaration of the standard |
| \f[CB]public\ static\ void\ main(String[])\f[R] method. |
| .IP \[bu] 2 |
| The compiled classes are loaded by a custom class loader, that delegates |
| to the application class loader. |
| This implies that classes appearing on the application class path cannot |
| refer to any classes declared in the source file. |
| .IP \[bu] 2 |
| The compiled classes are executed in the context of an unnamed module, |
| as though \f[CB]\-\-add\-modules=ALL\-DEFAULT\f[R] is in effect. |
| This is in addition to any other \f[CB]\-\-add\-module\f[R] options that |
| may be have been specified on the command line. |
| .IP \[bu] 2 |
| Any arguments appearing after the name of the file on the command line |
| are passed to the standard main method in the obvious way. |
| .IP \[bu] 2 |
| It is an error if there is a class on the application class path whose |
| name is the same as that of the class to be executed. |
| .PP |
| See \f[B]JEP 330: Launch Single\-File Source\-Code Programs\f[R] |
| [http://openjdk.java.net/jeps/330] for complete details. |
| .SH USING THE JDK_JAVA_OPTIONS LAUNCHER ENVIRONMENT VARIABLE |
| .PP |
| \f[CB]JDK_JAVA_OPTIONS\f[R] prepends its content to the options parsed |
| from the command line. |
| The content of the \f[CB]JDK_JAVA_OPTIONS\f[R] environment variable is a |
| list of arguments separated by white\-space characters (as determined by |
| \f[CB]isspace()\f[R]). |
| These are prepended to the command line arguments passed to |
| \f[CB]java\f[R] launcher. |
| The encoding requirement for the environment variable is the same as the |
| \f[CB]java\f[R] command line on the system. |
| \f[CB]JDK_JAVA_OPTIONS\f[R] environment variable content is treated in the |
| same manner as that specified in the command line. |
| .PP |
| Single (\f[CB]\[aq]\f[R]) or double (\f[CB]"\f[R]) quotes can be used to |
| enclose arguments that contain whitespace characters. |
| All content between the open quote and the first matching close quote |
| are preserved by simply removing the pair of quotes. |
| In case a matching quote is not found, the launcher will abort with an |
| error message. |
| \f[CB]\@\f[R]\-files are supported as they are specified in the command |
| line. |
| However, as in \f[CB]\@\f[R]\-files, use of a wildcard is not supported. |
| In order to mitigate potential misuse of \f[CB]JDK_JAVA_OPTIONS\f[R] |
| behavior, options that specify the main class (such as \f[CB]\-jar\f[R]) |
| or cause the \f[CB]java\f[R] launcher to exit without executing the main |
| class (such as \f[CB]\-h\f[R]) are disallowed in the environment variable. |
| If any of these options appear in the environment variable, the launcher |
| will abort with an error message. |
| When \f[CB]JDK_JAVA_OPTIONS\f[R] is set, the launcher prints a message to |
| stderr as a reminder. |
| .PP |
| \f[B]Example:\f[R] |
| .IP |
| .nf |
| \f[CB] |
| $\ export\ JDK_JAVA_OPTIONS=\[aq]\-g\ \@file1\ \-Dprop=value\ \@file2\ \-Dws.prop="white\ spaces"\[aq] |
| $\ java\ \-Xint\ \@file3 |
| \f[R] |
| .fi |
| .PP |
| is equivalent to the command line: |
| .IP |
| .nf |
| \f[CB] |
| java\ \-g\ \@file1\ \-Dprop=value\ \@file2\ \-Dws.prop="white\ spaces"\ \-Xint\ \@file3 |
| \f[R] |
| .fi |
| .SH OVERVIEW OF JAVA OPTIONS |
| .PP |
| The \f[CB]java\f[R] command supports a wide range of options in the |
| following categories: |
| .IP \[bu] 2 |
| \f[B]Standard Options for Java\f[R]: Options guaranteed to be supported |
| by all implementations of the Java Virtual Machine (JVM). |
| They\[aq]re used for common actions, such as checking the version of the |
| JRE, setting the class path, enabling verbose output, and so on. |
| .IP \[bu] 2 |
| \f[B]Extra Options for Java\f[R]: General purpose options that are |
| specific to the Java HotSpot Virtual Machine. |
| They aren\[aq]t guaranteed to be supported by all JVM implementations, |
| and are subject to change. |
| These options start with \f[CB]\-X\f[R]. |
| .PP |
| The advanced options aren\[aq]t recommended for casual use. |
| These are developer options used for tuning specific areas of the Java |
| HotSpot Virtual Machine operation that often have specific system |
| requirements and may require privileged access to system configuration |
| parameters. |
| Several examples of performance tuning are provided in \f[B]Performance |
| Tuning Examples\f[R]. |
| These options aren\[aq]t guaranteed to be supported by all JVM |
| implementations and are subject to change. |
| Advanced options start with \f[CB]\-XX\f[R]. |
| .IP \[bu] 2 |
| \f[B]Advanced Runtime Options for Java\f[R]: Control the runtime behavior |
| of the Java HotSpot VM. |
| .IP \[bu] 2 |
| \f[B]Advanced JIT Compiler Options for java\f[R]: Control the dynamic |
| just\-in\-time (JIT) compilation performed by the Java HotSpot VM. |
| .IP \[bu] 2 |
| \f[B]Advanced Serviceability Options for Java\f[R]: Enable gathering |
| system information and performing extensive debugging. |
| .IP \[bu] 2 |
| \f[B]Advanced Garbage Collection Options for Java\f[R]: Control how |
| garbage collection (GC) is performed by the Java HotSpot |
| .PP |
| Boolean options are used to either enable a feature that\[aq]s disabled |
| by default or disable a feature that\[aq]s enabled by default. |
| Such options don\[aq]t require a parameter. |
| Boolean \f[CB]\-XX\f[R] options are enabled using the plus sign |
| (\f[CB]\-XX:+\f[R]\f[I]OptionName\f[R]) and disabled using the minus sign |
| (\f[CB]\-XX:\-\f[R]\f[I]OptionName\f[R]). |
| .PP |
| For options that require an argument, the argument may be separated from |
| the option name by a space, a colon (:), or an equal sign (=), or the |
| argument may directly follow the option (the exact syntax differs for |
| each option). |
| If you\[aq]re expected to specify the size in bytes, then you can use no |
| suffix, or use the suffix \f[CB]k\f[R] or \f[CB]K\f[R] for kilobytes (KB), |
| \f[CB]m\f[R] or \f[CB]M\f[R] for megabytes (MB), or \f[CB]g\f[R] or \f[CB]G\f[R] |
| for gigabytes (GB). |
| For example, to set the size to 8 GB, you can specify either |
| \f[CB]8g\f[R], \f[CB]8192m\f[R], \f[CB]8388608k\f[R], or \f[CB]8589934592\f[R] |
| as the argument. |
| If you are expected to specify the percentage, then use a number from 0 |
| to 1. |
| For example, specify \f[CB]0.25\f[R] for 25%. |
| .PP |
| The following sections describe the options that are obsolete, |
| deprecated, and removed: |
| .IP \[bu] 2 |
| \f[B]Deprecated Java Options\f[R]: Accepted and acted upon \-\-\- a |
| warning is issued when they\[aq]re used. |
| .IP \[bu] 2 |
| \f[B]Obsolete Java Options\f[R]: Accepted but ignored \-\-\- a warning is |
| issued when they\[aq]re used. |
| .IP \[bu] 2 |
| \f[B]Removed Java Options\f[R]: Removed \-\-\- using them results in an |
| error. |
| .SH STANDARD OPTIONS FOR JAVA |
| .PP |
| These are the most commonly used options supported by all |
| implementations of the JVM. |
| .RS |
| .PP |
| \f[B]Note:\f[R] To specify an argument for a long option, you can use |
| either \f[CB]\-\-\f[R]\f[I]name\f[R]\f[CB]=\f[R]\f[I]value\f[R] or |
| \f[CB]\-\-\f[R]\f[I]name\f[R] \f[I]value\f[R]. |
| .RE |
| .TP |
| .B \f[CB]\-agentlib:\f[R]\f[I]libname\f[R][\f[CB]=\f[R]\f[I]options\f[R]] |
| Loads the specified native agent library. |
| After the library name, a comma\-separated list of options specific to |
| the library can be used. |
| .RS |
| .IP \[bu] 2 |
| \f[B]Linux and macOS:\f[R] If the option \f[CB]\-agentlib:foo\f[R] is |
| specified, then the JVM attempts to load the library named |
| \f[CB]libfoo.so\f[R] in the location specified by the |
| \f[CB]LD_LIBRARY_PATH\f[R] system variable (on macOS this variable is |
| \f[CB]DYLD_LIBRARY_PATH\f[R]). |
| .IP \[bu] 2 |
| \f[B]Windows:\f[R] If the option \f[CB]\-agentlib:foo\f[R] is specified, |
| then the JVM attempts to load the library named \f[CB]foo.dll\f[R] in the |
| location specified by the \f[CB]PATH\f[R] system variable. |
| .RS 2 |
| .PP |
| The following example shows how to load the Java Debug Wire Protocol |
| (JDWP) library and listen for the socket connection on port 8000, |
| suspending the JVM before the main class loads: |
| .RS |
| .PP |
| \f[CB]\-agentlib:jdwp=transport=dt_socket,server=y,address=8000\f[R] |
| .RE |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-agentpath:\f[R]\f[I]pathname\f[R][\f[CB]=\f[R]\f[I]options\f[R]] |
| Loads the native agent library specified by the absolute path name. |
| This option is equivalent to \f[CB]\-agentlib\f[R] but uses the full path |
| and file name of the library. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-\-class\-path\f[R] \f[I]classpath\f[R], \f[CB]\-classpath\f[R] \f[I]classpath\f[R], or \f[CB]\-cp\f[R] \f[I]classpath\f[R] |
| A semicolon (\f[CB];\f[R]) separated list of directories, JAR archives, |
| and ZIP archives to search for class files. |
| .RS |
| .PP |
| Specifying \f[I]classpath\f[R] overrides any setting of the |
| \f[CB]CLASSPATH\f[R] environment variable. |
| If the class path option isn\[aq]t used and \f[I]classpath\f[R] isn\[aq]t |
| set, then the user class path consists of the current directory (.). |
| .PP |
| As a special convenience, a class path element that contains a base name |
| of an asterisk (*) is considered equivalent to specifying a list of all |
| the files in the directory with the extension \f[CB]\&.jar\f[R] or |
| \f[CB]\&.JAR\f[R] . |
| A Java program can\[aq]t tell the difference between the two |
| invocations. |
| For example, if the directory mydir contains \f[CB]a.jar\f[R] and |
| \f[CB]b.JAR\f[R], then the class path element mydir/* is expanded to |
| \f[CB]A.jar:b.JAR\f[R], except that the order of JAR files is unspecified. |
| All \f[CB]\&.jar\f[R] files in the specified directory, even hidden ones, |
| are included in the list. |
| A class path entry consisting of an asterisk (*) expands to a list of |
| all the jar files in the current directory. |
| The \f[CB]CLASSPATH\f[R] environment variable, where defined, is similarly |
| expanded. |
| Any class path wildcard expansion that occurs before the Java VM is |
| started. |
| Java programs never see wildcards that aren\[aq]t expanded except by |
| querying the environment, such as by calling |
| \f[CB]System.getenv("CLASSPATH")\f[R]. |
| .RE |
| .TP |
| .B \f[CB]\-\-disable\-\@files\f[R] |
| Can be used anywhere on the command line, including in an argument file, |
| to prevent further \f[CB]\@filename\f[R] expansion. |
| This option stops expanding \f[CB]\@\f[R]\-argfiles after the option. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-\-enable\-preview\f[R] |
| Allows classes to depend on \f[B]preview features\f[R] |
| [https://docs.oracle.com/en/java/javase/12/language/index.html#JSLAN\-GUID\-5A82FE0E\-0CA4\-4F1F\-B075\-564874FE2823] |
| of the release. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-\-module\-path\f[R] \f[I]modulepath\f[R]... or \f[CB]\-p\f[R] \f[I]modulepath\f[R] |
| A semicolon (\f[CB];\f[R]) separated list of directories in which each |
| directory is a directory of modules. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-\-upgrade\-module\-path\f[R] \f[I]modulepath\f[R]... |
| A semicolon (\f[CB];\f[R]) separated list of directories in which each |
| directory is a directory of modules that replace upgradeable modules in |
| the runtime image. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-\-add\-modules\f[R] \f[I]module\f[R][\f[CB],\f[R]\f[I]module\f[R]...] |
| Specifies the root modules to resolve in addition to the initial module. |
| \f[I]module\f[R] also can be \f[CB]ALL\-DEFAULT\f[R], \f[CB]ALL\-SYSTEM\f[R], |
| and \f[CB]ALL\-MODULE\-PATH\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-\-list\-modules\f[R] |
| Lists the observable modules and then exits. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-d\f[R] \f[I]module_name\f[R] or \f[CB]\-\-describe\-module\f[R] \f[I]module_name\f[R] |
| Describes a specified module and then exits. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-\-dry\-run\f[R] |
| Creates the VM but doesn\[aq]t execute the main method. |
| This \f[CB]\-\-dry\-run\f[R] option might be useful for validating the |
| command\-line options such as the module system configuration. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-\-validate\-modules\f[R] |
| Validates all modules and exit. |
| This option is helpful for finding conflicts and other errors with |
| modules on the module path. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-D\f[R]\f[I]property\f[R]\f[CB]=\f[R]\f[I]value\f[R] |
| Sets a system property value. |
| The \f[I]property\f[R] variable is a string with no spaces that |
| represents the name of the property. |
| The \f[I]value\f[R] variable is a string that represents the value of the |
| property. |
| If \f[I]value\f[R] is a string with spaces, then enclose it in quotation |
| marks (for example \f[CB]\-Dfoo="foo\ bar"\f[R]). |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-disableassertions\f[R][\f[CB]:\f[R][\f[I]packagename\f[R]]...|\f[CB]:\f[R]\f[I]classname\f[R]] or \f[CB]\-da\f[R][\f[CB]:\f[R][\f[I]packagename\f[R]]...|\f[CB]:\f[R]\f[I]classname\f[R]] |
| Disables assertions. |
| By default, assertions are disabled in all packages and classes. |
| With no arguments, \f[CB]\-disableassertions\f[R] (\f[CB]\-da\f[R]) disables |
| assertions in all packages and classes. |
| With the \f[I]packagename\f[R] argument ending in \f[CB]\&...\f[R], the |
| switch disables assertions in the specified package and any subpackages. |
| If the argument is simply \f[CB]\&...\f[R], then the switch disables |
| assertions in the unnamed package in the current working directory. |
| With the \f[I]classname\f[R] argument, the switch disables assertions in |
| the specified class. |
| .RS |
| .PP |
| The \f[CB]\-disableassertions\f[R] (\f[CB]\-da\f[R]) option applies to all |
| class loaders and to system classes (which don\[aq]t have a class |
| loader). |
| There\[aq]s one exception to this rule: If the option is provided with |
| no arguments, then it doesn\[aq]t apply to system classes. |
| This makes it easy to disable assertions in all classes except for |
| system classes. |
| The \f[CB]\-disablesystemassertions\f[R] option enables you to disable |
| assertions in all system classes. |
| To explicitly enable assertions in specific packages or classes, use the |
| \f[CB]\-enableassertions\f[R] (\f[CB]\-ea\f[R]) option. |
| Both options can be used at the same time. |
| For example, to run the \f[CB]MyClass\f[R] application with assertions |
| enabled in the package \f[CB]com.wombat.fruitbat\f[R] (and any |
| subpackages) but disabled in the class |
| \f[CB]com.wombat.fruitbat.Brickbat\f[R], use the following command: |
| .RS |
| .PP |
| \f[CB]java\ \-ea:com.wombat.fruitbat...\ \-da:com.wombat.fruitbat.Brickbat\ MyClass\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-disablesystemassertions\f[R] or \f[CB]\-dsa\f[R] |
| Disables assertions in all system classes. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-enableassertions\f[R][\f[CB]:\f[R][\f[I]packagename\f[R]]...|\f[CB]:\f[R]\f[I]classname\f[R]] or \f[CB]\-ea\f[R][\f[CB]:\f[R][\f[I]packagename\f[R]]...|\f[CB]:\f[R]\f[I]classname\f[R]] |
| Enables assertions. |
| By default, assertions are disabled in all packages and classes. |
| With no arguments, \f[CB]\-enableassertions\f[R] (\f[CB]\-ea\f[R]) enables |
| assertions in all packages and classes. |
| With the \f[I]packagename\f[R] argument ending in \f[CB]\&...\f[R], the |
| switch enables assertions in the specified package and any subpackages. |
| If the argument is simply \f[CB]\&...\f[R], then the switch enables |
| assertions in the unnamed package in the current working directory. |
| With the \f[I]classname\f[R] argument, the switch enables assertions in |
| the specified class. |
| .RS |
| .PP |
| The \f[CB]\-enableassertions\f[R] (\f[CB]\-ea\f[R]) option applies to all |
| class loaders and to system classes (which don\[aq]t have a class |
| loader). |
| There\[aq]s one exception to this rule: If the option is provided with |
| no arguments, then it doesn\[aq]t apply to system classes. |
| This makes it easy to enable assertions in all classes except for system |
| classes. |
| The \f[CB]\-enablesystemassertions\f[R] option provides a separate switch |
| to enable assertions in all system classes. |
| To explicitly disable assertions in specific packages or classes, use |
| the \f[CB]\-disableassertions\f[R] (\f[CB]\-da\f[R]) option. |
| If a single command contains multiple instances of these switches, then |
| they\[aq]re processed in order, before loading any classes. |
| For example, to run the \f[CB]MyClass\f[R] application with assertions |
| enabled only in the package \f[CB]com.wombat.fruitbat\f[R] (and any |
| subpackages) but disabled in the class |
| \f[CB]com.wombat.fruitbat.Brickbat\f[R], use the following command: |
| .RS |
| .PP |
| \f[CB]java\ \-ea:com.wombat.fruitbat...\ \-da:com.wombat.fruitbat.Brickbat\ MyClass\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-enablesystemassertions\f[R] or \f[CB]\-esa\f[R] |
| Enables assertions in all system classes. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-help\f[R], \f[CB]\-h\f[R], or \f[CB]\-?\f[R] |
| Prints the help message to the error stream. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-\-help\f[R] |
| Prints the help message to the output stream. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-javaagent:\f[R]\f[I]jarpath\f[R][\f[CB]=\f[R]\f[I]options\f[R]] |
| Loads the specified Java programming language agent. |
| See \f[CB]java.lang.instrument\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-\-show\-version\f[R] |
| Prints the product version to the output stream and continues. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-showversion\f[R] |
| Prints the product version to the error stream and continues. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-\-show\-module\-resolution\f[R] |
| Shows module resolution output during startup. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-splash:\f[R]\f[I]imagepath\f[R] |
| Shows the splash screen with the image specified by \f[I]imagepath\f[R]. |
| HiDPI scaled images are automatically supported and used if available. |
| The unscaled image file name, such as \f[CB]image.ext\f[R], should always |
| be passed as the argument to the \f[CB]\-splash\f[R] option. |
| The most appropriate scaled image provided is picked up automatically. |
| .RS |
| .PP |
| For example, to show the \f[CB]splash.gif\f[R] file from the |
| \f[CB]images\f[R] directory when starting your application, use the |
| following option: |
| .RS |
| .PP |
| \f[CB]\-splash:images/splash.gif\f[R] |
| .RE |
| .PP |
| See the SplashScreen API documentation for more information. |
| .RE |
| .TP |
| .B \f[CB]\-verbose:class\f[R] |
| Displays information about each loaded class. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-verbose:gc\f[R] |
| Displays information about each garbage collection (GC) event. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-verbose:jni\f[R] |
| Displays information about the use of native methods and other Java |
| Native Interface (JNI) activity. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-verbose:module\f[R] |
| Displays information about the modules in use. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-\-version\f[R] |
| Prints product version to the output stream and exits. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-version\f[R] |
| Prints product version to the error stream and exits. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-X\f[R] |
| Prints the help on extra options to the error stream. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-\-help\-extra\f[R] |
| Prints the help on extra options to the output stream. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\@\f[R]\f[I]argfile\f[R] |
| Specifies one or more argument files prefixed by \f[CB]\@\f[R] used by the |
| \f[CB]java\f[R] command. |
| It isn\[aq]t uncommon for the \f[CB]java\f[R] command line to be very long |
| because of the \f[CB]\&.jar\f[R] files needed in the classpath. |
| The \f[CB]\@\f[R]\f[I]argfile\f[R] option overcomes command\-line length |
| limitations by enabling the launcher to expand the contents of argument |
| files after shell expansion, but before argument processing. |
| Contents in the argument files are expanded because otherwise, they |
| would be specified on the command line until the |
| \f[CB]\-\-disable\-\@files\f[R] option was encountered. |
| .RS |
| .PP |
| The argument files can also contain the main class name and all options. |
| If an argument file contains all of the options required by the |
| \f[CB]java\f[R] command, then the command line could simply be: |
| .RS |
| .PP |
| \f[CB]java\ \@\f[R]\f[I]argfile\f[R] |
| .RE |
| .PP |
| See \f[B]java Command\-Line Argument Files\f[R] for a description and |
| examples of using \f[CB]\@\f[R]\-argfiles. |
| .RE |
| .SH EXTRA OPTIONS FOR JAVA |
| .PP |
| The following \f[CB]java\f[R] options are general purpose options that are |
| specific to the Java HotSpot Virtual Machine. |
| .TP |
| .B \f[CB]\-Xbatch\f[R] |
| Disables background compilation. |
| By default, the JVM compiles the method as a background task, running |
| the method in interpreter mode until the background compilation is |
| finished. |
| The \f[CB]\-Xbatch\f[R] flag disables background compilation so that |
| compilation of all methods proceeds as a foreground task until |
| completed. |
| This option is equivalent to \f[CB]\-XX:\-BackgroundCompilation\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-Xbootclasspath/a:\f[R]\f[I]directories\f[R]|\f[I]zip\f[R]|\f[I]JAR\-files\f[R] |
| Specifies a list of directories, JAR files, and ZIP archives to append |
| to the end of the default bootstrap class path. |
| .RS |
| .PP |
| \f[B]Linux and macOS:\f[R] Colons (\f[CB]:\f[R]) separate entities in this |
| list. |
| .PP |
| \f[B]Windows:\f[R] Semicolons (\f[CB];\f[R]) separate entities in this |
| list. |
| .RE |
| .TP |
| .B \f[CB]\-Xcheck:jni\f[R] |
| Performs additional checks for Java Native Interface (JNI) functions. |
| .RS |
| .PP |
| The following checks are considered indicative of significant problems |
| with the native code, and the JVM terminates with an irrecoverable error |
| in such cases: |
| .IP \[bu] 2 |
| The thread doing the call is not attached to the JVM. |
| .IP \[bu] 2 |
| The thread doing the call is using the \f[CB]JNIEnv\f[R] belonging to |
| another thread. |
| .IP \[bu] 2 |
| A parameter validation check fails: |
| .RS 2 |
| .IP \[bu] 2 |
| A \f[CB]jfieldID\f[R], or \f[CB]jmethodID\f[R], is detected as being |
| invalid. |
| For example: |
| .RS 2 |
| .IP \[bu] 2 |
| Of the wrong type |
| .IP \[bu] 2 |
| Associated with the wrong class |
| .RE |
| .IP \[bu] 2 |
| A parameter of the wrong type is detected. |
| .IP \[bu] 2 |
| An invalid parameter value is detected. |
| For example: |
| .RS 2 |
| .IP \[bu] 2 |
| NULL where not permitted |
| .IP \[bu] 2 |
| An out\-of\-bounds array index, or frame capacity |
| .IP \[bu] 2 |
| A non\-UTF\-8 string |
| .IP \[bu] 2 |
| An invalid JNI reference |
| .IP \[bu] 2 |
| An attempt to use a \f[CB]ReleaseXXX\f[R] function on a parameter not |
| produced by the corresponding \f[CB]GetXXX\f[R] function |
| .RE |
| .RE |
| .PP |
| The following checks only result in warnings being printed: |
| .IP \[bu] 2 |
| A JNI call was made without checking for a pending exception from a |
| previous JNI call, and the current call is not safe when an exception |
| may be pending. |
| .IP \[bu] 2 |
| The number of JNI local references existing when a JNI function |
| terminates exceeds the number guaranteed to be available. |
| See the \f[CB]EnsureLocalcapacity\f[R] function. |
| .IP \[bu] 2 |
| A class descriptor is in decorated format (\f[CB]Lname;\f[R]) when it |
| should not be. |
| .IP \[bu] 2 |
| A \f[CB]NULL\f[R] parameter is allowed, but its use is questionable. |
| .IP \[bu] 2 |
| Calling other JNI functions in the scope of |
| \f[CB]Get/ReleasePrimitiveArrayCritical\f[R] or |
| \f[CB]Get/ReleaseStringCritical\f[R] |
| .PP |
| Expect a performance degradation when this option is used. |
| .RE |
| .TP |
| .B \f[CB]\-Xdebug\f[R] |
| Does nothing. |
| Provided for backward compatibility. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-Xdiag\f[R] |
| Shows additional diagnostic messages. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-Xint\f[R] |
| Runs the application in interpreted\-only mode. |
| Compilation to native code is disabled, and all bytecode is executed by |
| the interpreter. |
| The performance benefits offered by the just\-in\-time (JIT) compiler |
| aren\[aq]t present in this mode. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-Xinternalversion\f[R] |
| Displays more detailed JVM version information than the |
| \f[CB]\-version\f[R] option, and then exits. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-Xlog:\f[R]\f[I]option\f[R] |
| Configure or enable logging with the Java Virtual Machine (JVM) unified |
| logging framework. |
| See \f[B]Enable Logging with the JVM Unified Logging Framework\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-Xmixed\f[R] |
| Executes all bytecode by the interpreter except for hot methods, which |
| are compiled to native code. |
| On by default. |
| Use \f[CB]\-Xint\f[R] to switch off. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-Xmn\f[R] \f[I]size\f[R] |
| Sets the initial and maximum size (in bytes) of the heap for the young |
| generation (nursery) in the generational collectors. |
| Append the letter \f[CB]k\f[R] or \f[CB]K\f[R] to indicate kilobytes, |
| \f[CB]m\f[R] or \f[CB]M\f[R] to indicate megabytes, or \f[CB]g\f[R] or |
| \f[CB]G\f[R] to indicate gigabytes. |
| The young generation region of the heap is used for new objects. |
| GC is performed in this region more often than in other regions. |
| If the size for the young generation is too small, then a lot of minor |
| garbage collections are performed. |
| If the size is too large, then only full garbage collections are |
| performed, which can take a long time to complete. |
| It is recommended that you do not set the size for the young generation |
| for the G1 collector, and keep the size for the young generation greater |
| than 25% and less than 50% of the overall heap size for other |
| collectors. |
| The following examples show how to set the initial and maximum size of |
| young generation to 256 MB using various units: |
| .RS |
| .IP |
| .nf |
| \f[CB] |
| \-Xmn256m |
| \-Xmn262144k |
| \-Xmn268435456 |
| \f[R] |
| .fi |
| .PP |
| Instead of the \f[CB]\-Xmn\f[R] option to set both the initial and maximum |
| size of the heap for the young generation, you can use |
| \f[CB]\-XX:NewSize\f[R] to set the initial size and |
| \f[CB]\-XX:MaxNewSize\f[R] to set the maximum size. |
| .RE |
| .TP |
| .B \f[CB]\-Xms\f[R] \f[I]size\f[R] |
| Sets the minimum and initial size (in bytes) of the heap. |
| This value must be a multiple of 1024 and greater than 1 MB. |
| Append the letter \f[CB]k\f[R] or \f[CB]K\f[R] to indicate kilobytes, |
| \f[CB]m\f[R] or \f[CB]M\f[R] to indicate megabytes, \f[CB]g\f[R] or \f[CB]G\f[R] |
| to indicate gigabytes. |
| The following examples show how to set the size of allocated memory to 6 |
| MB using various units: |
| .RS |
| .IP |
| .nf |
| \f[CB] |
| \-Xms6291456 |
| \-Xms6144k |
| \-Xms6m |
| \f[R] |
| .fi |
| .PP |
| Instead of the \f[CB]\-Xms\f[R] option to set both the minimum and initial |
| size of the heap, you can use \f[CB]\-XX:MinHeapSize\f[R] to set the |
| minimum size and \f[CB]\-XX:InitialHeapSize\f[R] to set the initial size. |
| .PP |
| If you don\[aq]t set this option, the initial size is set as the sum of |
| the sizes allocated for the old generation and the young generation. |
| The initial size of the heap for the young generation can be set using |
| the \f[CB]\-Xmn\f[R] option or the \f[CB]\-XX:NewSize\f[R] option. |
| .RE |
| .TP |
| .B \f[CB]\-Xmx\f[R] \f[I]size\f[R] |
| Specifies the maximum size (in bytes) of the heap. |
| This value must be a multiple of 1024 and greater than 2 MB. |
| Append the letter \f[CB]k\f[R] or \f[CB]K\f[R] to indicate kilobytes, |
| \f[CB]m\f[R] or \f[CB]M\f[R] to indicate megabytes, or \f[CB]g\f[R] or |
| \f[CB]G\f[R] to indicate gigabytes. |
| The default value is chosen at runtime based on system configuration. |
| For server deployments, \f[CB]\-Xms\f[R] and \f[CB]\-Xmx\f[R] are often set |
| to the same value. |
| The following examples show how to set the maximum allowed size of |
| allocated memory to 80 MB using various units: |
| .RS |
| .IP |
| .nf |
| \f[CB] |
| \-Xmx83886080 |
| \-Xmx81920k |
| \-Xmx80m |
| \f[R] |
| .fi |
| .PP |
| The \f[CB]\-Xmx\f[R] option is equivalent to \f[CB]\-XX:MaxHeapSize\f[R]. |
| .RE |
| .TP |
| .B \f[CB]\-Xnoclassgc\f[R] |
| Disables garbage collection (GC) of classes. |
| This can save some GC time, which shortens interruptions during the |
| application run. |
| When you specify \f[CB]\-Xnoclassgc\f[R] at startup, the class objects in |
| the application are left untouched during GC and are always be |
| considered live. |
| This can result in more memory being permanently occupied which, if not |
| used carefully, throws an out\-of\-memory exception. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-Xrs\f[R] |
| Reduces the use of operating system signals by the JVM. |
| Shutdown hooks enable the orderly shutdown of a Java application by |
| running user cleanup code (such as closing database connections) at |
| shutdown, even if the JVM terminates abruptly. |
| .RS |
| .IP \[bu] 2 |
| \f[B]Linux and macOS:\f[R] |
| .RS 2 |
| .IP \[bu] 2 |
| The JVM catches signals to implement shutdown hooks for unexpected |
| termination. |
| The JVM uses \f[CB]SIGHUP\f[R], \f[CB]SIGINT\f[R], and \f[CB]SIGTERM\f[R] to |
| initiate the running of shutdown hooks. |
| .IP \[bu] 2 |
| Applications embedding the JVM frequently need to trap signals such as |
| \f[CB]SIGINT\f[R] or \f[CB]SIGTERM\f[R], which can lead to interference with |
| the JVM signal handlers. |
| The \f[CB]\-Xrs\f[R] option is available to address this issue. |
| When \f[CB]\-Xrs\f[R] is used, the signal masks for \f[CB]SIGINT\f[R], |
| \f[CB]SIGTERM\f[R], \f[CB]SIGHUP\f[R], and \f[CB]SIGQUIT\f[R] aren\[aq]t |
| changed by the JVM, and signal handlers for these signals aren\[aq]t |
| installed. |
| .RE |
| .IP \[bu] 2 |
| \f[B]Windows:\f[R] |
| .RS 2 |
| .IP \[bu] 2 |
| The JVM watches for console control events to implement shutdown hooks |
| for unexpected termination. |
| Specifically, the JVM registers a console control handler that begins |
| shutdown\-hook processing and returns \f[CB]TRUE\f[R] for |
| \f[CB]CTRL_C_EVENT\f[R], \f[CB]CTRL_CLOSE_EVENT\f[R], |
| \f[CB]CTRL_LOGOFF_EVENT\f[R], and \f[CB]CTRL_SHUTDOWN_EVENT\f[R]. |
| .IP \[bu] 2 |
| The JVM uses a similar mechanism to implement the feature of dumping |
| thread stacks for debugging purposes. |
| The JVM uses \f[CB]CTRL_BREAK_EVENT\f[R] to perform thread dumps. |
| .IP \[bu] 2 |
| If the JVM is run as a service (for example, as a servlet engine for a |
| web server), then it can receive \f[CB]CTRL_LOGOFF_EVENT\f[R] but |
| shouldn\[aq]t initiate shutdown because the operating system doesn\[aq]t |
| actually terminate the process. |
| To avoid possible interference such as this, the \f[CB]\-Xrs\f[R] option |
| can be used. |
| When the \f[CB]\-Xrs\f[R] option is used, the JVM doesn\[aq]t install a |
| console control handler, implying that it doesn\[aq]t watch for or |
| process \f[CB]CTRL_C_EVENT\f[R], \f[CB]CTRL_CLOSE_EVENT\f[R], |
| \f[CB]CTRL_LOGOFF_EVENT\f[R], or \f[CB]CTRL_SHUTDOWN_EVENT\f[R]. |
| .RE |
| .PP |
| There are two consequences of specifying \f[CB]\-Xrs\f[R]: |
| .IP \[bu] 2 |
| \f[B]Linux and macOS:\f[R] \f[CB]SIGQUIT\f[R] thread dumps aren\[aq]t |
| available. |
| .IP \[bu] 2 |
| \f[B]Windows:\f[R] Ctrl + Break thread dumps aren\[aq]t available. |
| .PP |
| User code is responsible for causing shutdown hooks to run, for example, |
| by calling the \f[CB]System.exit()\f[R] when the JVM is to be terminated. |
| .RE |
| .TP |
| .B \f[CB]\-Xshare:\f[R]\f[I]mode\f[R] |
| Sets the class data sharing (CDS) mode. |
| .RS |
| .PP |
| Possible \f[I]mode\f[R] arguments for this option include the following: |
| .TP |
| .B \f[CB]auto\f[R] |
| Use shared class data if possible (default). |
| .RS |
| .RE |
| .TP |
| .B \f[CB]on\f[R] |
| Require using shared class data, otherwise fail. |
| .RS |
| .RE |
| .RS |
| .PP |
| \f[B]Note:\f[R] The \f[CB]\-Xshare:on\f[R] option is used for testing |
| purposes only and may cause intermittent failures due to the use of |
| address space layout randomization by the operation system. |
| This option should not be used in production environments. |
| .RE |
| .TP |
| .B \f[CB]off\f[R] |
| Do not attempt to use shared class data. |
| .RS |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XshowSettings\f[R] |
| Shows all settings and then continues. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XshowSettings:\f[R]\f[I]category\f[R] |
| Shows settings and continues. |
| Possible \f[I]category\f[R] arguments for this option include the |
| following: |
| .RS |
| .TP |
| .B \f[CB]all\f[R] |
| Shows all categories of settings. |
| This is the default value. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]locale\f[R] |
| Shows settings related to locale. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]properties\f[R] |
| Shows settings related to system properties. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]vm\f[R] |
| Shows the settings of the JVM. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]system\f[R] |
| \f[B]Linux:\f[R] Shows host system or container configuration and |
| continues. |
| .RS |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-Xss\f[R] \f[I]size\f[R] |
| Sets the thread stack size (in bytes). |
| Append the letter \f[CB]k\f[R] or \f[CB]K\f[R] to indicate KB, \f[CB]m\f[R] or |
| \f[CB]M\f[R] to indicate MB, or \f[CB]g\f[R] or \f[CB]G\f[R] to indicate GB. |
| The default value depends on the platform: |
| .RS |
| .IP \[bu] 2 |
| Linux/x64 (64\-bit): 1024 KB |
| .IP \[bu] 2 |
| macOS (64\-bit): 1024 KB |
| .IP \[bu] 2 |
| Windows: The default value depends on virtual memory |
| .PP |
| The following examples set the thread stack size to 1024 KB in different |
| units: |
| .IP |
| .nf |
| \f[CB] |
| \-Xss1m |
| \-Xss1024k |
| \-Xss1048576 |
| \f[R] |
| .fi |
| .PP |
| This option is similar to \f[CB]\-XX:ThreadStackSize\f[R]. |
| .RE |
| .TP |
| .B \f[CB]\-\-add\-reads\f[R] \f[I]module\f[R]\f[CB]=\f[R]\f[I]target\-module\f[R](\f[CB],\f[R]\f[I]target\-module\f[R])* |
| Updates \f[I]module\f[R] to read the \f[I]target\-module\f[R], regardless |
| of the module declaration. |
| \f[I]target\-module\f[R] can be all unnamed to read all unnamed modules. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-\-add\-exports\f[R] \f[I]module\f[R]\f[CB]/\f[R]\f[I]package\f[R]\f[CB]=\f[R]\f[I]target\-module\f[R](\f[CB],\f[R]\f[I]target\-module\f[R])* |
| Updates \f[I]module\f[R] to export \f[I]package\f[R] to |
| \f[I]target\-module\f[R], regardless of module declaration. |
| The \f[I]target\-module\f[R] can be all unnamed to export to all unnamed |
| modules. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-\-add\-opens\f[R] \f[I]module\f[R]\f[CB]/\f[R]\f[I]package\f[R]\f[CB]=\f[R]\f[I]target\-module\f[R](\f[CB],\f[R]\f[I]target\-module\f[R])* |
| Updates \f[I]module\f[R] to open \f[I]package\f[R] to |
| \f[I]target\-module\f[R], regardless of module declaration. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-\-limit\-modules\f[R] \f[I]module\f[R][\f[CB],\f[R]\f[I]module\f[R]...] |
| Specifies the limit of the universe of observable modules. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-\-patch\-module\f[R] \f[I]module\f[R]\f[CB]=\f[R]\f[I]file\f[R](\f[CB];\f[R]\f[I]file\f[R])* |
| Overrides or augments a module with classes and resources in JAR files |
| or directories. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-\-source\f[R] \f[I]version\f[R] |
| Sets the version of the source in source\-file mode. |
| .RS |
| .RE |
| .SH EXTRA OPTIONS FOR MACOS |
| .PP |
| The following extra options are macOS specific. |
| .TP |
| .B \f[CB]\-XstartOnFirstThread\f[R] |
| Runs the \f[CB]main()\f[R] method on the first (AppKit) thread. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-Xdock:name=\f[R]\f[I]application_name\f[R] |
| Overrides the default application name displayed in dock. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-Xdock:icon=\f[R]\f[I]path_to_icon_file\f[R] |
| Overrides the default icon displayed in dock. |
| .RS |
| .RE |
| .SH ADVANCED OPTIONS FOR JAVA |
| .PP |
| These \f[CB]java\f[R] options can be used to enable other advanced |
| options. |
| .TP |
| .B \f[CB]\-XX:+UnlockDiagnosticVMOptions\f[R] |
| Unlocks the options intended for diagnosing the JVM. |
| By default, this option is disabled and diagnostic options aren\[aq]t |
| available. |
| .RS |
| .PP |
| Command line options that are enabled with the use of this option are |
| not supported. |
| If you encounter issues while using any of these options, it is very |
| likely that you will be required to reproduce the problem without using |
| any of these unsupported options before Oracle Support can assist with |
| an investigation. |
| It is also possible that any of these options may be removed or their |
| behavior changed without any warning. |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UnlockExperimentalVMOptions\f[R] |
| Unlocks the options that provide experimental features in the JVM. |
| By default, this option is disabled and experimental features aren\[aq]t |
| available. |
| .RS |
| .RE |
| .SH ADVANCED RUNTIME OPTIONS FOR JAVA |
| .PP |
| These \f[CB]java\f[R] options control the runtime behavior of the Java |
| HotSpot VM. |
| .TP |
| .B \f[CB]\-XX:ActiveProcessorCount=\f[R]\f[I]x\f[R] |
| Overrides the number of CPUs that the VM will use to calculate the size |
| of thread pools it will use for various operations such as Garbage |
| Collection and ForkJoinPool. |
| .RS |
| .PP |
| The VM normally determines the number of available processors from the |
| operating system. |
| This flag can be useful for partitioning CPU resources when running |
| multiple Java processes in docker containers. |
| This flag is honored even if \f[CB]UseContainerSupport\f[R] is not |
| enabled. |
| See \f[CB]\-XX:\-UseContainerSupport\f[R] for a description of enabling |
| and disabling container support. |
| .RE |
| .TP |
| .B \f[CB]\-XX:AllocateHeapAt=\f[R]\f[I]path\f[R] |
| Takes a path to the file system and uses memory mapping to allocate the |
| object heap on the memory device. |
| Using this option enables the HotSpot VM to allocate the Java object |
| heap on an alternative memory device, such as an NV\-DIMM, specified by |
| the user. |
| .RS |
| .PP |
| Alternative memory devices that have the same semantics as DRAM, |
| including the semantics of atomic operations, can be used instead of |
| DRAM for the object heap without changing the existing application code. |
| All other memory structures (such as the code heap, metaspace, and |
| thread stacks) continue to reside in DRAM. |
| .PP |
| Some operating systems expose non\-DRAM memory through the file system. |
| Memory\-mapped files in these file systems bypass the page cache and |
| provide a direct mapping of virtual memory to the physical memory on the |
| device. |
| The existing heap related flags (such as \f[CB]\-Xmx\f[R] and |
| \f[CB]\-Xms\f[R]) and garbage\-collection related flags continue to work |
| as before. |
| .RE |
| .TP |
| .B \f[CB]\-XX:\-CompactStrings\f[R] |
| Disables the Compact Strings feature. |
| By default, this option is enabled. |
| When this option is enabled, Java Strings containing only single\-byte |
| characters are internally represented and stored as |
| single\-byte\-per\-character Strings using ISO\-8859\-1 / Latin\-1 |
| encoding. |
| This reduces, by 50%, the amount of space required for Strings |
| containing only single\-byte characters. |
| For Java Strings containing at least one multibyte character: these are |
| represented and stored as 2 bytes per character using UTF\-16 encoding. |
| Disabling the Compact Strings feature forces the use of UTF\-16 encoding |
| as the internal representation for all Java Strings. |
| .RS |
| .PP |
| Cases where it may be beneficial to disable Compact Strings include the |
| following: |
| .IP \[bu] 2 |
| When it\[aq]s known that an application overwhelmingly will be |
| allocating multibyte character Strings |
| .IP \[bu] 2 |
| In the unexpected event where a performance regression is observed in |
| migrating from Java SE 8 to Java SE 9 and an analysis shows that Compact |
| Strings introduces the regression |
| .PP |
| In both of these scenarios, disabling Compact Strings makes sense. |
| .RE |
| .TP |
| .B \f[CB]\-XX:ErrorFile=\f[R]\f[I]filename\f[R] |
| Specifies the path and file name to which error data is written when an |
| irrecoverable error occurs. |
| By default, this file is created in the current working directory and |
| named \f[CB]hs_err_pid\f[R]\f[I]pid\f[R]\f[CB]\&.log\f[R] where \f[I]pid\f[R] |
| is the identifier of the process that encountered the error. |
| .RS |
| .PP |
| The following example shows how to set the default log file (note that |
| the identifier of the process is specified as \f[CB]%p\f[R]): |
| .RS |
| .PP |
| \f[CB]\-XX:ErrorFile=./hs_err_pid%p.log\f[R] |
| .RE |
| .IP \[bu] 2 |
| \f[B]Linux and macOS:\f[R] The following example shows how to set the |
| error log to \f[CB]/var/log/java/java_error.log\f[R]: |
| .RS 2 |
| .RS |
| .PP |
| \f[CB]\-XX:ErrorFile=/var/log/java/java_error.log\f[R] |
| .RE |
| .RE |
| .IP \[bu] 2 |
| \f[B]Windows:\f[R] The following example shows how to set the error log |
| file to \f[CB]C:/log/java/java_error.log\f[R]: |
| .RS 2 |
| .RS |
| .PP |
| \f[CB]\-XX:ErrorFile=C:/log/java/java_error.log\f[R] |
| .RE |
| .RE |
| .PP |
| If the file exists, and is writeable, then it will be overwritten. |
| Otherwise, if the file can\[aq]t be created in the specified directory |
| (due to insufficient space, permission problem, or another issue), then |
| the file is created in the temporary directory for the operating system: |
| .IP \[bu] 2 |
| \f[B]Linux and macOS:\f[R] The temporary directory is \f[CB]/tmp\f[R]. |
| .IP \[bu] 2 |
| \f[B]Windows:\f[R] The temporary directory is specified by the value of |
| the \f[CB]TMP\f[R] environment variable; if that environment variable |
| isn\[aq]t defined, then the value of the \f[CB]TEMP\f[R] environment |
| variable is used. |
| .RE |
| .TP |
| .B \f[CB]\-XX:+ExtensiveErrorReports\f[R] |
| Enables the reporting of more extensive error information in the |
| \f[CB]ErrorFile\f[R]. |
| This option can be turned on in environments where maximal information |
| is desired \- even if the resulting logs may be quite large and/or |
| contain information that might be considered sensitive. |
| The information can vary from release to release, and across different |
| platforms. |
| By default this option is disabled. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:FlightRecorderOptions=\f[R]\f[I]parameter\f[R]\f[CB]=\f[R]\f[I]value\f[R] (or)\f[CB]\-XX:FlightRecorderOptions:\f[R]\f[I]parameter\f[R]\f[CB]=\f[R]\f[I]value\f[R] |
| Sets the parameters that control the behavior of JFR. |
| .RS |
| .PP |
| The following list contains the available JFR |
| \f[I]parameter\f[R]\f[CB]=\f[R]\f[I]value\f[R] entries: |
| .TP |
| .B \f[CB]globalbuffersize=\f[R]\f[I]size\f[R] |
| Specifies the total amount of primary memory used for data retention. |
| The default value is based on the value specified for |
| \f[CB]memorysize\f[R]. |
| Change the \f[CB]memorysize\f[R] parameter to alter the size of global |
| buffers. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]maxchunksize=\f[R]\f[I]size\f[R] |
| Specifies the maximum size (in bytes) of the data chunks in a recording. |
| Append \f[CB]m\f[R] or \f[CB]M\f[R] to specify the size in megabytes (MB), |
| or \f[CB]g\f[R] or \f[CB]G\f[R] to specify the size in gigabytes (GB). |
| By default, the maximum size of data chunks is set to 12 MB. |
| The minimum allowed is 1 MB. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]memorysize=\f[R]\f[I]size\f[R] |
| Determines how much buffer memory should be used, and sets the |
| \f[CB]globalbuffersize\f[R] and \f[CB]numglobalbuffers\f[R] parameters based |
| on the size specified. |
| Append \f[CB]m\f[R] or \f[CB]M\f[R] to specify the size in megabytes (MB), |
| or \f[CB]g\f[R] or \f[CB]G\f[R] to specify the size in gigabytes (GB). |
| By default, the memory size is set to 10 MB. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]numglobalbuffers\f[R] |
| Specifies the number of global buffers used. |
| The default value is based on the memory size specified. |
| Change the \f[CB]memorysize\f[R] parameter to alter the number of global |
| buffers. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]old\-object\-queue\-size=number\-of\-objects\f[R] |
| Maximum number of old objects to track. |
| By default, the number of objects is set to 256. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]repository=\f[R]\f[I]path\f[R] |
| Specifies the repository (a directory) for temporary disk storage. |
| By default, the system\[aq]s temporary directory is used. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]retransform=\f[R]{\f[CB]true\f[R]|\f[CB]false\f[R]} |
| Specifies whether event classes should be retransformed using JVMTI. |
| If false, instrumentation is added when event classes are loaded. |
| By default, this parameter is enabled. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]samplethreads=\f[R]{\f[CB]true\f[R]|\f[CB]false\f[R]} |
| Specifies whether thread sampling is enabled. |
| Thread sampling occurs only if the sampling event is enabled along with |
| this parameter. |
| By default, this parameter is enabled. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]stackdepth=\f[R]\f[I]depth\f[R] |
| Stack depth for stack traces. |
| By default, the depth is set to 64 method calls. |
| The maximum is 2048. |
| Values greater than 64 could create significant overhead and reduce |
| performance. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]threadbuffersize=\f[R]\f[I]size\f[R] |
| Specifies the per\-thread local buffer size (in bytes). |
| By default, the local buffer size is set to 8 kilobytes, with a minimum |
| value of 4 kilobytes. |
| Overriding this parameter could reduce performance and is not |
| recommended. |
| .RS |
| .RE |
| .PP |
| You can specify values for multiple parameters by separating them with a |
| comma. |
| .RE |
| .TP |
| .B \f[CB]\-XX:LargePageSizeInBytes=\f[R]\f[I]size\f[R] |
| Sets the maximum large page size (in bytes) used by the JVM. |
| The \f[I]size\f[R] argument must be a valid page size supported by the |
| environment to have any effect. |
| Append the letter \f[CB]k\f[R] or \f[CB]K\f[R] to indicate kilobytes, |
| \f[CB]m\f[R] or \f[CB]M\f[R] to indicate megabytes, or \f[CB]g\f[R] or |
| \f[CB]G\f[R] to indicate gigabytes. |
| By default, the size is set to 0, meaning that the JVM will use the |
| default large page size for the environment as the maximum size for |
| large pages. |
| See \f[B]Large Pages\f[R]. |
| .RS |
| .PP |
| The following example describes how to set the large page size to 1 |
| gigabyte (GB): |
| .RS |
| .PP |
| \f[CB]\-XX:LargePageSizeInBytes=1g\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:MaxDirectMemorySize=\f[R]\f[I]size\f[R] |
| Sets the maximum total size (in bytes) of the \f[CB]java.nio\f[R] package, |
| direct\-buffer allocations. |
| Append the letter \f[CB]k\f[R] or \f[CB]K\f[R] to indicate kilobytes, |
| \f[CB]m\f[R] or \f[CB]M\f[R] to indicate megabytes, or \f[CB]g\f[R] or |
| \f[CB]G\f[R] to indicate gigabytes. |
| By default, the size is set to 0, meaning that the JVM chooses the size |
| for NIO direct\-buffer allocations automatically. |
| .RS |
| .PP |
| The following examples illustrate how to set the NIO size to 1024 KB in |
| different units: |
| .IP |
| .nf |
| \f[CB] |
| \-XX:MaxDirectMemorySize=1m |
| \-XX:MaxDirectMemorySize=1024k |
| \-XX:MaxDirectMemorySize=1048576 |
| \f[R] |
| .fi |
| .RE |
| .TP |
| .B \f[CB]\-XX:\-MaxFDLimit\f[R] |
| Disables the attempt to set the soft limit for the number of open file |
| descriptors to the hard limit. |
| By default, this option is enabled on all platforms, but is ignored on |
| Windows. |
| The only time that you may need to disable this is on Mac OS, where its |
| use imposes a maximum of 10240, which is lower than the actual system |
| maximum. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:NativeMemoryTracking=\f[R]\f[I]mode\f[R] |
| Specifies the mode for tracking JVM native memory usage. |
| Possible \f[I]mode\f[R] arguments for this option include the following: |
| .RS |
| .TP |
| .B \f[CB]off\f[R] |
| Instructs not to track JVM native memory usage. |
| This is the default behavior if you don\[aq]t specify the |
| \f[CB]\-XX:NativeMemoryTracking\f[R] option. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]summary\f[R] |
| Tracks memory usage only by JVM subsystems, such as Java heap, class, |
| code, and thread. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]detail\f[R] |
| In addition to tracking memory usage by JVM subsystems, track memory |
| usage by individual \f[CB]CallSite\f[R], individual virtual memory region |
| and its committed regions. |
| .RS |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:ObjectAlignmentInBytes=\f[R]\f[I]alignment\f[R] |
| Sets the memory alignment of Java objects (in bytes). |
| By default, the value is set to 8 bytes. |
| The specified value should be a power of 2, and must be within the range |
| of 8 and 256 (inclusive). |
| This option makes it possible to use compressed pointers with large Java |
| heap sizes. |
| .RS |
| .PP |
| The heap size limit in bytes is calculated as: |
| .RS |
| .PP |
| \f[CB]4GB\ *\ ObjectAlignmentInBytes\f[R] |
| .RE |
| .RS |
| .PP |
| \f[B]Note:\f[R] As the alignment value increases, the unused space |
| between objects also increases. |
| As a result, you may not realize any benefits from using compressed |
| pointers with large Java heap sizes. |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:OnError=\f[R]\f[I]string\f[R] |
| Sets a custom command or a series of semicolon\-separated commands to |
| run when an irrecoverable error occurs. |
| If the string contains spaces, then it must be enclosed in quotation |
| marks. |
| .RS |
| .IP \[bu] 2 |
| \f[B]Linux and macOS:\f[R] The following example shows how the |
| \f[CB]\-XX:OnError\f[R] option can be used to run the \f[CB]gcore\f[R] |
| command to create a core image, and start the \f[CB]gdb\f[R] debugger to |
| attach to the process in case of an irrecoverable error (the \f[CB]%p\f[R] |
| designates the current process identifier): |
| .RS 2 |
| .RS |
| .PP |
| \f[CB]\-XX:OnError="gcore\ %p;gdb\ \-p\ %p"\f[R] |
| .RE |
| .RE |
| .IP \[bu] 2 |
| \f[B]Windows:\f[R] The following example shows how the |
| \f[CB]\-XX:OnError\f[R] option can be used to run the |
| \f[CB]userdump.exe\f[R] utility to obtain a crash dump in case of an |
| irrecoverable error (the \f[CB]%p\f[R] designates the current process |
| identifier). |
| This example assumes that the path to the \f[CB]userdump.exe\f[R] utility |
| is specified in the \f[CB]PATH\f[R] environment variable: |
| .RS 2 |
| .RS |
| .PP |
| \f[CB]\-XX:OnError="userdump.exe\ %p"\f[R] |
| .RE |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:OnOutOfMemoryError=\f[R]\f[I]string\f[R] |
| Sets a custom command or a series of semicolon\-separated commands to |
| run when an \f[CB]OutOfMemoryError\f[R] exception is first thrown. |
| If the string contains spaces, then it must be enclosed in quotation |
| marks. |
| For an example of a command string, see the description of the |
| \f[CB]\-XX:OnError\f[R] option. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+PrintCommandLineFlags\f[R] |
| Enables printing of ergonomically selected JVM flags that appeared on |
| the command line. |
| It can be useful to know the ergonomic values set by the JVM, such as |
| the heap space size and the selected garbage collector. |
| By default, this option is disabled and flags aren\[aq]t printed. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+PreserveFramePointer\f[R] |
| Selects between using the RBP register as a general purpose register |
| (\f[CB]\-XX:\-PreserveFramePointer\f[R]) and using the RBP register to |
| hold the frame pointer of the currently executing method |
| (\f[CB]\-XX:+PreserveFramePointer\f[R] . |
| If the frame pointer is available, then external profiling tools (for |
| example, Linux perf) can construct more accurate stack traces. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+PrintNMTStatistics\f[R] |
| Enables printing of collected native memory tracking data at JVM exit |
| when native memory tracking is enabled (see |
| \f[CB]\-XX:NativeMemoryTracking\f[R]). |
| By default, this option is disabled and native memory tracking data |
| isn\[aq]t printed. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:SharedArchiveFile=\f[R]\f[I]path\f[R] |
| Specifies the path and name of the class data sharing (CDS) archive file |
| .RS |
| .PP |
| See \f[B]Application Class Data Sharing\f[R]. |
| .RE |
| .TP |
| .B \f[CB]\-XX:SharedArchiveConfigFile\f[R]=\f[I]shared_config_file\f[R] |
| Specifies additional shared data added to the archive file. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:SharedClassListFile=\f[R]\f[I]file_name\f[R] |
| Specifies the text file that contains the names of the classes to store |
| in the class data sharing (CDS) archive. |
| This file contains the full name of one class per line, except slashes |
| (\f[CB]/\f[R]) replace dots (\f[CB]\&.\f[R]). |
| For example, to specify the classes \f[CB]java.lang.Object\f[R] and |
| \f[CB]hello.Main\f[R], create a text file that contains the following two |
| lines: |
| .RS |
| .IP |
| .nf |
| \f[CB] |
| java/lang/Object |
| hello/Main |
| \f[R] |
| .fi |
| .PP |
| The classes that you specify in this text file should include the |
| classes that are commonly used by the application. |
| They may include any classes from the application, extension, or |
| bootstrap class paths. |
| .PP |
| See \f[B]Application Class Data Sharing\f[R]. |
| .RE |
| .TP |
| .B \f[CB]\-XX:+ShowCodeDetailsInExceptionMessages\f[R] |
| Enables printing of improved \f[CB]NullPointerException\f[R] messages. |
| When an application throws a \f[CB]NullPointerException\f[R], the option |
| enables the JVM to analyze the program\[aq]s bytecode instructions to |
| determine precisely which reference is \f[CB]null\f[R], and describes the |
| source with a null\-detail message. |
| The null\-detail message is calculated and returned by |
| \f[CB]NullPointerException.getMessage()\f[R], and will be printed as the |
| exception message along with the method, filename, and line number. |
| By default, this option is enabled. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+ShowMessageBoxOnError\f[R] |
| Enables the display of a dialog box when the JVM experiences an |
| irrecoverable error. |
| This prevents the JVM from exiting and keeps the process active so that |
| you can attach a debugger to it to investigate the cause of the error. |
| By default, this option is disabled. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:StartFlightRecording=\f[R]\f[I]parameter\f[R]\f[CB]=\f[R]\f[I]value\f[R] |
| Starts a JFR recording for the Java application. |
| This option is equivalent to the \f[CB]JFR.start\f[R] diagnostic command |
| that starts a recording during runtime. |
| You can set the following \f[I]parameter\f[R]\f[CB]=\f[R]\f[I]value\f[R] |
| entries when starting a JFR recording: |
| .RS |
| .TP |
| .B \f[CB]delay=\f[R]\f[I]time\f[R] |
| Specifies the delay between the Java application launch time and the |
| start of the recording. |
| Append \f[CB]s\f[R] to specify the time in seconds, \f[CB]m\f[R] for |
| minutes, \f[CB]h\f[R] for hours, or \f[CB]d\f[R] for days (for example, |
| specifying \f[CB]10m\f[R] means 10 minutes). |
| By default, there\[aq]s no delay, and this parameter is set to 0. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]disk=\f[R]{\f[CB]true\f[R]|\f[CB]false\f[R]} |
| Specifies whether to write data to disk while recording. |
| By default, this parameter is enabled. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]dumponexit=\f[R]{\f[CB]true\f[R]|\f[CB]false\f[R]} |
| Specifies if the running recording is dumped when the JVM shuts down. |
| If enabled and a \f[CB]filename\f[R] is not entered, the recording is |
| written to a file in the directory where the process was started. |
| The file name is a system\-generated name that contains the process ID, |
| recording ID, and current timestamp, similar to |
| \f[CB]hotspot\-pid\-47496\-id\-1\-2018_01_25_19_10_41.jfr\f[R]. |
| By default, this parameter is disabled. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]duration=\f[R]\f[I]time\f[R] |
| Specifies the duration of the recording. |
| Append \f[CB]s\f[R] to specify the time in seconds, \f[CB]m\f[R] for |
| minutes, \f[CB]h\f[R] for hours, or \f[CB]d\f[R] for days (for example, |
| specifying \f[CB]5h\f[R] means 5 hours). |
| By default, the duration isn\[aq]t limited, and this parameter is set to |
| 0. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]filename=\f[R]\f[I]path\f[R] |
| Specifies the path and name of the file to which the recording is |
| written when the recording is stopped, for example: |
| .RS |
| .IP \[bu] 2 |
| \f[CB]recording.jfr\f[R] |
| .IP \[bu] 2 |
| \f[CB]/home/user/recordings/recording.jfr\f[R] |
| .IP \[bu] 2 |
| \f[CB]c:\\recordings\\recording.jfr\f[R] |
| .RE |
| .TP |
| .B \f[CB]name=\f[R]\f[I]identifier\f[R] |
| Takes both the name and the identifier of a recording. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]maxage=\f[R]\f[I]time\f[R] |
| Specifies the maximum age of disk data to keep for the recording. |
| This parameter is valid only when the \f[CB]disk\f[R] parameter is set to |
| \f[CB]true\f[R]. |
| Append \f[CB]s\f[R] to specify the time in seconds, \f[CB]m\f[R] for |
| minutes, \f[CB]h\f[R] for hours, or \f[CB]d\f[R] for days (for example, |
| specifying \f[CB]30s\f[R] means 30 seconds). |
| By default, the maximum age isn\[aq]t limited, and this parameter is set |
| to \f[CB]0s\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]maxsize=\f[R]\f[I]size\f[R] |
| Specifies the maximum size (in bytes) of disk data to keep for the |
| recording. |
| This parameter is valid only when the \f[CB]disk\f[R] parameter is set to |
| \f[CB]true\f[R]. |
| The value must not be less than the value for the \f[CB]maxchunksize\f[R] |
| parameter set with \f[CB]\-XX:FlightRecorderOptions\f[R]. |
| Append \f[CB]m\f[R] or \f[CB]M\f[R] to specify the size in megabytes, or |
| \f[CB]g\f[R] or \f[CB]G\f[R] to specify the size in gigabytes. |
| By default, the maximum size of disk data isn\[aq]t limited, and this |
| parameter is set to \f[CB]0\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]path\-to\-gc\-roots=\f[R]{\f[CB]true\f[R]|\f[CB]false\f[R]} |
| Specifies whether to collect the path to garbage collection (GC) roots |
| at the end of a recording. |
| By default, this parameter is disabled. |
| .RS |
| .PP |
| The path to GC roots is useful for finding memory leaks, but collecting |
| it is time\-consuming. |
| Enable this option only when you start a recording for an application |
| that you suspect has a memory leak. |
| If the \f[CB]settings\f[R] parameter is set to \f[CB]profile\f[R], the stack |
| trace from where the potential leaking object was allocated is included |
| in the information collected. |
| .RE |
| .TP |
| .B \f[CB]settings=\f[R]\f[I]path\f[R] |
| Specifies the path and name of the event settings file (of type JFC). |
| By default, the \f[CB]default.jfc\f[R] file is used, which is located in |
| \f[CB]JAVA_HOME/lib/jfr\f[R]. |
| This default settings file collects a predefined set of information with |
| low overhead, so it has minimal impact on performance and can be used |
| with recordings that run continuously. |
| .RS |
| .PP |
| A second settings file is also provided, profile.jfc, which provides |
| more data than the default configuration, but can have more overhead and |
| impact performance. |
| Use this configuration for short periods of time when more information |
| is needed. |
| .RE |
| .PP |
| You can specify values for multiple parameters by separating them with a |
| comma. |
| Event settings and .jfc options can be specified using the following |
| syntax: |
| .TP |
| .B \f[CB]option=\f[R]\f[I]value\f[R] |
| Specifies the option value to modify. |
| To list available options, use the \f[CB]JAVA_HOME\f[R]/bin/jfr tool. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]event\-setting\f[R]=\f[I]value\f[R] |
| Specifies the event setting value to modify. |
| Use the form: #= To add a new event setting, prefix the event name with |
| \[aq]+\[aq]. |
| .RS |
| .RE |
| .PP |
| You can specify values for multiple event settings and .jfc options by |
| separating them with a comma. |
| In case of a conflict between a parameter and a .jfc option, the |
| parameter will take precedence. |
| The whitespace delimiter can be omitted for timespan values, i.e. |
| 20ms. |
| For more information about the settings syntax, see Javadoc of the |
| jdk.jfr package. |
| .RE |
| .TP |
| .B \f[CB]\-XX:ThreadStackSize=\f[R]\f[I]size\f[R] |
| Sets the Java thread stack size (in kilobytes). |
| Use of a scaling suffix, such as \f[CB]k\f[R], results in the scaling of |
| the kilobytes value so that \f[CB]\-XX:ThreadStackSize=1k\f[R] sets the |
| Java thread stack size to 1024*1024 bytes or 1 megabyte. |
| The default value depends on the platform: |
| .RS |
| .IP \[bu] 2 |
| Linux/x64 (64\-bit): 1024 KB |
| .IP \[bu] 2 |
| macOS (64\-bit): 1024 KB |
| .IP \[bu] 2 |
| Windows: The default value depends on virtual memory |
| .PP |
| The following examples show how to set the thread stack size to 1 |
| megabyte in different units: |
| .IP |
| .nf |
| \f[CB] |
| \-XX:ThreadStackSize=1k |
| \-XX:ThreadStackSize=1024 |
| \f[R] |
| .fi |
| .PP |
| This option is similar to \f[CB]\-Xss\f[R]. |
| .RE |
| .TP |
| .B \f[CB]\-XX:\-UseCompressedOops\f[R] |
| Disables the use of compressed pointers. |
| By default, this option is enabled, and compressed pointers are used. |
| This will automatically limit the maximum ergonomically determined Java |
| heap size to the maximum amount of memory that can be covered by |
| compressed pointers. |
| By default this range is 32 GB. |
| .RS |
| .PP |
| With compressed oops enabled, object references are represented as |
| 32\-bit offsets instead of 64\-bit pointers, which typically increases |
| performance when running the application with Java heap sizes smaller |
| than the compressed oops pointer range. |
| This option works only for 64\-bit JVMs. |
| .PP |
| It\[aq]s possible to use compressed pointers with Java heap sizes |
| greater than 32 GB. |
| See the \f[CB]\-XX:ObjectAlignmentInBytes\f[R] option. |
| .RE |
| .TP |
| .B \f[CB]\-XX:\-UseContainerSupport\f[R] |
| The VM now provides automatic container detection support, which allows |
| the VM to determine the amount of memory and number of processors that |
| are available to a Java process running in docker containers. |
| It uses this information to allocate system resources. |
| This support is only available on Linux x64 platforms. |
| If supported, the default for this flag is \f[CB]true\f[R], and container |
| support is enabled by default. |
| It can be disabled with \f[CB]\-XX:\-UseContainerSupport\f[R]. |
| .RS |
| .PP |
| Unified Logging is available to help to diagnose issues related to this |
| support. |
| .PP |
| Use \f[CB]\-Xlog:os+container=trace\f[R] for maximum logging of container |
| information. |
| See \f[B]Enable Logging with the JVM Unified Logging Framework\f[R] for a |
| description of using Unified Logging. |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseHugeTLBFS\f[R] |
| \f[B]Linux only:\f[R] This option is the equivalent of specifying |
| \f[CB]\-XX:+UseLargePages\f[R]. |
| This option is disabled by default. |
| This option pre\-allocates all large pages up\-front, when memory is |
| reserved; consequently the JVM can\[aq]t dynamically grow or shrink |
| large pages memory areas; see \f[CB]\-XX:UseTransparentHugePages\f[R] if |
| you want this behavior. |
| .RS |
| .PP |
| See \f[B]Large Pages\f[R]. |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseLargePages\f[R] |
| Enables the use of large page memory. |
| By default, this option is disabled and large page memory isn\[aq]t |
| used. |
| .RS |
| .PP |
| See \f[B]Large Pages\f[R]. |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseTransparentHugePages\f[R] |
| \f[B]Linux only:\f[R] Enables the use of large pages that can dynamically |
| grow or shrink. |
| This option is disabled by default. |
| You may encounter performance problems with transparent huge pages as |
| the OS moves other pages around to create huge pages; this option is |
| made available for experimentation. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+AllowUserSignalHandlers\f[R] |
| Enables installation of signal handlers by the application. |
| By default, this option is disabled and the application isn\[aq]t |
| allowed to install signal handlers. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:VMOptionsFile=\f[R]\f[I]filename\f[R] |
| Allows user to specify VM options in a file, for example, |
| \f[CB]java\ \-XX:VMOptionsFile=/var/my_vm_options\ HelloWorld\f[R]. |
| .RS |
| .RE |
| .SH ADVANCED JIT COMPILER OPTIONS FOR JAVA |
| .PP |
| These \f[CB]java\f[R] options control the dynamic just\-in\-time (JIT) |
| compilation performed by the Java HotSpot VM. |
| .TP |
| .B \f[CB]\-XX:AllocateInstancePrefetchLines=\f[R]\f[I]lines\f[R] |
| Sets the number of lines to prefetch ahead of the instance allocation |
| pointer. |
| By default, the number of lines to prefetch is set to 1: |
| .RS |
| .RS |
| .PP |
| \f[CB]\-XX:AllocateInstancePrefetchLines=1\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:AllocatePrefetchDistance=\f[R]\f[I]size\f[R] |
| Sets the size (in bytes) of the prefetch distance for object allocation. |
| Memory about to be written with the value of new objects is prefetched |
| up to this distance starting from the address of the last allocated |
| object. |
| Each Java thread has its own allocation point. |
| .RS |
| .PP |
| Negative values denote that prefetch distance is chosen based on the |
| platform. |
| Positive values are bytes to prefetch. |
| Append the letter \f[CB]k\f[R] or \f[CB]K\f[R] to indicate kilobytes, |
| \f[CB]m\f[R] or \f[CB]M\f[R] to indicate megabytes, or \f[CB]g\f[R] or |
| \f[CB]G\f[R] to indicate gigabytes. |
| The default value is set to \-1. |
| .PP |
| The following example shows how to set the prefetch distance to 1024 |
| bytes: |
| .RS |
| .PP |
| \f[CB]\-XX:AllocatePrefetchDistance=1024\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:AllocatePrefetchInstr=\f[R]\f[I]instruction\f[R] |
| Sets the prefetch instruction to prefetch ahead of the allocation |
| pointer. |
| Possible values are from 0 to 3. |
| The actual instructions behind the values depend on the platform. |
| By default, the prefetch instruction is set to 0: |
| .RS |
| .RS |
| .PP |
| \f[CB]\-XX:AllocatePrefetchInstr=0\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:AllocatePrefetchLines=\f[R]\f[I]lines\f[R] |
| Sets the number of cache lines to load after the last object allocation |
| by using the prefetch instructions generated in compiled code. |
| The default value is 1 if the last allocated object was an instance, and |
| 3 if it was an array. |
| .RS |
| .PP |
| The following example shows how to set the number of loaded cache lines |
| to 5: |
| .RS |
| .PP |
| \f[CB]\-XX:AllocatePrefetchLines=5\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:AllocatePrefetchStepSize=\f[R]\f[I]size\f[R] |
| Sets the step size (in bytes) for sequential prefetch instructions. |
| Append the letter \f[CB]k\f[R] or \f[CB]K\f[R] to indicate kilobytes, |
| \f[CB]m\f[R] or \f[CB]M\f[R] to indicate megabytes, \f[CB]g\f[R] or \f[CB]G\f[R] |
| to indicate gigabytes. |
| By default, the step size is set to 16 bytes: |
| .RS |
| .RS |
| .PP |
| \f[CB]\-XX:AllocatePrefetchStepSize=16\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:AllocatePrefetchStyle=\f[R]\f[I]style\f[R] |
| Sets the generated code style for prefetch instructions. |
| The \f[I]style\f[R] argument is an integer from 0 to 3: |
| .RS |
| .TP |
| .B \f[CB]0\f[R] |
| Don\[aq]t generate prefetch instructions. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]1\f[R] |
| Execute prefetch instructions after each allocation. |
| This is the default setting. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]2\f[R] |
| Use the thread\-local allocation block (TLAB) watermark pointer to |
| determine when prefetch instructions are executed. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]3\f[R] |
| Generate one prefetch instruction per cache line. |
| .RS |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:+BackgroundCompilation\f[R] |
| Enables background compilation. |
| This option is enabled by default. |
| To disable background compilation, specify |
| \f[CB]\-XX:\-BackgroundCompilation\f[R] (this is equivalent to specifying |
| \f[CB]\-Xbatch\f[R]). |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:CICompilerCount=\f[R]\f[I]threads\f[R] |
| Sets the number of compiler threads to use for compilation. |
| By default, the number of compiler threads is selected automatically |
| depending on the number of CPUs and memory available for compiled code. |
| The following example shows how to set the number of threads to 2: |
| .RS |
| .RS |
| .PP |
| \f[CB]\-XX:CICompilerCount=2\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseDynamicNumberOfCompilerThreads\f[R] |
| Dynamically create compiler thread up to the limit specified by |
| \f[CB]\-XX:CICompilerCount\f[R]. |
| This option is enabled by default. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:CompileCommand=\f[R]\f[I]command\f[R]\f[CB],\f[R]\f[I]method\f[R][\f[CB],\f[R]\f[I]option\f[R]] |
| Specifies a \f[I]command\f[R] to perform on a \f[I]method\f[R]. |
| For example, to exclude the \f[CB]indexOf()\f[R] method of the |
| \f[CB]String\f[R] class from being compiled, use the following: |
| .RS |
| .RS |
| .PP |
| \f[CB]\-XX:CompileCommand=exclude,java/lang/String.indexOf\f[R] |
| .RE |
| .PP |
| Note that the full class name is specified, including all packages and |
| subpackages separated by a slash (\f[CB]/\f[R]). |
| For easier cut\-and\-paste operations, it\[aq]s also possible to use the |
| method name format produced by the \f[CB]\-XX:+PrintCompilation\f[R] and |
| \f[CB]\-XX:+LogCompilation\f[R] options: |
| .RS |
| .PP |
| \f[CB]\-XX:CompileCommand=exclude,java.lang.String::indexOf\f[R] |
| .RE |
| .PP |
| If the method is specified without the signature, then the command is |
| applied to all methods with the specified name. |
| However, you can also specify the signature of the method in the class |
| file format. |
| In this case, you should enclose the arguments in quotation marks, |
| because otherwise the shell treats the semicolon as a command end. |
| For example, if you want to exclude only the \f[CB]indexOf(String)\f[R] |
| method of the \f[CB]String\f[R] class from being compiled, use the |
| following: |
| .RS |
| .PP |
| \f[CB]\-XX:CompileCommand="exclude,java/lang/String.indexOf,(Ljava/lang/String;)I"\f[R] |
| .RE |
| .PP |
| You can also use the asterisk (*) as a wildcard for class and method |
| names. |
| For example, to exclude all \f[CB]indexOf()\f[R] methods in all classes |
| from being compiled, use the following: |
| .RS |
| .PP |
| \f[CB]\-XX:CompileCommand=exclude,*.indexOf\f[R] |
| .RE |
| .PP |
| The commas and periods are aliases for spaces, making it easier to pass |
| compiler commands through a shell. |
| You can pass arguments to \f[CB]\-XX:CompileCommand\f[R] using spaces as |
| separators by enclosing the argument in quotation marks: |
| .RS |
| .PP |
| \f[CB]\-XX:CompileCommand="exclude\ java/lang/String\ indexOf"\f[R] |
| .RE |
| .PP |
| Note that after parsing the commands passed on the command line using |
| the \f[CB]\-XX:CompileCommand\f[R] options, the JIT compiler then reads |
| commands from the \f[CB]\&.hotspot_compiler\f[R] file. |
| You can add commands to this file or specify a different file using the |
| \f[CB]\-XX:CompileCommandFile\f[R] option. |
| .PP |
| To add several commands, either specify the \f[CB]\-XX:CompileCommand\f[R] |
| option multiple times, or separate each argument with the new line |
| separator (\f[CB]\\n\f[R]). |
| The following commands are available: |
| .TP |
| .B \f[CB]break\f[R] |
| Sets a breakpoint when debugging the JVM to stop at the beginning of |
| compilation of the specified method. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]compileonly\f[R] |
| Excludes all methods from compilation except for the specified method. |
| As an alternative, you can use the \f[CB]\-XX:CompileOnly\f[R] option, |
| which lets you specify several methods. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]dontinline\f[R] |
| Prevents inlining of the specified method. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]exclude\f[R] |
| Excludes the specified method from compilation. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]help\f[R] |
| Prints a help message for the \f[CB]\-XX:CompileCommand\f[R] option. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]inline\f[R] |
| Attempts to inline the specified method. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]log\f[R] |
| Excludes compilation logging (with the \f[CB]\-XX:+LogCompilation\f[R] |
| option) for all methods except for the specified method. |
| By default, logging is performed for all compiled methods. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]option\f[R] |
| Passes a JIT compilation option to the specified method in place of the |
| last argument (\f[CB]option\f[R]). |
| The compilation option is set at the end, after the method name. |
| For example, to enable the \f[CB]BlockLayoutByFrequency\f[R] option for |
| the \f[CB]append()\f[R] method of the \f[CB]StringBuffer\f[R] class, use the |
| following: |
| .RS |
| .RS |
| .PP |
| \f[CB]\-XX:CompileCommand=option,java/lang/StringBuffer.append,BlockLayoutByFrequency\f[R] |
| .RE |
| .PP |
| You can specify multiple compilation options, separated by commas or |
| spaces. |
| .RE |
| .TP |
| .B \f[CB]print\f[R] |
| Prints generated assembler code after compilation of the specified |
| method. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]quiet\f[R] |
| Instructs not to print the compile commands. |
| By default, the commands that you specify with the |
| \f[CB]\-XX:CompileCommand\f[R] option are printed; for example, if you |
| exclude from compilation the \f[CB]indexOf()\f[R] method of the |
| \f[CB]String\f[R] class, then the following is printed to standard output: |
| .RS |
| .RS |
| .PP |
| \f[CB]CompilerOracle:\ exclude\ java/lang/String.indexOf\f[R] |
| .RE |
| .PP |
| You can suppress this by specifying the |
| \f[CB]\-XX:CompileCommand=quiet\f[R] option before other |
| \f[CB]\-XX:CompileCommand\f[R] options. |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:CompileCommandFile=\f[R]\f[I]filename\f[R] |
| Sets the file from which JIT compiler commands are read. |
| By default, the \f[CB]\&.hotspot_compiler\f[R] file is used to store |
| commands performed by the JIT compiler. |
| .RS |
| .PP |
| Each line in the command file represents a command, a class name, and a |
| method name for which the command is used. |
| For example, this line prints assembly code for the \f[CB]toString()\f[R] |
| method of the \f[CB]String\f[R] class: |
| .RS |
| .PP |
| \f[CB]print\ java/lang/String\ toString\f[R] |
| .RE |
| .PP |
| If you\[aq]re using commands for the JIT compiler to perform on methods, |
| then see the \f[CB]\-XX:CompileCommand\f[R] option. |
| .RE |
| .TP |
| .B \f[CB]\-XX:CompilerDirectivesFile=\f[R]\f[I]file\f[R] |
| Adds directives from a file to the directives stack when a program |
| starts. |
| See \f[B]Compiler Control\f[R] |
| [https://docs.oracle.com/en/java/javase/12/vm/compiler\-control1.html#GUID\-94AD8194\-786A\-4F19\-BFFF\-278F8E237F3A]. |
| .RS |
| .PP |
| The \f[CB]\-XX:CompilerDirectivesFile\f[R] option has to be used together |
| with the \f[CB]\-XX:UnlockDiagnosticVMOptions\f[R] option that unlocks |
| diagnostic JVM options. |
| .RE |
| .TP |
| .B \f[CB]\-XX:+CompilerDirectivesPrint\f[R] |
| Prints the directives stack when the program starts or when a new |
| directive is added. |
| .RS |
| .PP |
| The \f[CB]\-XX:+CompilerDirectivesPrint\f[R] option has to be used |
| together with the \f[CB]\-XX:UnlockDiagnosticVMOptions\f[R] option that |
| unlocks diagnostic JVM options. |
| .RE |
| .TP |
| .B \f[CB]\-XX:CompileOnly=\f[R]\f[I]methods\f[R] |
| Sets the list of methods (separated by commas) to which compilation |
| should be restricted. |
| Only the specified methods are compiled. |
| Specify each method with the full class name (including the packages and |
| subpackages). |
| For example, to compile only the \f[CB]length()\f[R] method of the |
| \f[CB]String\f[R] class and the \f[CB]size()\f[R] method of the |
| \f[CB]List\f[R] class, use the following: |
| .RS |
| .RS |
| .PP |
| \f[CB]\-XX:CompileOnly=java/lang/String.length,java/util/List.size\f[R] |
| .RE |
| .PP |
| Note that the full class name is specified, including all packages and |
| subpackages separated by a slash (\f[CB]/\f[R]). |
| For easier cut and paste operations, it\[aq]s also possible to use the |
| method name format produced by the \f[CB]\-XX:+PrintCompilation\f[R] and |
| \f[CB]\-XX:+LogCompilation\f[R] options: |
| .RS |
| .PP |
| \f[CB]\-XX:CompileOnly=java.lang.String::length,java.util.List::size\f[R] |
| .RE |
| .PP |
| Although wildcards aren\[aq]t supported, you can specify only the class |
| or package name to compile all methods in that class or package, as well |
| as specify just the method to compile methods with this name in any |
| class: |
| .IP |
| .nf |
| \f[CB] |
| \-XX:CompileOnly=java/lang/String |
| \-XX:CompileOnly=java/lang |
| \-XX:CompileOnly=.length |
| \f[R] |
| .fi |
| .RE |
| .TP |
| .B \f[CB]\-XX:CompileThresholdScaling=\f[R]\f[I]scale\f[R] |
| Provides unified control of first compilation. |
| This option controls when methods are first compiled for both the tiered |
| and the nontiered modes of operation. |
| The \f[CB]CompileThresholdScaling\f[R] option has a floating point value |
| between 0 and +Inf and scales the thresholds corresponding to the |
| current mode of operation (both tiered and nontiered). |
| Setting \f[CB]CompileThresholdScaling\f[R] to a value less than 1.0 |
| results in earlier compilation while values greater than 1.0 delay |
| compilation. |
| Setting \f[CB]CompileThresholdScaling\f[R] to 0 is equivalent to disabling |
| compilation. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+DoEscapeAnalysis\f[R] |
| Enables the use of escape analysis. |
| This option is enabled by default. |
| To disable the use of escape analysis, specify |
| \f[CB]\-XX:\-DoEscapeAnalysis\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:InitialCodeCacheSize=\f[R]\f[I]size\f[R] |
| Sets the initial code cache size (in bytes). |
| Append the letter \f[CB]k\f[R] or \f[CB]K\f[R] to indicate kilobytes, |
| \f[CB]m\f[R] or \f[CB]M\f[R] to indicate megabytes, or \f[CB]g\f[R] or |
| \f[CB]G\f[R] to indicate gigabytes. |
| The default value depends on the platform. |
| The initial code cache size shouldn\[aq]t be less than the system\[aq]s |
| minimal memory page size. |
| The following example shows how to set the initial code cache size to 32 |
| KB: |
| .RS |
| .RS |
| .PP |
| \f[CB]\-XX:InitialCodeCacheSize=32k\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:+Inline\f[R] |
| Enables method inlining. |
| This option is enabled by default to increase performance. |
| To disable method inlining, specify \f[CB]\-XX:\-Inline\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:InlineSmallCode=\f[R]\f[I]size\f[R] |
| Sets the maximum code size (in bytes) for already compiled methods that |
| may be inlined. |
| This flag only applies to the C2 compiler. |
| Append the letter \f[CB]k\f[R] or \f[CB]K\f[R] to indicate kilobytes, |
| \f[CB]m\f[R] or \f[CB]M\f[R] to indicate megabytes, or \f[CB]g\f[R] or |
| \f[CB]G\f[R] to indicate gigabytes. |
| The default value depends on the platform and on whether tiered |
| compilation is enabled. |
| In the following example it is set to 1000 bytes: |
| .RS |
| .RS |
| .PP |
| \f[CB]\-XX:InlineSmallCode=1000\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:+LogCompilation\f[R] |
| Enables logging of compilation activity to a file named |
| \f[CB]hotspot.log\f[R] in the current working directory. |
| You can specify a different log file path and name using the |
| \f[CB]\-XX:LogFile\f[R] option. |
| .RS |
| .PP |
| By default, this option is disabled and compilation activity isn\[aq]t |
| logged. |
| The \f[CB]\-XX:+LogCompilation\f[R] option has to be used together with |
| the \f[CB]\-XX:UnlockDiagnosticVMOptions\f[R] option that unlocks |
| diagnostic JVM options. |
| .PP |
| You can enable verbose diagnostic output with a message printed to the |
| console every time a method is compiled by using the |
| \f[CB]\-XX:+PrintCompilation\f[R] option. |
| .RE |
| .TP |
| .B \f[CB]\-XX:FreqInlineSize=\f[R]\f[I]size\f[R] |
| Sets the maximum bytecode size (in bytes) of a hot method to be inlined. |
| This flag only applies to the C2 compiler. |
| Append the letter \f[CB]k\f[R] or \f[CB]K\f[R] to indicate kilobytes, |
| \f[CB]m\f[R] or \f[CB]M\f[R] to indicate megabytes, or \f[CB]g\f[R] or |
| \f[CB]G\f[R] to indicate gigabytes. |
| The default value depends on the platform. |
| In the following example it is set to 325 bytes: |
| .RS |
| .RS |
| .PP |
| \f[CB]\-XX:FreqInlineSize=325\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:MaxInlineSize=\f[R]\f[I]size\f[R] |
| Sets the maximum bytecode size (in bytes) of a cold method to be |
| inlined. |
| This flag only applies to the C2 compiler. |
| Append the letter \f[CB]k\f[R] or \f[CB]K\f[R] to indicate kilobytes, |
| \f[CB]m\f[R] or \f[CB]M\f[R] to indicate megabytes, or \f[CB]g\f[R] or |
| \f[CB]G\f[R] to indicate gigabytes. |
| By default, the maximum bytecode size is set to 35 bytes: |
| .RS |
| .RS |
| .PP |
| \f[CB]\-XX:MaxInlineSize=35\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:C1MaxInlineSize=\f[R]\f[I]size\f[R] |
| Sets the maximum bytecode size (in bytes) of a cold method to be |
| inlined. |
| This flag only applies to the C1 compiler. |
| Append the letter \f[CB]k\f[R] or \f[CB]K\f[R] to indicate kilobytes, |
| \f[CB]m\f[R] or \f[CB]M\f[R] to indicate megabytes, or \f[CB]g\f[R] or |
| \f[CB]G\f[R] to indicate gigabytes. |
| By default, the maximum bytecode size is set to 35 bytes: |
| .RS |
| .RS |
| .PP |
| \f[CB]\-XX:MaxInlineSize=35\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:MaxTrivialSize=\f[R]\f[I]size\f[R] |
| Sets the maximum bytecode size (in bytes) of a trivial method to be |
| inlined. |
| This flag only applies to the C2 compiler. |
| Append the letter \f[CB]k\f[R] or \f[CB]K\f[R] to indicate kilobytes, |
| \f[CB]m\f[R] or \f[CB]M\f[R] to indicate megabytes, or \f[CB]g\f[R] or |
| \f[CB]G\f[R] to indicate gigabytes. |
| By default, the maximum bytecode size of a trivial method is set to 6 |
| bytes: |
| .RS |
| .RS |
| .PP |
| \f[CB]\-XX:MaxTrivialSize=6\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:C1MaxTrivialSize=\f[R]\f[I]size\f[R] |
| Sets the maximum bytecode size (in bytes) of a trivial method to be |
| inlined. |
| This flag only applies to the C1 compiler. |
| Append the letter \f[CB]k\f[R] or \f[CB]K\f[R] to indicate kilobytes, |
| \f[CB]m\f[R] or \f[CB]M\f[R] to indicate megabytes, or \f[CB]g\f[R] or |
| \f[CB]G\f[R] to indicate gigabytes. |
| By default, the maximum bytecode size of a trivial method is set to 6 |
| bytes: |
| .RS |
| .RS |
| .PP |
| \f[CB]\-XX:MaxTrivialSize=6\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:MaxNodeLimit=\f[R]\f[I]nodes\f[R] |
| Sets the maximum number of nodes to be used during single method |
| compilation. |
| By default the value depends on the features enabled. |
| In the following example the maximum number of nodes is set to 100,000: |
| .RS |
| .RS |
| .PP |
| \f[CB]\-XX:MaxNodeLimit=100000\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:NonNMethodCodeHeapSize=\f[R]\f[I]size\f[R] |
| Sets the size in bytes of the code segment containing nonmethod code. |
| .RS |
| .PP |
| A nonmethod code segment containing nonmethod code, such as compiler |
| buffers and the bytecode interpreter. |
| This code type stays in the code cache forever. |
| This flag is used only if \f[CB]\-XX:SegmentedCodeCache\f[R] is enabled. |
| .RE |
| .TP |
| .B \f[CB]\-XX:NonProfiledCodeHeapSize=\f[R]\f[I]size\f[R] |
| Sets the size in bytes of the code segment containing nonprofiled |
| methods. |
| This flag is used only if \f[CB]\-XX:SegmentedCodeCache\f[R] is enabled. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+OptimizeStringConcat\f[R] |
| Enables the optimization of \f[CB]String\f[R] concatenation operations. |
| This option is enabled by default. |
| To disable the optimization of \f[CB]String\f[R] concatenation operations, |
| specify \f[CB]\-XX:\-OptimizeStringConcat\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+PrintAssembly\f[R] |
| Enables printing of assembly code for bytecoded and native methods by |
| using the external \f[CB]hsdis\-<arch>.so\f[R] or \f[CB]\&.dll\f[R] library. |
| For 64\-bit VM on Windows, it\[aq]s \f[CB]hsdis\-amd64.dll\f[R]. |
| This lets you to see the generated code, which may help you to diagnose |
| performance issues. |
| .RS |
| .PP |
| By default, this option is disabled and assembly code isn\[aq]t printed. |
| The \f[CB]\-XX:+PrintAssembly\f[R] option has to be used together with the |
| \f[CB]\-XX:UnlockDiagnosticVMOptions\f[R] option that unlocks diagnostic |
| JVM options. |
| .RE |
| .TP |
| .B \f[CB]\-XX:ProfiledCodeHeapSize=\f[R]\f[I]size\f[R] |
| Sets the size in bytes of the code segment containing profiled methods. |
| This flag is used only if \f[CB]\-XX:SegmentedCodeCache\f[R] is enabled. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+PrintCompilation\f[R] |
| Enables verbose diagnostic output from the JVM by printing a message to |
| the console every time a method is compiled. |
| This lets you to see which methods actually get compiled. |
| By default, this option is disabled and diagnostic output isn\[aq]t |
| printed. |
| .RS |
| .PP |
| You can also log compilation activity to a file by using the |
| \f[CB]\-XX:+LogCompilation\f[R] option. |
| .RE |
| .TP |
| .B \f[CB]\-XX:+PrintInlining\f[R] |
| Enables printing of inlining decisions. |
| This let\[aq]s you see which methods are getting inlined. |
| .RS |
| .PP |
| By default, this option is disabled and inlining information isn\[aq]t |
| printed. |
| The \f[CB]\-XX:+PrintInlining\f[R] option has to be used together with the |
| \f[CB]\-XX:+UnlockDiagnosticVMOptions\f[R] option that unlocks diagnostic |
| JVM options. |
| .RE |
| .TP |
| .B \f[CB]\-XX:ReservedCodeCacheSize=\f[R]\f[I]size\f[R] |
| Sets the maximum code cache size (in bytes) for JIT\-compiled code. |
| Append the letter \f[CB]k\f[R] or \f[CB]K\f[R] to indicate kilobytes, |
| \f[CB]m\f[R] or \f[CB]M\f[R] to indicate megabytes, or \f[CB]g\f[R] or |
| \f[CB]G\f[R] to indicate gigabytes. |
| The default maximum code cache size is 240 MB; if you disable tiered |
| compilation with the option \f[CB]\-XX:\-TieredCompilation\f[R], then the |
| default size is 48 MB. |
| This option has a limit of 2 GB; otherwise, an error is generated. |
| The maximum code cache size shouldn\[aq]t be less than the initial code |
| cache size; see the option \f[CB]\-XX:InitialCodeCacheSize\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:RTMAbortRatio=\f[R]\f[I]abort_ratio\f[R] |
| Specifies the RTM abort ratio is specified as a percentage (%) of all |
| executed RTM transactions. |
| If a number of aborted transactions becomes greater than this ratio, |
| then the compiled code is deoptimized. |
| This ratio is used when the \f[CB]\-XX:+UseRTMDeopt\f[R] option is |
| enabled. |
| The default value of this option is 50. |
| This means that the compiled code is deoptimized if 50% of all |
| transactions are aborted. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:RTMRetryCount=\f[R]\f[I]number_of_retries\f[R] |
| Specifies the number of times that the RTM locking code is retried, when |
| it is aborted or busy, before falling back to the normal locking |
| mechanism. |
| The default value for this option is 5. |
| The \f[CB]\-XX:UseRTMLocking\f[R] option must be enabled. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+SegmentedCodeCache\f[R] |
| Enables segmentation of the code cache. |
| Without the \f[CB]\-XX:+SegmentedCodeCache\f[R], the code cache consists |
| of one large segment. |
| With \f[CB]\-XX:+SegmentedCodeCache\f[R], we have separate segments for |
| nonmethod, profiled method, and nonprofiled method code. |
| These segments aren\[aq]t resized at runtime. |
| The feature is enabled by default if tiered compilation is enabled |
| (\f[CB]\-XX:+TieredCompilation\f[R] ) and |
| \f[CB]\-XX:ReservedCodeCacheSize\f[R] >= 240 MB. |
| The advantages are better control of the memory footprint, reduced code |
| fragmentation, and better iTLB/iCache behavior due to improved locality. |
| iTLB/iCache is a CPU\-specific term meaning Instruction Translation |
| Lookaside Buffer (ITLB). |
| ICache is an instruction cache in theCPU. |
| The implementation of the code cache can be found in the file: |
| \f[CB]/share/vm/code/codeCache.cpp\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:StartAggressiveSweepingAt=\f[R]\f[I]percent\f[R] |
| Forces stack scanning of active methods to aggressively remove unused |
| code when only the given percentage of the code cache is free. |
| The default value is 10%. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:\-TieredCompilation\f[R] |
| Disables the use of tiered compilation. |
| By default, this option is enabled. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:UseSSE=\f[R]\f[I]version\f[R] |
| Enables the use of SSE instruction set of a specified version. |
| Is set by default to the highest supported version available (x86 only). |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:UseAVX=\f[R]\f[I]version\f[R] |
| Enables the use of AVX instruction set of a specified version. |
| Is set by default to the highest supported version available (x86 only). |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseAES\f[R] |
| Enables hardware\-based AES intrinsics for hardware that supports it. |
| This option is on by default on hardware that has the necessary |
| instructions. |
| The \f[CB]\-XX:+UseAES\f[R] is used in conjunction with UseAESIntrinsics. |
| Flags that control intrinsics now require the option |
| \f[CB]\-XX:+UnlockDiagnosticVMOptions\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseAESIntrinsics\f[R] |
| Enables AES intrinsics. |
| Specifying\f[CB]\-XX:+UseAESIntrinsics\f[R] is equivalent to also enabling |
| \f[CB]\-XX:+UseAES\f[R]. |
| To disable hardware\-based AES intrinsics, specify |
| \f[CB]\-XX:\-UseAES\ \-XX:\-UseAESIntrinsics\f[R]. |
| For example, to enable hardware AES, use the following flags: |
| .RS |
| .RS |
| .PP |
| \f[CB]\-XX:+UseAES\ \-XX:+UseAESIntrinsics\f[R] |
| .RE |
| .PP |
| Flags that control intrinsics now require the option |
| \f[CB]\-XX:+UnlockDiagnosticVMOptions\f[R]. |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseAESCTRIntrinsics\f[R] |
| Analogous to \f[CB]\-XX:+UseAESIntrinsics\f[R] enables AES/CTR intrinsics. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseGHASHIntrinsics\f[R] |
| Controls the use of GHASH intrinsics. |
| Enabled by default on platforms that support the corresponding |
| instructions. |
| Flags that control intrinsics now require the option |
| \f[CB]\-XX:+UnlockDiagnosticVMOptions\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseBASE64Intrinsics\f[R] |
| Controls the use of accelerated BASE64 encoding routines for |
| \f[CB]java.util.Base64\f[R]. |
| Enabled by default on platforms that support it. |
| Flags that control intrinsics now require the option |
| \f[CB]\-XX:+UnlockDiagnosticVMOptions\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseAdler32Intrinsics\f[R] |
| Controls the use of Adler32 checksum algorithm intrinsic for |
| \f[CB]java.util.zip.Adler32\f[R]. |
| Enabled by default on platforms that support it. |
| Flags that control intrinsics now require the option |
| \f[CB]\-XX:+UnlockDiagnosticVMOptions\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseCRC32Intrinsics\f[R] |
| Controls the use of CRC32 intrinsics for \f[CB]java.util.zip.CRC32\f[R]. |
| Enabled by default on platforms that support it. |
| Flags that control intrinsics now require the option |
| \f[CB]\-XX:+UnlockDiagnosticVMOptions\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseCRC32CIntrinsics\f[R] |
| Controls the use of CRC32C intrinsics for \f[CB]java.util.zip.CRC32C\f[R]. |
| Enabled by default on platforms that support it. |
| Flags that control intrinsics now require the option |
| \f[CB]\-XX:+UnlockDiagnosticVMOptions\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseSHA\f[R] |
| Enables hardware\-based intrinsics for SHA crypto hash functions for |
| some hardware. |
| The \f[CB]UseSHA\f[R] option is used in conjunction with the |
| \f[CB]UseSHA1Intrinsics\f[R], \f[CB]UseSHA256Intrinsics\f[R], and |
| \f[CB]UseSHA512Intrinsics\f[R] options. |
| .RS |
| .PP |
| The \f[CB]UseSHA\f[R] and \f[CB]UseSHA*Intrinsics\f[R] flags are enabled by |
| default on machines that support the corresponding instructions. |
| .PP |
| This feature is applicable only when using the |
| \f[CB]sun.security.provider.Sun\f[R] provider for SHA operations. |
| Flags that control intrinsics now require the option |
| \f[CB]\-XX:+UnlockDiagnosticVMOptions\f[R]. |
| .PP |
| To disable all hardware\-based SHA intrinsics, specify the |
| \f[CB]\-XX:\-UseSHA\f[R]. |
| To disable only a particular SHA intrinsic, use the appropriate |
| corresponding option. |
| For example: \f[CB]\-XX:\-UseSHA256Intrinsics\f[R]. |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseSHA1Intrinsics\f[R] |
| Enables intrinsics for SHA\-1 crypto hash function. |
| Flags that control intrinsics now require the option |
| \f[CB]\-XX:+UnlockDiagnosticVMOptions\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseSHA256Intrinsics\f[R] |
| Enables intrinsics for SHA\-224 and SHA\-256 crypto hash functions. |
| Flags that control intrinsics now require the option |
| \f[CB]\-XX:+UnlockDiagnosticVMOptions\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseSHA512Intrinsics\f[R] |
| Enables intrinsics for SHA\-384 and SHA\-512 crypto hash functions. |
| Flags that control intrinsics now require the option |
| \f[CB]\-XX:+UnlockDiagnosticVMOptions\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseMathExactIntrinsics\f[R] |
| Enables intrinsification of various \f[CB]java.lang.Math.*Exact()\f[R] |
| functions. |
| Enabled by default. |
| Flags that control intrinsics now require the option |
| \f[CB]\-XX:+UnlockDiagnosticVMOptions\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseMultiplyToLenIntrinsic\f[R] |
| Enables intrinsification of \f[CB]BigInteger.multiplyToLen()\f[R]. |
| Enabled by default on platforms that support it. |
| Flags that control intrinsics now require the option |
| \f[CB]\-XX:+UnlockDiagnosticVMOptions\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \-XX:+UseSquareToLenIntrinsic |
| Enables intrinsification of \f[CB]BigInteger.squareToLen()\f[R]. |
| Enabled by default on platforms that support it. |
| Flags that control intrinsics now require the option |
| \f[CB]\-XX:+UnlockDiagnosticVMOptions\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \-XX:+UseMulAddIntrinsic |
| Enables intrinsification of \f[CB]BigInteger.mulAdd()\f[R]. |
| Enabled by default on platforms that support it. |
| Flags that control intrinsics now require the option |
| \f[CB]\-XX:+UnlockDiagnosticVMOptions\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \-XX:+UseMontgomeryMultiplyIntrinsic |
| Enables intrinsification of \f[CB]BigInteger.montgomeryMultiply()\f[R]. |
| Enabled by default on platforms that support it. |
| Flags that control intrinsics now require the option |
| \f[CB]\-XX:+UnlockDiagnosticVMOptions\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \-XX:+UseMontgomerySquareIntrinsic |
| Enables intrinsification of \f[CB]BigInteger.montgomerySquare()\f[R]. |
| Enabled by default on platforms that support it. |
| Flags that control intrinsics now require the option |
| \f[CB]\-XX:+UnlockDiagnosticVMOptions\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseCMoveUnconditionally\f[R] |
| Generates CMove (scalar and vector) instructions regardless of |
| profitability analysis. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseCodeCacheFlushing\f[R] |
| Enables flushing of the code cache before shutting down the compiler. |
| This option is enabled by default. |
| To disable flushing of the code cache before shutting down the compiler, |
| specify \f[CB]\-XX:\-UseCodeCacheFlushing\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseCondCardMark\f[R] |
| Enables checking if the card is already marked before updating the card |
| table. |
| This option is disabled by default. |
| It should be used only on machines with multiple sockets, where it |
| increases the performance of Java applications that rely on concurrent |
| operations. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseCountedLoopSafepoints\f[R] |
| Keeps safepoints in counted loops. |
| Its default value depends on whether the selected garbage collector |
| requires low latency safepoints. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:LoopStripMiningIter=\f[R]\f[I]number_of_iterations\f[R] |
| Controls the number of iterations in the inner strip mined loop. |
| Strip mining transforms counted loops into two level nested loops. |
| Safepoints are kept in the outer loop while the inner loop can execute |
| at full speed. |
| This option controls the maximum number of iterations in the inner loop. |
| The default value is 1,000. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:LoopStripMiningIterShortLoop\f[R]=\f[I]number_of_iterations\f[R] |
| Controls loop strip mining optimization. |
| Loops with the number of iterations less than specified will not have |
| safepoints in them. |
| Default value is 1/10th of \f[CB]\-XX:LoopStripMiningIter\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseFMA\f[R] |
| Enables hardware\-based FMA intrinsics for hardware where FMA |
| instructions are available (such as, Intel and ARM64). |
| FMA intrinsics are generated for the |
| \f[CB]java.lang.Math.fma(\f[R]\f[I]a\f[R]\f[CB],\f[R] \f[I]b\f[R]\f[CB],\f[R] |
| \f[I]c\f[R]\f[CB])\f[R] methods that calculate the value of \f[CB](\f[R] |
| \f[I]a\f[R] \f[CB]*\f[R] \f[I]b\f[R] \f[CB]+\f[R] \f[I]c\f[R] \f[CB])\f[R] |
| expressions. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseRTMDeopt\f[R] |
| Autotunes RTM locking depending on the abort ratio. |
| This ratio is specified by the \f[CB]\-XX:RTMAbortRatio\f[R] option. |
| If the number of aborted transactions exceeds the abort ratio, then the |
| method containing the lock is deoptimized and recompiled with all locks |
| as normal locks. |
| This option is disabled by default. |
| The \f[CB]\-XX:+UseRTMLocking\f[R] option must be enabled. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseRTMLocking\f[R] |
| Generates Restricted Transactional Memory (RTM) locking code for all |
| inflated locks, with the normal locking mechanism as the fallback |
| handler. |
| This option is disabled by default. |
| Options related to RTM are available only on x86 CPUs that support |
| Transactional Synchronization Extensions (TSX). |
| .RS |
| .PP |
| RTM is part of Intel\[aq]s TSX, which is an x86 instruction set |
| extension and facilitates the creation of multithreaded applications. |
| RTM introduces the new instructions \f[CB]XBEGIN\f[R], \f[CB]XABORT\f[R], |
| \f[CB]XEND\f[R], and \f[CB]XTEST\f[R]. |
| The \f[CB]XBEGIN\f[R] and \f[CB]XEND\f[R] instructions enclose a set of |
| instructions to run as a transaction. |
| If no conflict is found when running the transaction, then the memory |
| and register modifications are committed together at the \f[CB]XEND\f[R] |
| instruction. |
| The \f[CB]XABORT\f[R] instruction can be used to explicitly abort a |
| transaction and the \f[CB]XTEST\f[R] instruction checks if a set of |
| instructions is being run in a transaction. |
| .PP |
| A lock on a transaction is inflated when another thread tries to access |
| the same transaction, thereby blocking the thread that didn\[aq]t |
| originally request access to the transaction. |
| RTM requires that a fallback set of operations be specified in case a |
| transaction aborts or fails. |
| An RTM lock is a lock that has been delegated to the TSX\[aq]s system. |
| .PP |
| RTM improves performance for highly contended locks with low conflict in |
| a critical region (which is code that must not be accessed by more than |
| one thread concurrently). |
| RTM also improves the performance of coarse\-grain locking, which |
| typically doesn\[aq]t perform well in multithreaded applications. |
| (Coarse\-grain locking is the strategy of holding locks for long periods |
| to minimize the overhead of taking and releasing locks, while |
| fine\-grained locking is the strategy of trying to achieve maximum |
| parallelism by locking only when necessary and unlocking as soon as |
| possible.) Also, for lightly contended locks that are used by different |
| threads, RTM can reduce false cache line sharing, also known as cache |
| line ping\-pong. |
| This occurs when multiple threads from different processors are |
| accessing different resources, but the resources share the same cache |
| line. |
| As a result, the processors repeatedly invalidate the cache lines of |
| other processors, which forces them to read from main memory instead of |
| their cache. |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseSuperWord\f[R] |
| Enables the transformation of scalar operations into superword |
| operations. |
| Superword is a vectorization optimization. |
| This option is enabled by default. |
| To disable the transformation of scalar operations into superword |
| operations, specify \f[CB]\-XX:\-UseSuperWord\f[R]. |
| .RS |
| .RE |
| .SH ADVANCED SERVICEABILITY OPTIONS FOR JAVA |
| .PP |
| These \f[CB]java\f[R] options provide the ability to gather system |
| information and perform extensive debugging. |
| .TP |
| .B \f[CB]\-XX:+DisableAttachMechanism\f[R] |
| Disables the mechanism that lets tools attach to the JVM. |
| By default, this option is disabled, meaning that the attach mechanism |
| is enabled and you can use diagnostics and troubleshooting tools such as |
| \f[CB]jcmd\f[R], \f[CB]jstack\f[R], \f[CB]jmap\f[R], and \f[CB]jinfo\f[R]. |
| .RS |
| .RS |
| .PP |
| \f[B]Note:\f[R] The tools such as \f[B]jcmd\f[R], \f[B]jinfo\f[R], |
| \f[B]jmap\f[R], and \f[B]jstack\f[R] shipped with the JDK aren\[aq]t |
| supported when using the tools from one JDK version to troubleshoot a |
| different JDK version. |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:+ExtendedDTraceProbes\f[R] |
| \f[B]Linux and macOS:\f[R] Enables additional \f[CB]dtrace\f[R] tool probes |
| that affect the performance. |
| By default, this option is disabled and \f[CB]dtrace\f[R] performs only |
| standard probes. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+HeapDumpOnOutOfMemoryError\f[R] |
| Enables the dumping of the Java heap to a file in the current directory |
| by using the heap profiler (HPROF) when a |
| \f[CB]java.lang.OutOfMemoryError\f[R] exception is thrown. |
| You can explicitly set the heap dump file path and name using the |
| \f[CB]\-XX:HeapDumpPath\f[R] option. |
| By default, this option is disabled and the heap isn\[aq]t dumped when |
| an \f[CB]OutOfMemoryError\f[R] exception is thrown. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:HeapDumpPath=path\f[R] |
| Sets the path and file name for writing the heap dump provided by the |
| heap profiler (HPROF) when the \f[CB]\-XX:+HeapDumpOnOutOfMemoryError\f[R] |
| option is set. |
| By default, the file is created in the current working directory, and |
| it\[aq]s named \f[CB]java_pid<pid>.hprof\f[R] where \f[CB]<pid>\f[R] is the |
| identifier of the process that caused the error. |
| The following example shows how to set the default file explicitly |
| (\f[CB]%p\f[R] represents the current process identifier): |
| .RS |
| .RS |
| .PP |
| \f[CB]\-XX:HeapDumpPath=./java_pid%p.hprof\f[R] |
| .RE |
| .IP \[bu] 2 |
| \f[B]Linux and macOS:\f[R] The following example shows how to set the |
| heap dump file to \f[CB]/var/log/java/java_heapdump.hprof\f[R]: |
| .RS 2 |
| .RS |
| .PP |
| \f[CB]\-XX:HeapDumpPath=/var/log/java/java_heapdump.hprof\f[R] |
| .RE |
| .RE |
| .IP \[bu] 2 |
| \f[B]Windows:\f[R] The following example shows how to set the heap dump |
| file to \f[CB]C:/log/java/java_heapdump.log\f[R]: |
| .RS 2 |
| .RS |
| .PP |
| \f[CB]\-XX:HeapDumpPath=C:/log/java/java_heapdump.log\f[R] |
| .RE |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:LogFile=\f[R]\f[I]path\f[R] |
| Sets the path and file name to where log data is written. |
| By default, the file is created in the current working directory, and |
| it\[aq]s named \f[CB]hotspot.log\f[R]. |
| .RS |
| .IP \[bu] 2 |
| \f[B]Linux and macOS:\f[R] The following example shows how to set the log |
| file to \f[CB]/var/log/java/hotspot.log\f[R]: |
| .RS 2 |
| .RS |
| .PP |
| \f[CB]\-XX:LogFile=/var/log/java/hotspot.log\f[R] |
| .RE |
| .RE |
| .IP \[bu] 2 |
| \f[B]Windows:\f[R] The following example shows how to set the log file to |
| \f[CB]C:/log/java/hotspot.log\f[R]: |
| .RS 2 |
| .RS |
| .PP |
| \f[CB]\-XX:LogFile=C:/log/java/hotspot.log\f[R] |
| .RE |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:+PrintClassHistogram\f[R] |
| Enables printing of a class instance histogram after one of the |
| following events: |
| .RS |
| .IP \[bu] 2 |
| \f[B]Linux and macOS:\f[R] \f[CB]Control+Break\f[R] |
| .IP \[bu] 2 |
| \f[B]Windows:\f[R] \f[CB]Control+C\f[R] (\f[CB]SIGTERM\f[R]) |
| .PP |
| By default, this option is disabled. |
| .PP |
| Setting this option is equivalent to running the \f[CB]jmap\ \-histo\f[R] |
| command, or the \f[CB]jcmd\f[R] \f[I]pid\f[R] \f[CB]GC.class_histogram\f[R] |
| command, where \f[I]pid\f[R] is the current Java process identifier. |
| .RE |
| .TP |
| .B \f[CB]\-XX:+PrintConcurrentLocks\f[R] |
| Enables printing of \f[CB]java.util.concurrent\f[R] locks after one of the |
| following events: |
| .RS |
| .IP \[bu] 2 |
| \f[B]Linux and macOS:\f[R] \f[CB]Control+Break\f[R] |
| .IP \[bu] 2 |
| \f[B]Windows:\f[R] \f[CB]Control+C\f[R] (\f[CB]SIGTERM\f[R]) |
| .PP |
| By default, this option is disabled. |
| .PP |
| Setting this option is equivalent to running the \f[CB]jstack\ \-l\f[R] |
| command or the \f[CB]jcmd\f[R] \f[I]pid\f[R] \f[CB]Thread.print\ \-l\f[R] |
| command, where \f[I]pid\f[R] is the current Java process identifier. |
| .RE |
| .TP |
| .B \f[CB]\-XX:+PrintFlagsRanges\f[R] |
| Prints the range specified and allows automatic testing of the values. |
| See \f[B]Validate Java Virtual Machine Flag Arguments\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+PerfDataSaveToFile\f[R] |
| If enabled, saves \f[B]jstat\f[R] binary data when the Java application |
| exits. |
| This binary data is saved in a file named |
| \f[CB]hsperfdata_\f[R]\f[I]pid\f[R], where \f[I]pid\f[R] is the process |
| identifier of the Java application that you ran. |
| Use the \f[CB]jstat\f[R] command to display the performance data contained |
| in this file as follows: |
| .RS |
| .RS |
| .PP |
| \f[CB]jstat\ \-class\ file:///\f[R]\f[I]path\f[R]\f[CB]/hsperfdata_\f[R]\f[I]pid\f[R] |
| .RE |
| .RS |
| .PP |
| \f[CB]jstat\ \-gc\ file:///\f[R]\f[I]path\f[R]\f[CB]/hsperfdata_\f[R]\f[I]pid\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UsePerfData\f[R] |
| Enables the \f[CB]perfdata\f[R] feature. |
| This option is enabled by default to allow JVM monitoring and |
| performance testing. |
| Disabling it suppresses the creation of the \f[CB]hsperfdata_userid\f[R] |
| directories. |
| To disable the \f[CB]perfdata\f[R] feature, specify |
| \f[CB]\-XX:\-UsePerfData\f[R]. |
| .RS |
| .RE |
| .SH ADVANCED GARBAGE COLLECTION OPTIONS FOR JAVA |
| .PP |
| These \f[CB]java\f[R] options control how garbage collection (GC) is |
| performed by the Java HotSpot VM. |
| .TP |
| .B \f[CB]\-XX:+AggressiveHeap\f[R] |
| Enables Java heap optimization. |
| This sets various parameters to be optimal for long\-running jobs with |
| intensive memory allocation, based on the configuration of the computer |
| (RAM and CPU). |
| By default, the option is disabled and the heap sizes are configured |
| less aggressively. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+AlwaysPreTouch\f[R] |
| Requests the VM to touch every page on the Java heap after requesting it |
| from the operating system and before handing memory out to the |
| application. |
| By default, this option is disabled and all pages are committed as the |
| application uses the heap space. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:ConcGCThreads=\f[R]\f[I]threads\f[R] |
| Sets the number of threads used for concurrent GC. |
| Sets \f[I]\f[CI]threads\f[I]\f[R] to approximately 1/4 of the number of |
| parallel garbage collection threads. |
| The default value depends on the number of CPUs available to the JVM. |
| .RS |
| .PP |
| For example, to set the number of threads for concurrent GC to 2, |
| specify the following option: |
| .RS |
| .PP |
| \f[CB]\-XX:ConcGCThreads=2\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:+DisableExplicitGC\f[R] |
| Enables the option that disables processing of calls to the |
| \f[CB]System.gc()\f[R] method. |
| This option is disabled by default, meaning that calls to |
| \f[CB]System.gc()\f[R] are processed. |
| If processing of calls to \f[CB]System.gc()\f[R] is disabled, then the JVM |
| still performs GC when necessary. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+ExplicitGCInvokesConcurrent\f[R] |
| Enables invoking of concurrent GC by using the \f[CB]System.gc()\f[R] |
| request. |
| This option is disabled by default and can be enabled only with the |
| \f[CB]\-XX:+UseG1GC\f[R] option. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:G1AdaptiveIHOPNumInitialSamples=\f[R]\f[I]number\f[R] |
| When \f[CB]\-XX:UseAdaptiveIHOP\f[R] is enabled, this option sets the |
| number of completed marking cycles used to gather samples until G1 |
| adaptively determines the optimum value of |
| \f[CB]\-XX:InitiatingHeapOccupancyPercent\f[R]. |
| Before, G1 uses the value of |
| \f[CB]\-XX:InitiatingHeapOccupancyPercent\f[R] directly for this purpose. |
| The default value is 3. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:G1HeapRegionSize=size\f[R] |
| Sets the size of the regions into which the Java heap is subdivided when |
| using the garbage\-first (G1) collector. |
| The value is a power of 2 and can range from 1 MB to 32 MB. |
| The default region size is determined ergonomically based on the heap |
| size with a goal of approximately 2048 regions. |
| .RS |
| .PP |
| The following example sets the size of the subdivisions to 16 MB: |
| .RS |
| .PP |
| \f[CB]\-XX:G1HeapRegionSize=16m\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:G1HeapWastePercent=\f[R]\f[I]percent\f[R] |
| Sets the percentage of heap that you\[aq]re willing to waste. |
| The Java HotSpot VM doesn\[aq]t initiate the mixed garbage collection |
| cycle when the reclaimable percentage is less than the heap waste |
| percentage. |
| The default is 5 percent. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:G1MaxNewSizePercent=\f[R]\f[I]percent\f[R] |
| Sets the percentage of the heap size to use as the maximum for the young |
| generation size. |
| The default value is 60 percent of your Java heap. |
| .RS |
| .PP |
| This is an experimental flag. |
| This setting replaces the \f[CB]\-XX:DefaultMaxNewGenPercent\f[R] setting. |
| .RE |
| .TP |
| .B \f[CB]\-XX:G1MixedGCCountTarget=\f[R]\f[I]number\f[R] |
| Sets the target number of mixed garbage collections after a marking |
| cycle to collect old regions with at most |
| \f[CB]G1MixedGCLIveThresholdPercent\f[R] live data. |
| The default is 8 mixed garbage collections. |
| The goal for mixed collections is to be within this target number. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:G1MixedGCLiveThresholdPercent=\f[R]\f[I]percent\f[R] |
| Sets the occupancy threshold for an old region to be included in a mixed |
| garbage collection cycle. |
| The default occupancy is 85 percent. |
| .RS |
| .PP |
| This is an experimental flag. |
| This setting replaces the |
| \f[CB]\-XX:G1OldCSetRegionLiveThresholdPercent\f[R] setting. |
| .RE |
| .TP |
| .B \f[CB]\-XX:G1NewSizePercent=\f[R]\f[I]percent\f[R] |
| Sets the percentage of the heap to use as the minimum for the young |
| generation size. |
| The default value is 5 percent of your Java heap. |
| .RS |
| .PP |
| This is an experimental flag. |
| This setting replaces the \f[CB]\-XX:DefaultMinNewGenPercent\f[R] setting. |
| .RE |
| .TP |
| .B \f[CB]\-XX:G1OldCSetRegionThresholdPercent=\f[R]\f[I]percent\f[R] |
| Sets an upper limit on the number of old regions to be collected during |
| a mixed garbage collection cycle. |
| The default is 10 percent of the Java heap. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:G1ReservePercent=\f[R]\f[I]percent\f[R] |
| Sets the percentage of the heap (0 to 50) that\[aq]s reserved as a false |
| ceiling to reduce the possibility of promotion failure for the G1 |
| collector. |
| When you increase or decrease the percentage, ensure that you adjust the |
| total Java heap by the same amount. |
| By default, this option is set to 10%. |
| .RS |
| .PP |
| The following example sets the reserved heap to 20%: |
| .RS |
| .PP |
| \f[CB]\-XX:G1ReservePercent=20\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:+G1UseAdaptiveIHOP\f[R] |
| Controls adaptive calculation of the old generation occupancy to start |
| background work preparing for an old generation collection. |
| If enabled, G1 uses \f[CB]\-XX:InitiatingHeapOccupancyPercent\f[R] for the |
| first few times as specified by the value of |
| \f[CB]\-XX:G1AdaptiveIHOPNumInitialSamples\f[R], and after that adaptively |
| calculates a new optimum value for the initiating occupancy |
| automatically. |
| Otherwise, the old generation collection process always starts at the |
| old generation occupancy determined by |
| \f[CB]\-XX:InitiatingHeapOccupancyPercent\f[R]. |
| .RS |
| .PP |
| The default is enabled. |
| .RE |
| .TP |
| .B \f[CB]\-XX:InitialHeapSize=\f[R]\f[I]size\f[R] |
| Sets the initial size (in bytes) of the memory allocation pool. |
| This value must be either 0, or a multiple of 1024 and greater than 1 |
| MB. |
| Append the letter \f[CB]k\f[R] or \f[CB]K\f[R] to indicate kilobytes, |
| \f[CB]m\f[R] or \f[CB]M\f[R] to indicate megabytes, or \f[CB]g\f[R] or |
| \f[CB]G\f[R] to indicate gigabytes. |
| The default value is selected at run time based on the system |
| configuration. |
| .RS |
| .PP |
| The following examples show how to set the size of allocated memory to 6 |
| MB using various units: |
| .IP |
| .nf |
| \f[CB] |
| \-XX:InitialHeapSize=6291456 |
| \-XX:InitialHeapSize=6144k |
| \-XX:InitialHeapSize=6m |
| \f[R] |
| .fi |
| .PP |
| If you set this option to 0, then the initial size is set as the sum of |
| the sizes allocated for the old generation and the young generation. |
| The size of the heap for the young generation can be set using the |
| \f[CB]\-XX:NewSize\f[R] option. |
| .RE |
| .TP |
| .B \f[CB]\-XX:InitialRAMPercentage=\f[R]\f[I]percent\f[R] |
| Sets the initial amount of memory that the JVM will use for the Java |
| heap before applying ergonomics heuristics as a percentage of the |
| maximum amount determined as described in the \f[CB]\-XX:MaxRAM\f[R] |
| option. |
| The default value is 1.5625 percent. |
| .RS |
| .PP |
| The following example shows how to set the percentage of the initial |
| amount of memory used for the Java heap: |
| .RS |
| .PP |
| \f[CB]\-XX:InitialRAMPercentage=5\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:InitialSurvivorRatio=\f[R]\f[I]ratio\f[R] |
| Sets the initial survivor space ratio used by the throughput garbage |
| collector (which is enabled by the \f[CB]\-XX:+UseParallelGC\f[R] option). |
| Adaptive sizing is enabled by default with the throughput garbage |
| collector by using the \f[CB]\-XX:+UseParallelGC\f[R] option, and the |
| survivor space is resized according to the application behavior, |
| starting with the initial value. |
| If adaptive sizing is disabled (using the |
| \f[CB]\-XX:\-UseAdaptiveSizePolicy\f[R] option), then the |
| \f[CB]\-XX:SurvivorRatio\f[R] option should be used to set the size of the |
| survivor space for the entire execution of the application. |
| .RS |
| .PP |
| The following formula can be used to calculate the initial size of |
| survivor space (S) based on the size of the young generation (Y), and |
| the initial survivor space ratio (R): |
| .RS |
| .PP |
| \f[CB]S=Y/(R+2)\f[R] |
| .RE |
| .PP |
| The 2 in the equation denotes two survivor spaces. |
| The larger the value specified as the initial survivor space ratio, the |
| smaller the initial survivor space size. |
| .PP |
| By default, the initial survivor space ratio is set to 8. |
| If the default value for the young generation space size is used (2 MB), |
| then the initial size of the survivor space is 0.2 MB. |
| .PP |
| The following example shows how to set the initial survivor space ratio |
| to 4: |
| .RS |
| .PP |
| \f[CB]\-XX:InitialSurvivorRatio=4\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:InitiatingHeapOccupancyPercent=\f[R]\f[I]percent\f[R] |
| Sets the percentage of the old generation occupancy (0 to 100) at which |
| to start the first few concurrent marking cycles for the G1 garbage |
| collector. |
| .RS |
| .PP |
| By default, the initiating value is set to 45%. |
| A value of 0 implies nonstop concurrent GC cycles from the beginning |
| until G1 adaptively sets this value. |
| .PP |
| See also the \f[CB]\-XX:G1UseAdaptiveIHOP\f[R] and |
| \f[CB]\-XX:G1AdaptiveIHOPNumInitialSamples\f[R] options. |
| .PP |
| The following example shows how to set the initiating heap occupancy to |
| 75%: |
| .RS |
| .PP |
| \f[CB]\-XX:InitiatingHeapOccupancyPercent=75\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:MaxGCPauseMillis=\f[R]\f[I]time\f[R] |
| Sets a target for the maximum GC pause time (in milliseconds). |
| This is a soft goal, and the JVM will make its best effort to achieve |
| it. |
| The specified value doesn\[aq]t adapt to your heap size. |
| By default, for G1 the maximum pause time target is 200 milliseconds. |
| The other generational collectors do not use a pause time goal by |
| default. |
| .RS |
| .PP |
| The following example shows how to set the maximum target pause time to |
| 500 ms: |
| .RS |
| .PP |
| \f[CB]\-XX:MaxGCPauseMillis=500\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:MaxHeapSize=\f[R]\f[I]size\f[R] |
| Sets the maximum size (in byes) of the memory allocation pool. |
| This value must be a multiple of 1024 and greater than 2 MB. |
| Append the letter \f[CB]k\f[R] or \f[CB]K\f[R] to indicate kilobytes, |
| \f[CB]m\f[R] or \f[CB]M\f[R] to indicate megabytes, or \f[CB]g\f[R] or |
| \f[CB]G\f[R] to indicate gigabytes. |
| The default value is selected at run time based on the system |
| configuration. |
| For server deployments, the options \f[CB]\-XX:InitialHeapSize\f[R] and |
| \f[CB]\-XX:MaxHeapSize\f[R] are often set to the same value. |
| .RS |
| .PP |
| The following examples show how to set the maximum allowed size of |
| allocated memory to 80 MB using various units: |
| .IP |
| .nf |
| \f[CB] |
| \-XX:MaxHeapSize=83886080 |
| \-XX:MaxHeapSize=81920k |
| \-XX:MaxHeapSize=80m |
| \f[R] |
| .fi |
| .PP |
| The \f[CB]\-XX:MaxHeapSize\f[R] option is equivalent to \f[CB]\-Xmx\f[R]. |
| .RE |
| .TP |
| .B \f[CB]\-XX:MaxHeapFreeRatio=\f[R]\f[I]percent\f[R] |
| Sets the maximum allowed percentage of free heap space (0 to 100) after |
| a GC event. |
| If free heap space expands above this value, then the heap is shrunk. |
| By default, this value is set to 70%. |
| .RS |
| .PP |
| Minimize the Java heap size by lowering the values of the parameters |
| \f[CB]MaxHeapFreeRatio\f[R] (default value is 70%) and |
| \f[CB]MinHeapFreeRatio\f[R] (default value is 40%) with the command\-line |
| options \f[CB]\-XX:MaxHeapFreeRatio\f[R] and |
| \f[CB]\-XX:MinHeapFreeRatio\f[R]. |
| Lowering \f[CB]MaxHeapFreeRatio\f[R] to as low as 10% and |
| \f[CB]MinHeapFreeRatio\f[R] to 5% has successfully reduced the heap size |
| without too much performance regression; however, results may vary |
| greatly depending on your application. |
| Try different values for these parameters until they\[aq]re as low as |
| possible yet still retain acceptable performance. |
| .RS |
| .PP |
| \f[CB]\-XX:MaxHeapFreeRatio=10\ \-XX:MinHeapFreeRatio=5\f[R] |
| .RE |
| .PP |
| Customers trying to keep the heap small should also add the option |
| \f[CB]\-XX:\-ShrinkHeapInSteps\f[R]. |
| See \f[B]Performance Tuning Examples\f[R] for a description of using this |
| option to keep the Java heap small by reducing the dynamic footprint for |
| embedded applications. |
| .RE |
| .TP |
| .B \f[CB]\-XX:MaxMetaspaceSize=\f[R]\f[I]size\f[R] |
| Sets the maximum amount of native memory that can be allocated for class |
| metadata. |
| By default, the size isn\[aq]t limited. |
| The amount of metadata for an application depends on the application |
| itself, other running applications, and the amount of memory available |
| on the system. |
| .RS |
| .PP |
| The following example shows how to set the maximum class metadata size |
| to 256 MB: |
| .RS |
| .PP |
| \f[CB]\-XX:MaxMetaspaceSize=256m\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:MaxNewSize=\f[R]\f[I]size\f[R] |
| Sets the maximum size (in bytes) of the heap for the young generation |
| (nursery). |
| The default value is set ergonomically. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:MaxRAM=\f[R]\f[I]size\f[R] |
| Sets the maximum amount of memory that the JVM may use for the Java heap |
| before applying ergonomics heuristics. |
| The default value is the maximum amount of available memory to the JVM |
| process or 128 GB, whichever is lower. |
| .RS |
| .PP |
| The maximum amount of available memory to the JVM process is the minimum |
| of the machine\[aq]s physical memory and any constraints set by the |
| environment (e.g. |
| container). |
| .PP |
| Specifying this option disables automatic use of compressed oops if the |
| combined result of this and other options influencing the maximum amount |
| of memory is larger than the range of memory addressable by compressed |
| oops. |
| See \f[CB]\-XX:UseCompressedOops\f[R] for further information about |
| compressed oops. |
| .PP |
| The following example shows how to set the maximum amount of available |
| memory for sizing the Java heap to 2 GB: |
| .RS |
| .PP |
| \f[CB]\-XX:MaxRAM=2G\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:MaxRAMPercentage=\f[R]\f[I]percent\f[R] |
| Sets the maximum amount of memory that the JVM may use for the Java heap |
| before applying ergonomics heuristics as a percentage of the maximum |
| amount determined as described in the \f[CB]\-XX:MaxRAM\f[R] option. |
| The default value is 25 percent. |
| .RS |
| .PP |
| Specifying this option disables automatic use of compressed oops if the |
| combined result of this and other options influencing the maximum amount |
| of memory is larger than the range of memory addressable by compressed |
| oops. |
| See \f[CB]\-XX:UseCompressedOops\f[R] for further information about |
| compressed oops. |
| .PP |
| The following example shows how to set the percentage of the maximum |
| amount of memory used for the Java heap: |
| .RS |
| .PP |
| \f[CB]\-XX:MaxRAMPercentage=75\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:MinRAMPercentage=\f[R]\f[I]percent\f[R] |
| Sets the maximum amount of memory that the JVM may use for the Java heap |
| before applying ergonomics heuristics as a percentage of the maximum |
| amount determined as described in the \f[CB]\-XX:MaxRAM\f[R] option for |
| small heaps. |
| A small heap is a heap of approximately 125 MB. |
| The default value is 50 percent. |
| .RS |
| .PP |
| The following example shows how to set the percentage of the maximum |
| amount of memory used for the Java heap for small heaps: |
| .RS |
| .PP |
| \f[CB]\-XX:MinRAMPercentage=75\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:MaxTenuringThreshold=\f[R]\f[I]threshold\f[R] |
| Sets the maximum tenuring threshold for use in adaptive GC sizing. |
| The largest value is 15. |
| The default value is 15 for the parallel (throughput) collector. |
| .RS |
| .PP |
| The following example shows how to set the maximum tenuring threshold to |
| 10: |
| .RS |
| .PP |
| \f[CB]\-XX:MaxTenuringThreshold=10\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:MetaspaceSize=\f[R]\f[I]size\f[R] |
| Sets the size of the allocated class metadata space that triggers a |
| garbage collection the first time it\[aq]s exceeded. |
| This threshold for a garbage collection is increased or decreased |
| depending on the amount of metadata used. |
| The default size depends on the platform. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:MinHeapFreeRatio=\f[R]\f[I]percent\f[R] |
| Sets the minimum allowed percentage of free heap space (0 to 100) after |
| a GC event. |
| If free heap space falls below this value, then the heap is expanded. |
| By default, this value is set to 40%. |
| .RS |
| .PP |
| Minimize Java heap size by lowering the values of the parameters |
| \f[CB]MaxHeapFreeRatio\f[R] (default value is 70%) and |
| \f[CB]MinHeapFreeRatio\f[R] (default value is 40%) with the command\-line |
| options \f[CB]\-XX:MaxHeapFreeRatio\f[R] and |
| \f[CB]\-XX:MinHeapFreeRatio\f[R]. |
| Lowering \f[CB]MaxHeapFreeRatio\f[R] to as low as 10% and |
| \f[CB]MinHeapFreeRatio\f[R] to 5% has successfully reduced the heap size |
| without too much performance regression; however, results may vary |
| greatly depending on your application. |
| Try different values for these parameters until they\[aq]re as low as |
| possible, yet still retain acceptable performance. |
| .RS |
| .PP |
| \f[CB]\-XX:MaxHeapFreeRatio=10\ \-XX:MinHeapFreeRatio=5\f[R] |
| .RE |
| .PP |
| Customers trying to keep the heap small should also add the option |
| \f[CB]\-XX:\-ShrinkHeapInSteps\f[R]. |
| See \f[B]Performance Tuning Examples\f[R] for a description of using this |
| option to keep the Java heap small by reducing the dynamic footprint for |
| embedded applications. |
| .RE |
| .TP |
| .B \f[CB]\-XX:MinHeapSize=\f[R]\f[I]size\f[R] |
| Sets the minimum size (in bytes) of the memory allocation pool. |
| This value must be either 0, or a multiple of 1024 and greater than 1 |
| MB. |
| Append the letter \f[CB]k\f[R] or \f[CB]K\f[R] to indicate kilobytes, |
| \f[CB]m\f[R] or \f[CB]M\f[R] to indicate megabytes, or \f[CB]g\f[R] or |
| \f[CB]G\f[R] to indicate gigabytes. |
| The default value is selected at run time based on the system |
| configuration. |
| .RS |
| .PP |
| The following examples show how to set the mimimum size of allocated |
| memory to 6 MB using various units: |
| .IP |
| .nf |
| \f[CB] |
| \-XX:MinHeapSize=6291456 |
| \-XX:MinHeapSize=6144k |
| \-XX:MinHeapSize=6m |
| \f[R] |
| .fi |
| .PP |
| If you set this option to 0, then the minimum size is set to the same |
| value as the initial size. |
| .RE |
| .TP |
| .B \f[CB]\-XX:NewRatio=\f[R]\f[I]ratio\f[R] |
| Sets the ratio between young and old generation sizes. |
| By default, this option is set to 2. |
| The following example shows how to set the young\-to\-old ratio to 1: |
| .RS |
| .RS |
| .PP |
| \f[CB]\-XX:NewRatio=1\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:NewSize=\f[R]\f[I]size\f[R] |
| Sets the initial size (in bytes) of the heap for the young generation |
| (nursery). |
| Append the letter \f[CB]k\f[R] or \f[CB]K\f[R] to indicate kilobytes, |
| \f[CB]m\f[R] or \f[CB]M\f[R] to indicate megabytes, or \f[CB]g\f[R] or |
| \f[CB]G\f[R] to indicate gigabytes. |
| .RS |
| .PP |
| The young generation region of the heap is used for new objects. |
| GC is performed in this region more often than in other regions. |
| If the size for the young generation is too low, then a large number of |
| minor GCs are performed. |
| If the size is too high, then only full GCs are performed, which can |
| take a long time to complete. |
| It is recommended that you keep the size for the young generation |
| greater than 25% and less than 50% of the overall heap size. |
| .PP |
| The following examples show how to set the initial size of the young |
| generation to 256 MB using various units: |
| .IP |
| .nf |
| \f[CB] |
| \-XX:NewSize=256m |
| \-XX:NewSize=262144k |
| \-XX:NewSize=268435456 |
| \f[R] |
| .fi |
| .PP |
| The \f[CB]\-XX:NewSize\f[R] option is equivalent to \f[CB]\-Xmn\f[R]. |
| .RE |
| .TP |
| .B \f[CB]\-XX:ParallelGCThreads=\f[R]\f[I]threads\f[R] |
| Sets the number of the stop\-the\-world (STW) worker threads. |
| The default value depends on the number of CPUs available to the JVM and |
| the garbage collector selected. |
| .RS |
| .PP |
| For example, to set the number of threads for G1 GC to 2, specify the |
| following option: |
| .RS |
| .PP |
| \f[CB]\-XX:ParallelGCThreads=2\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:+ParallelRefProcEnabled\f[R] |
| Enables parallel reference processing. |
| By default, this option is disabled. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+PrintAdaptiveSizePolicy\f[R] |
| Enables printing of information about adaptive\-generation sizing. |
| By default, this option is disabled. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+ScavengeBeforeFullGC\f[R] |
| Enables GC of the young generation before each full GC. |
| This option is enabled by default. |
| It is recommended that you \f[I]don\[aq]t\f[R] disable it, because |
| scavenging the young generation before a full GC can reduce the number |
| of objects reachable from the old generation space into the young |
| generation space. |
| To disable GC of the young generation before each full GC, specify the |
| option \f[CB]\-XX:\-ScavengeBeforeFullGC\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:SoftRefLRUPolicyMSPerMB=\f[R]\f[I]time\f[R] |
| Sets the amount of time (in milliseconds) a softly reachable object is |
| kept active on the heap after the last time it was referenced. |
| The default value is one second of lifetime per free megabyte in the |
| heap. |
| The \f[CB]\-XX:SoftRefLRUPolicyMSPerMB\f[R] option accepts integer values |
| representing milliseconds per one megabyte of the current heap size (for |
| Java HotSpot Client VM) or the maximum possible heap size (for Java |
| HotSpot Server VM). |
| This difference means that the Client VM tends to flush soft references |
| rather than grow the heap, whereas the Server VM tends to grow the heap |
| rather than flush soft references. |
| In the latter case, the value of the \f[CB]\-Xmx\f[R] option has a |
| significant effect on how quickly soft references are garbage collected. |
| .RS |
| .PP |
| The following example shows how to set the value to 2.5 seconds: |
| .PP |
| \f[CB]\-XX:SoftRefLRUPolicyMSPerMB=2500\f[R] |
| .RE |
| .TP |
| .B \f[CB]\-XX:\-ShrinkHeapInSteps\f[R] |
| Incrementally reduces the Java heap to the target size, specified by the |
| option \f[CB]\-XX:MaxHeapFreeRatio\f[R]. |
| This option is enabled by default. |
| If disabled, then it immediately reduces the Java heap to the target |
| size instead of requiring multiple garbage collection cycles. |
| Disable this option if you want to minimize the Java heap size. |
| You will likely encounter performance degradation when this option is |
| disabled. |
| .RS |
| .PP |
| See \f[B]Performance Tuning Examples\f[R] for a description of using the |
| \f[CB]MaxHeapFreeRatio\f[R] option to keep the Java heap small by reducing |
| the dynamic footprint for embedded applications. |
| .RE |
| .TP |
| .B \f[CB]\-XX:StringDeduplicationAgeThreshold=\f[R]\f[I]threshold\f[R] |
| Identifies \f[CB]String\f[R] objects reaching the specified age that are |
| considered candidates for deduplication. |
| An object\[aq]s age is a measure of how many times it has survived |
| garbage collection. |
| This is sometimes referred to as tenuring. |
| .RS |
| .RS |
| .PP |
| \f[B]Note:\f[R] \f[CB]String\f[R] objects that are promoted to an old heap |
| region before this age has been reached are always considered candidates |
| for deduplication. |
| The default value for this option is \f[CB]3\f[R]. |
| See the \f[CB]\-XX:+UseStringDeduplication\f[R] option. |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:SurvivorRatio=\f[R]\f[I]ratio\f[R] |
| Sets the ratio between eden space size and survivor space size. |
| By default, this option is set to 8. |
| The following example shows how to set the eden/survivor space ratio to |
| 4: |
| .RS |
| .RS |
| .PP |
| \f[CB]\-XX:SurvivorRatio=4\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:TargetSurvivorRatio=\f[R]\f[I]percent\f[R] |
| Sets the desired percentage of survivor space (0 to 100) used after |
| young garbage collection. |
| By default, this option is set to 50%. |
| .RS |
| .PP |
| The following example shows how to set the target survivor space ratio |
| to 30%: |
| .RS |
| .PP |
| \f[CB]\-XX:TargetSurvivorRatio=30\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:TLABSize=\f[R]\f[I]size\f[R] |
| Sets the initial size (in bytes) of a thread\-local allocation buffer |
| (TLAB). |
| Append the letter \f[CB]k\f[R] or \f[CB]K\f[R] to indicate kilobytes, |
| \f[CB]m\f[R] or \f[CB]M\f[R] to indicate megabytes, or \f[CB]g\f[R] or |
| \f[CB]G\f[R] to indicate gigabytes. |
| If this option is set to 0, then the JVM selects the initial size |
| automatically. |
| .RS |
| .PP |
| The following example shows how to set the initial TLAB size to 512 KB: |
| .RS |
| .PP |
| \f[CB]\-XX:TLABSize=512k\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseAdaptiveSizePolicy\f[R] |
| Enables the use of adaptive generation sizing. |
| This option is enabled by default. |
| To disable adaptive generation sizing, specify |
| \f[CB]\-XX:\-UseAdaptiveSizePolicy\f[R] and set the size of the memory |
| allocation pool explicitly. |
| See the \f[CB]\-XX:SurvivorRatio\f[R] option. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseG1GC\f[R] |
| Enables the use of the garbage\-first (G1) garbage collector. |
| It\[aq]s a server\-style garbage collector, targeted for multiprocessor |
| machines with a large amount of RAM. |
| This option meets GC pause time goals with high probability, while |
| maintaining good throughput. |
| The G1 collector is recommended for applications requiring large heaps |
| (sizes of around 6 GB or larger) with limited GC latency requirements (a |
| stable and predictable pause time below 0.5 seconds). |
| By default, this option is enabled and G1 is used as the default garbage |
| collector. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseGCOverheadLimit\f[R] |
| Enables the use of a policy that limits the proportion of time spent by |
| the JVM on GC before an \f[CB]OutOfMemoryError\f[R] exception is thrown. |
| This option is enabled, by default, and the parallel GC will throw an |
| \f[CB]OutOfMemoryError\f[R] if more than 98% of the total time is spent on |
| garbage collection and less than 2% of the heap is recovered. |
| When the heap is small, this feature can be used to prevent applications |
| from running for long periods of time with little or no progress. |
| To disable this option, specify the option |
| \f[CB]\-XX:\-UseGCOverheadLimit\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseNUMA\f[R] |
| Enables performance optimization of an application on a machine with |
| nonuniform memory architecture (NUMA) by increasing the |
| application\[aq]s use of lower latency memory. |
| By default, this option is disabled and no optimization for NUMA is |
| made. |
| The option is available only when the parallel garbage collector is used |
| (\f[CB]\-XX:+UseParallelGC\f[R]). |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseParallelGC\f[R] |
| Enables the use of the parallel scavenge garbage collector (also known |
| as the throughput collector) to improve the performance of your |
| application by leveraging multiple processors. |
| .RS |
| .PP |
| By default, this option is disabled and the default collector is used. |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseSerialGC\f[R] |
| Enables the use of the serial garbage collector. |
| This is generally the best choice for small and simple applications that |
| don\[aq]t require any special functionality from garbage collection. |
| By default, this option is disabled and the default collector is used. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseSHM\f[R] |
| \f[B]Linux only:\f[R] Enables the JVM to use shared memory to set up |
| large pages. |
| .RS |
| .PP |
| See \f[B]Large Pages\f[R] for setting up large pages. |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseStringDeduplication\f[R] |
| Enables string deduplication. |
| By default, this option is disabled. |
| To use this option, you must enable the garbage\-first (G1) garbage |
| collector. |
| .RS |
| .PP |
| String deduplication reduces the memory footprint of \f[CB]String\f[R] |
| objects on the Java heap by taking advantage of the fact that many |
| \f[CB]String\f[R] objects are identical. |
| Instead of each \f[CB]String\f[R] object pointing to its own character |
| array, identical \f[CB]String\f[R] objects can point to and share the same |
| character array. |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseTLAB\f[R] |
| Enables the use of thread\-local allocation blocks (TLABs) in the young |
| generation space. |
| This option is enabled by default. |
| To disable the use of TLABs, specify the option \f[CB]\-XX:\-UseTLAB\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseZGC\f[R] |
| Enables the use of the Z garbage collector (ZGC). |
| This is a low latency garbage collector, providing max pause times of a |
| few milliseconds, at some throughput cost. |
| Pause times are independent of what heap size is used. |
| Supports heap sizes from 8MB to 16TB. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:ZAllocationSpikeTolerance\f[R]=\f[I]factor\f[R] |
| Sets the allocation spike tolerance for ZGC. |
| By default, this option is set to 2.0. |
| This factor describes the level of allocation spikes to expect. |
| For example, using a factor of 3.0 means the current allocation rate can |
| be expected to triple at any time. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:ZCollectionInterval\f[R]=\f[I]seconds\f[R] |
| Sets the maximum interval (in seconds) between two GC cycles when using |
| ZGC. |
| By default, this option is set to 0 (disabled). |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:ZFragmentationLimit\f[R]=\f[I]percent\f[R] |
| Sets the maximum acceptable heap fragmentation (in percent) for ZGC. |
| By default, this option is set to 25. |
| Using a lower value will cause the heap to be compacted more |
| aggressively, to reclaim more memory at the cost of using more CPU time. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+ZProactive\f[R] |
| Enables proactive GC cycles when using ZGC. |
| By default, this option is enabled. |
| ZGC will start a proactive GC cycle if doing so is expected to have |
| minimal impact on the running application. |
| This is useful if the application is mostly idle or allocates very few |
| objects, but you still want to keep the heap size down and allow |
| reference processing to happen even when there are a lot of free space |
| on the heap. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+ZUncommit\f[R] |
| Enables uncommitting of unused heap memory when using ZGC. |
| By default, this option is enabled. |
| Uncommitting unused heap memory will lower the memory footprint of the |
| JVM, and make that memory available for other processes to use. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:ZUncommitDelay\f[R]=\f[I]seconds\f[R] |
| Sets the amount of time (in seconds) that heap memory must have been |
| unused before being uncommitted. |
| By default, this option is set to 300 (5 minutes). |
| Committing and uncommitting memory are relatively expensive operations. |
| Using a lower value will cause heap memory to be uncommitted earlier, at |
| the risk of soon having to commit it again. |
| .RS |
| .RE |
| .SH DEPRECATED JAVA OPTIONS |
| .PP |
| These \f[CB]java\f[R] options are deprecated and might be removed in a |
| future JDK release. |
| They\[aq]re still accepted and acted upon, but a warning is issued when |
| they\[aq]re used. |
| .TP |
| .B \f[CB]\-Xfuture\f[R] |
| Enables strict class\-file format checks that enforce close conformance |
| to the class\-file format specification. |
| Developers should use this flag when developing new code. |
| Stricter checks may become the default in future releases. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-Xloggc:\f[R]\f[I]filename\f[R] |
| Sets the file to which verbose GC events information should be |
| redirected for logging. |
| The \f[CB]\-Xloggc\f[R] option overrides \f[CB]\-verbose:gc\f[R] if both are |
| given with the same java command. |
| \f[CB]\-Xloggc:\f[R]\f[I]filename\f[R] is replaced by |
| \f[CB]\-Xlog:gc:\f[R]\f[I]filename\f[R]. |
| See Enable Logging with the JVM Unified Logging Framework. |
| .RS |
| .PP |
| Example: |
| .PP |
| \f[CB]\-Xlog:gc:garbage\-collection.log\f[R] |
| .RE |
| .TP |
| .B \f[CB]\-XX:+FlightRecorder\f[R] |
| Enables the use of Java Flight Recorder (JFR) during the runtime of the |
| application. |
| Since JDK 8u40 this option has not been required to use JFR. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:InitialRAMFraction=\f[R]\f[I]ratio\f[R] |
| Sets the initial amount of memory that the JVM may use for the Java heap |
| before applying ergonomics heuristics as a ratio of the maximum amount |
| determined as described in the \f[CB]\-XX:MaxRAM\f[R] option. |
| The default value is 64. |
| .RS |
| .PP |
| Use the option \f[CB]\-XX:InitialRAMPercentage\f[R] instead. |
| .RE |
| .TP |
| .B \f[CB]\-XX:MaxRAMFraction=\f[R]\f[I]ratio\f[R] |
| Sets the maximum amount of memory that the JVM may use for the Java heap |
| before applying ergonomics heuristics as a fraction of the maximum |
| amount determined as described in the \f[CB]\-XX:MaxRAM\f[R] option. |
| The default value is 4. |
| .RS |
| .PP |
| Specifying this option disables automatic use of compressed oops if the |
| combined result of this and other options influencing the maximum amount |
| of memory is larger than the range of memory addressable by compressed |
| oops. |
| See \f[CB]\-XX:UseCompressedOops\f[R] for further information about |
| compressed oops. |
| .PP |
| Use the option \f[CB]\-XX:MaxRAMPercentage\f[R] instead. |
| .RE |
| .TP |
| .B \f[CB]\-XX:MinRAMFraction=\f[R]\f[I]ratio\f[R] |
| Sets the maximum amount of memory that the JVM may use for the Java heap |
| before applying ergonomics heuristics as a fraction of the maximum |
| amount determined as described in the \f[CB]\-XX:MaxRAM\f[R] option for |
| small heaps. |
| A small heap is a heap of approximately 125 MB. |
| The default value is 2. |
| .RS |
| .PP |
| Use the option \f[CB]\-XX:MinRAMPercentage\f[R] instead. |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseBiasedLocking\f[R] |
| Enables the use of biased locking. |
| Some applications with significant amounts of uncontended |
| synchronization may attain significant speedups with this flag enabled, |
| but applications with certain patterns of locking may see slowdowns. |
| .RS |
| .PP |
| By default, this option is disabled. |
| .RE |
| .SH OBSOLETE JAVA OPTIONS |
| .PP |
| These \f[CB]java\f[R] options are still accepted but ignored, and a |
| warning is issued when they\[aq]re used. |
| .TP |
| .B \f[CB]\-\-illegal\-access=\f[R]\f[I]parameter\f[R] |
| Controlled \f[I]relaxed strong encapsulation\f[R], as defined in \f[B]JEP |
| 261\f[R] |
| [https://openjdk.java.net/jeps/261#Relaxed\-strong\-encapsulation]. |
| This option was deprecated in JDK 16 by \f[B]JEP 396\f[R] |
| [https://openjdk.java.net/jeps/396] and made obsolete in JDK 17 by |
| \f[B]JEP 403\f[R] [https://openjdk.java.net/jeps/403]. |
| .RS |
| .RE |
| .SH REMOVED JAVA OPTIONS |
| .PP |
| These \f[CB]java\f[R] options have been removed in JDK 17 and using them |
| results in an error of: |
| .RS |
| .PP |
| \f[CB]Unrecognized\ VM\ option\f[R] \f[I]option\-name\f[R] |
| .RE |
| .TP |
| .B \f[CB]\-XX:+UseMembar\f[R] |
| Enabled issuing membars on thread\-state transitions. |
| This option was disabled by default on all platforms except ARM servers, |
| where it was enabled. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:MaxPermSize=\f[R]\f[I]size\f[R] |
| Sets the maximum permanent generation space size (in bytes). |
| This option was deprecated in JDK 8 and superseded by the |
| \f[CB]\-XX:MaxMetaspaceSize\f[R] option. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:PermSize=\f[R]\f[I]size\f[R] |
| Sets the space (in bytes) allocated to the permanent generation that |
| triggers a garbage collection if it\[aq]s exceeded. |
| This option was deprecated in JDK 8 and superseded by the |
| \f[CB]\-XX:MetaspaceSize\f[R] option. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-XX:+TraceClassLoading\f[R] |
| Enables tracing of classes as they are loaded. |
| By default, this option is disabled and classes aren\[aq]t traced. |
| .RS |
| .PP |
| The replacement Unified Logging syntax is |
| \f[CB]\-Xlog:class+load=\f[R]\f[I]level\f[R]. |
| See \f[B]Enable Logging with the JVM Unified Logging Framework\f[R] |
| .PP |
| Use \f[I]level\f[R]=\f[CB]info\f[R] for regular information, or |
| \f[I]level\f[R]=\f[CB]debug\f[R] for additional information. |
| In Unified Logging syntax, \f[CB]\-verbose:class\f[R] equals |
| \f[CB]\-Xlog:class+load=info,class+unload=info\f[R]. |
| .RE |
| .TP |
| .B \f[CB]\-XX:+TraceClassLoadingPreorder\f[R] |
| Enables tracing of all loaded classes in the order in which they\[aq]re |
| referenced. |
| By default, this option is disabled and classes aren\[aq]t traced. |
| .RS |
| .PP |
| The replacement Unified Logging syntax is |
| \f[CB]\-Xlog:class+preorder=debug\f[R]. |
| See \f[B]Enable Logging with the JVM Unified Logging Framework\f[R]. |
| .RE |
| .TP |
| .B \f[CB]\-XX:+TraceClassResolution\f[R] |
| Enables tracing of constant pool resolutions. |
| By default, this option is disabled and constant pool resolutions |
| aren\[aq]t traced. |
| .RS |
| .PP |
| The replacement Unified Logging syntax is |
| \f[CB]\-Xlog:class+resolve=debug\f[R]. |
| See \f[B]Enable Logging with the JVM Unified Logging Framework\f[R]. |
| .RE |
| .TP |
| .B \f[CB]\-XX:+TraceLoaderConstraints\f[R] |
| Enables tracing of the loader constraints recording. |
| By default, this option is disabled and loader constraints recording |
| isn\[aq]t traced. |
| .RS |
| .PP |
| The replacement Unified Logging syntax is |
| \f[CB]\-Xlog:class+loader+constraints=info\f[R]. |
| See \f[B]Enable Logging with the JVM Unified Logging Framework\f[R]. |
| .RE |
| .PP |
| For the lists and descriptions of options removed in previous releases |
| see the \f[I]Removed Java Options\f[R] section in: |
| .IP \[bu] 2 |
| \f[B]Java Platform, Standard Edition Tools Reference, Release 16\f[R] |
| [https://docs.oracle.com/en/java/javase/16/docs/specs/man/java.html] |
| .IP \[bu] 2 |
| \f[B]Java Platform, Standard Edition Tools Reference, Release 15\f[R] |
| [https://docs.oracle.com/en/java/javase/15/docs/specs/man/java.html] |
| .IP \[bu] 2 |
| \f[B]Java Platform, Standard Edition Tools Reference, Release 14\f[R] |
| [https://docs.oracle.com/en/java/javase/14/docs/specs/man/java.html] |
| .IP \[bu] 2 |
| \f[B]Java Platform, Standard Edition Tools Reference, Release 13\f[R] |
| [https://docs.oracle.com/en/java/javase/13/docs/specs/man/java.html] |
| .IP \[bu] 2 |
| \f[B]Java Platform, Standard Edition Tools Reference, Release 12\f[R] |
| [https://docs.oracle.com/en/java/javase/12/tools/java.html#GUID\-3B1CE181\-CD30\-4178\-9602\-230B800D4FAE] |
| .IP \[bu] 2 |
| \f[B]Java Platform, Standard Edition Tools Reference, Release 11\f[R] |
| [https://docs.oracle.com/en/java/javase/11/tools/java.html#GUID\-741FC470\-AA3E\-494A\-8D2B\-1B1FE4A990D1] |
| .IP \[bu] 2 |
| \f[B]Java Platform, Standard Edition Tools Reference, Release 10\f[R] |
| [https://docs.oracle.com/javase/10/tools/java.htm#JSWOR624] |
| .IP \[bu] 2 |
| \f[B]Java Platform, Standard Edition Tools Reference, Release 9\f[R] |
| [https://docs.oracle.com/javase/9/tools/java.htm#JSWOR624] |
| .IP \[bu] 2 |
| \f[B]Java Platform, Standard Edition Tools Reference, Release 8 for |
| Oracle JDK on Windows\f[R] |
| [https://docs.oracle.com/javase/8/docs/technotes/tools/windows/java.html#BGBCIEFC] |
| .IP \[bu] 2 |
| \f[B]Java Platform, Standard Edition Tools Reference, Release 8 for |
| Oracle JDK on Solaris, Linux, and macOS\f[R] |
| [https://docs.oracle.com/javase/8/docs/technotes/tools/unix/java.html#BGBCIEFC] |
| .SH JAVA COMMAND\-LINE ARGUMENT FILES |
| .PP |
| You can shorten or simplify the \f[CB]java\f[R] command by using |
| \f[CB]\@\f[R] argument files to specify one or more text files that |
| contain arguments, such as options and class names, which are passed to |
| the \f[CB]java\f[R] command. |
| This let\[aq]s you to create \f[CB]java\f[R] commands of any length on any |
| operating system. |
| .PP |
| In the command line, use the at sign (\f[CB]\@\f[R]) prefix to identify an |
| argument file that contains \f[CB]java\f[R] options and class names. |
| When the \f[CB]java\f[R] command encounters a file beginning with the at |
| sign (\f[CB]\@\f[R]), it expands the contents of that file into an |
| argument list just as they would be specified on the command line. |
| .PP |
| The \f[CB]java\f[R] launcher expands the argument file contents until it |
| encounters the \f[CB]\-\-disable\-\@files\f[R] option. |
| You can use the \f[CB]\-\-disable\-\@files\f[R] option anywhere on the |
| command line, including in an argument file, to stop \f[CB]\@\f[R] |
| argument files expansion. |
| .PP |
| The following items describe the syntax of \f[CB]java\f[R] argument files: |
| .IP \[bu] 2 |
| The argument file must contain only ASCII characters or characters in |
| system default encoding that\[aq]s ASCII friendly, such as UTF\-8. |
| .IP \[bu] 2 |
| The argument file size must not exceed MAXINT (2,147,483,647) bytes. |
| .IP \[bu] 2 |
| The launcher doesn\[aq]t expand wildcards that are present within an |
| argument file. |
| .IP \[bu] 2 |
| Use white space or new line characters to separate arguments included in |
| the file. |
| .IP \[bu] 2 |
| White space includes a white space character, \f[CB]\\t\f[R], |
| \f[CB]\\n\f[R], \f[CB]\\r\f[R], and \f[CB]\\f\f[R]. |
| .RS 2 |
| .PP |
| For example, it is possible to have a path with a space, such as |
| \f[CB]c:\\Program\ Files\f[R] that can be specified as either |
| \f[CB]"c:\\\\Program\ Files"\f[R] or, to avoid an escape, |
| \f[CB]c:\\Program"\ "Files\f[R]. |
| .RE |
| .IP \[bu] 2 |
| Any option that contains spaces, such as a path component, must be |
| within quotation marks using quotation (\[aq]"\[aq]) characters in its |
| entirety. |
| .IP \[bu] 2 |
| A string within quotation marks may contain the characters \f[CB]\\n\f[R], |
| \f[CB]\\r\f[R], \f[CB]\\t\f[R], and \f[CB]\\f\f[R]. |
| They are converted to their respective ASCII codes. |
| .IP \[bu] 2 |
| If a file name contains embedded spaces, then put the whole file name in |
| double quotation marks. |
| .IP \[bu] 2 |
| File names in an argument file are relative to the current directory, |
| not to the location of the argument file. |
| .IP \[bu] 2 |
| Use the number sign \f[CB]#\f[R] in the argument file to identify |
| comments. |
| All characters following the \f[CB]#\f[R] are ignored until the end of |
| line. |
| .IP \[bu] 2 |
| Additional at sign \f[CB]\@\f[R] prefixes to \f[CB]\@\f[R] prefixed options |
| act as an escape, (the first \f[CB]\@\f[R] is removed and the rest of the |
| arguments are presented to the launcher literally). |
| .IP \[bu] 2 |
| Lines may be continued using the continuation character (\f[CB]\\\f[R]) at |
| the end\-of\-line. |
| The two lines are concatenated with the leading white spaces trimmed. |
| To prevent trimming the leading white spaces, a continuation character |
| (\f[CB]\\\f[R]) may be placed at the first column. |
| .IP \[bu] 2 |
| Because backslash (\\) is an escape character, a backslash character |
| must be escaped with another backslash character. |
| .IP \[bu] 2 |
| Partial quote is allowed and is closed by an end\-of\-file. |
| .IP \[bu] 2 |
| An open quote stops at end\-of\-line unless \f[CB]\\\f[R] is the last |
| character, which then joins the next line by removing all leading white |
| space characters. |
| .IP \[bu] 2 |
| Wildcards (*) aren\[aq]t allowed in these lists (such as specifying |
| \f[CB]*.java\f[R]). |
| .IP \[bu] 2 |
| Use of the at sign (\f[CB]\@\f[R]) to recursively interpret files |
| isn\[aq]t supported. |
| .SS Example of Open or Partial Quotes in an Argument File |
| .PP |
| In the argument file, |
| .IP |
| .nf |
| \f[CB] |
| \-cp\ "lib/ |
| cool/ |
| app/ |
| jars |
| \f[R] |
| .fi |
| .PP |
| this is interpreted as: |
| .RS |
| .PP |
| \f[CB]\-cp\ lib/cool/app/jars\f[R] |
| .RE |
| .SS Example of a Backslash Character Escaped with Another Backslash |
| Character in an Argument File |
| .PP |
| To output the following: |
| .RS |
| .PP |
| \f[CB]\-cp\ c:\\Program\ Files\ (x86)\\Java\\jre\\lib\\ext;c:\\Program\ Files\\Java\\jre9\\lib\\ext\f[R] |
| .RE |
| .PP |
| The backslash character must be specified in the argument file as: |
| .RS |
| .PP |
| \f[CB]\-cp\ "c:\\\\Program\ Files\ (x86)\\\\Java\\\\jre\\\\lib\\\\ext;c:\\\\Program\ Files\\\\Java\\\\jre9\\\\lib\\\\ext"\f[R] |
| .RE |
| .SS Example of an EOL Escape Used to Force Concatenation of Lines in an |
| Argument File |
| .PP |
| In the argument file, |
| .IP |
| .nf |
| \f[CB] |
| \-cp\ "/lib/cool\ app/jars:\\ |
| \ \ \ \ /lib/another\ app/jars" |
| \f[R] |
| .fi |
| .PP |
| This is interpreted as: |
| .RS |
| .PP |
| \f[CB]\-cp\ /lib/cool\ app/jars:/lib/another\ app/jars\f[R] |
| .RE |
| .SS Example of Line Continuation with Leading Spaces in an Argument File |
| .PP |
| In the argument file, |
| .IP |
| .nf |
| \f[CB] |
| \-cp\ "/lib/cool\\ |
| \\app/jars??? |
| \f[R] |
| .fi |
| .PP |
| This is interpreted as: |
| .PP |
| \f[CB]\-cp\ /lib/cool\ app/jars\f[R] |
| .SS Examples of Using Single Argument File |
| .PP |
| You can use a single argument file, such as \f[CB]myargumentfile\f[R] in |
| the following example, to hold all required \f[CB]java\f[R] arguments: |
| .RS |
| .PP |
| \f[CB]java\ \@myargumentfile\f[R] |
| .RE |
| .SS Examples of Using Argument Files with Paths |
| .PP |
| You can include relative paths in argument files; however, they\[aq]re |
| relative to the current working directory and not to the paths of the |
| argument files themselves. |
| In the following example, \f[CB]path1/options\f[R] and |
| \f[CB]path2/options\f[R] represent argument files with different paths. |
| Any relative paths that they contain are relative to the current working |
| directory and not to the argument files: |
| .RS |
| .PP |
| \f[CB]java\ \@path1/options\ \@path2/classes\f[R] |
| .RE |
| .SH CODE HEAP STATE ANALYTICS |
| .SS Overview |
| .PP |
| There are occasions when having insight into the current state of the |
| JVM code heap would be helpful to answer questions such as: |
| .IP \[bu] 2 |
| Why was the JIT turned off and then on again and again? |
| .IP \[bu] 2 |
| Where has all the code heap space gone? |
| .IP \[bu] 2 |
| Why is the method sweeper not working effectively? |
| .PP |
| To provide this insight, a code heap state analytics feature has been |
| implemented that enables on\-the\-fly analysis of the code heap. |
| The analytics process is divided into two parts. |
| The first part examines the entire code heap and aggregates all |
| information that is believed to be useful or important. |
| The second part consists of several independent steps that print the |
| collected information with an emphasis on different aspects of the data. |
| Data collection and printing are done on an "on request" basis. |
| .SS Syntax |
| .PP |
| Requests for real\-time, on\-the\-fly analysis can be issued with the |
| following command: |
| .RS |
| .PP |
| \f[CB]jcmd\f[R] \f[I]pid\f[R] \f[CB]Compiler.CodeHeap_Analytics\f[R] |
| [\f[I]function\f[R]] [\f[I]granularity\f[R]] |
| .RE |
| .PP |
| If you are only interested in how the code heap looks like after running |
| a sample workload, you can use the command line option: |
| .RS |
| .PP |
| \f[CB]\-Xlog:codecache=Trace\f[R] |
| .RE |
| .PP |
| To see the code heap state when a "CodeCache full" condition exists, |
| start the VM with the command line option: |
| .RS |
| .PP |
| \f[CB]\-Xlog:codecache=Debug\f[R] |
| .RE |
| .PP |
| See \f[B]CodeHeap State Analytics (OpenJDK)\f[R] |
| [https://bugs.openjdk.java.net/secure/attachment/75649/JVM_CodeHeap_StateAnalytics_V2.pdf] |
| for a detailed description of the code heap state analytics feature, the |
| supported functions, and the granularity options. |
| .SH ENABLE LOGGING WITH THE JVM UNIFIED LOGGING FRAMEWORK |
| .PP |
| You use the \f[CB]\-Xlog\f[R] option to configure or enable logging with |
| the Java Virtual Machine (JVM) unified logging framework. |
| .SS Synopsis |
| .RS |
| .PP |
| \f[CB]\-Xlog\f[R][\f[CB]:\f[R][\f[I]what\f[R]][\f[CB]:\f[R][\f[I]output\f[R]][\f[CB]:\f[R][\f[I]decorators\f[R]][\f[CB]:\f[R]\f[I]output\-options\f[R][\f[CB],\f[R]...]]]]] |
| .PP |
| \f[CB]\-Xlog:\f[R]\f[I]directive\f[R] |
| .RE |
| .TP |
| .B \f[I]what\f[R] |
| Specifies a combination of tags and levels of the form |
| \f[I]tag1\f[R][\f[CB]+\f[R]\f[I]tag2\f[R]...][\f[CB]*\f[R]][\f[CB]=\f[R]\f[I]level\f[R]][\f[CB],\f[R]...]. |
| Unless the wildcard (\f[CB]*\f[R]) is specified, only log messages tagged |
| with exactly the tags specified are matched. |
| See \f[B]\-Xlog Tags and Levels\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[I]output\f[R] |
| Sets the type of output. |
| Omitting the \f[I]output\f[R] type defaults to \f[CB]stdout\f[R]. |
| See \f[B]\-Xlog Output\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[I]decorators\f[R] |
| Configures the output to use a custom set of decorators. |
| Omitting \f[I]decorators\f[R] defaults to \f[CB]uptime\f[R], |
| \f[CB]level\f[R], and \f[CB]tags\f[R]. |
| See \f[B]Decorations\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[I]output\-options\f[R] |
| Sets the \f[CB]\-Xlog\f[R] logging output options. |
| .RS |
| .RE |
| .TP |
| .B \f[I]directive\f[R] |
| A global option or subcommand: help, disable, async |
| .RS |
| .RE |
| .SS Description |
| .PP |
| The Java Virtual Machine (JVM) unified logging framework provides a |
| common logging system for all components of the JVM. |
| GC logging for the JVM has been changed to use the new logging |
| framework. |
| The mapping of old GC flags to the corresponding new Xlog configuration |
| is described in \f[B]Convert GC Logging Flags to Xlog\f[R]. |
| In addition, runtime logging has also been changed to use the JVM |
| unified logging framework. |
| The mapping of legacy runtime logging flags to the corresponding new |
| Xlog configuration is described in \f[B]Convert Runtime Logging Flags to |
| Xlog\f[R]. |
| .PP |
| The following provides quick reference to the \f[CB]\-Xlog\f[R] command |
| and syntax for options: |
| .TP |
| .B \f[CB]\-Xlog\f[R] |
| Enables JVM logging on an \f[CB]info\f[R] level. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-Xlog:help\f[R] |
| Prints \f[CB]\-Xlog\f[R] usage syntax and available tags, levels, and |
| decorators along with example command lines with explanations. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-Xlog:disable\f[R] |
| Turns off all logging and clears all configuration of the logging |
| framework including the default configuration for warnings and errors. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-Xlog\f[R][\f[CB]:\f[R]\f[I]option\f[R]] |
| Applies multiple arguments in the order that they appear on the command |
| line. |
| Multiple \f[CB]\-Xlog\f[R] arguments for the same output override each |
| other in their given order. |
| .RS |
| .PP |
| The \f[I]option\f[R] is set as: |
| .RS |
| .PP |
| [\f[I]tag\-selection\f[R]][\f[CB]:\f[R][\f[I]output\f[R]][\f[CB]:\f[R][\f[I]decorators\f[R]][\f[CB]:\f[R]\f[I]output\-options\f[R]]]] |
| .RE |
| .PP |
| Omitting the \f[I]tag\-selection\f[R] defaults to a tag\-set of |
| \f[CB]all\f[R] and a level of \f[CB]info\f[R]. |
| .RS |
| .PP |
| \f[I]tag\f[R][\f[CB]+\f[R]...] \f[CB]all\f[R] |
| .RE |
| .PP |
| The \f[CB]all\f[R] tag is a meta tag consisting of all tag\-sets |
| available. |
| The asterisk \f[CB]*\f[R] in a tag set definition denotes a wildcard tag |
| match. |
| Matching with a wildcard selects all tag sets that contain \f[I]at |
| least\f[R] the specified tags. |
| Without the wildcard, only exact matches of the specified tag sets are |
| selected. |
| .PP |
| \f[I]output\-options\f[R] is |
| .RS |
| .PP |
| \f[CB]filecount=\f[R]\f[I]file\-count\f[R] \f[CB]filesize=\f[R]\f[I]file size |
| with optional K, M or G suffix\f[R] |
| .RE |
| .RE |
| .SS Default Configuration |
| .PP |
| When the \f[CB]\-Xlog\f[R] option and nothing else is specified on the |
| command line, the default configuration is used. |
| The default configuration logs all messages with a level that matches |
| either warning or error regardless of what tags the message is |
| associated with. |
| The default configuration is equivalent to entering the following on the |
| command line: |
| .RS |
| .PP |
| \f[CB]\-Xlog:all=warning:stdout:uptime,level,tags\f[R] |
| .RE |
| .SS Controlling Logging at Runtime |
| .PP |
| Logging can also be controlled at run time through Diagnostic Commands |
| (with the \f[B]jcmd\f[R] utility). |
| Everything that can be specified on the command line can also be |
| specified dynamically with the \f[CB]VM.log\f[R] command. |
| As the diagnostic commands are automatically exposed as MBeans, you can |
| use JMX to change logging configuration at run time. |
| .SS \-Xlog Tags and Levels |
| .PP |
| Each log message has a level and a tag set associated with it. |
| The level of the message corresponds to its details, and the tag set |
| corresponds to what the message contains or which JVM component it |
| involves (such as, \f[CB]gc\f[R], \f[CB]jit\f[R], or \f[CB]os\f[R]). |
| Mapping GC flags to the Xlog configuration is described in \f[B]Convert |
| GC Logging Flags to Xlog\f[R]. |
| Mapping legacy runtime logging flags to the corresponding Xlog |
| configuration is described in \f[B]Convert Runtime Logging Flags to |
| Xlog\f[R]. |
| .PP |
| \f[B]Available log levels:\f[R] |
| .IP \[bu] 2 |
| \f[CB]off\f[R] |
| .IP \[bu] 2 |
| \f[CB]trace\f[R] |
| .IP \[bu] 2 |
| \f[CB]debug\f[R] |
| .IP \[bu] 2 |
| \f[CB]info\f[R] |
| .IP \[bu] 2 |
| \f[CB]warning\f[R] |
| .IP \[bu] 2 |
| \f[CB]error\f[R] |
| .PP |
| \f[B]Available log tags:\f[R] |
| .PP |
| There are literally dozens of log tags, which in the right combinations, |
| will enable a range of logging output. |
| The full set of available log tags can be seen using |
| \f[CB]\-Xlog:help\f[R]. |
| Specifying \f[CB]all\f[R] instead of a tag combination matches all tag |
| combinations. |
| .SS \-Xlog Output |
| .PP |
| The \f[CB]\-Xlog\f[R] option supports the following types of outputs: |
| .IP \[bu] 2 |
| \f[CB]stdout\f[R] \-\-\- Sends output to stdout |
| .IP \[bu] 2 |
| \f[CB]stderr\f[R] \-\-\- Sends output to stderr |
| .IP \[bu] 2 |
| \f[CB]file=\f[R]\f[I]filename\f[R] \-\-\- Sends output to text file(s). |
| .PP |
| When using \f[CB]file=\f[R]\f[I]filename\f[R], specifying \f[CB]%p\f[R] |
| and/or \f[CB]%t\f[R] in the file name expands to the JVM\[aq]s PID and |
| startup timestamp, respectively. |
| You can also configure text files to handle file rotation based on file |
| size and a number of files to rotate. |
| For example, to rotate the log file every 10 MB and keep 5 files in |
| rotation, specify the options \f[CB]filesize=10M,\ filecount=5\f[R]. |
| The target size of the files isn\[aq]t guaranteed to be exact, it\[aq]s |
| just an approximate value. |
| Files are rotated by default with up to 5 rotated files of target size |
| 20 MB, unless configured otherwise. |
| Specifying \f[CB]filecount=0\f[R] means that the log file shouldn\[aq]t be |
| rotated. |
| There\[aq]s a possibility of the pre\-existing log file getting |
| overwritten. |
| .SS \-Xlog Output Mode |
| .PP |
| By default logging messages are output synchronously \- each log message |
| is written to the designated output when the logging call is made. |
| But you can instead use asynchronous logging mode by specifying: |
| .TP |
| .B \f[CB]\-Xlog:async\f[R] |
| Write all logging asynchronously. |
| .RS |
| .RE |
| .PP |
| In asynchronous logging mode, log sites enqueue all logging messages to |
| an intermediate buffer and a standalone thread is responsible for |
| flushing them to the corresponding outputs. |
| The intermediate buffer is bounded and on buffer exhaustion the |
| enqueuing message is discarded. |
| Log entry write operations are guaranteed non\-blocking. |
| .PP |
| The option \f[CB]\-XX:AsyncLogBufferSize=N\f[R] specifies the memory |
| budget in bytes for the intermediate buffer. |
| The default value should be big enough to cater for most cases. |
| Users can provide a custom value to trade memory overhead for log |
| accuracy if they need to. |
| .SS Decorations |
| .PP |
| Logging messages are decorated with information about the message. |
| You can configure each output to use a custom set of decorators. |
| The order of the output is always the same as listed in the table. |
| You can configure the decorations to be used at run time. |
| Decorations are prepended to the log message. |
| For example: |
| .IP |
| .nf |
| \f[CB] |
| [6.567s][info][gc,old]\ Old\ collection\ complete |
| \f[R] |
| .fi |
| .PP |
| Omitting \f[CB]decorators\f[R] defaults to \f[CB]uptime\f[R], |
| \f[CB]level\f[R], and \f[CB]tags\f[R]. |
| The \f[CB]none\f[R] decorator is special and is used to turn off all |
| decorations. |
| .PP |
| \f[CB]time\f[R] (\f[CB]t\f[R]), \f[CB]utctime\f[R] (\f[CB]utc\f[R]), |
| \f[CB]uptime\f[R] (\f[CB]u\f[R]), \f[CB]timemillis\f[R] (\f[CB]tm\f[R]), |
| \f[CB]uptimemillis\f[R] (\f[CB]um\f[R]), \f[CB]timenanos\f[R] (\f[CB]tn\f[R]), |
| \f[CB]uptimenanos\f[R] (\f[CB]un\f[R]), \f[CB]hostname\f[R] (\f[CB]hn\f[R]), |
| \f[CB]pid\f[R] (\f[CB]p\f[R]), \f[CB]tid\f[R] (\f[CB]ti\f[R]), \f[CB]level\f[R] |
| (\f[CB]l\f[R]), \f[CB]tags\f[R] (\f[CB]tg\f[R]) decorators can also be |
| specified as \f[CB]none\f[R] for no decoration. |
| .PP |
| .TS |
| tab(@); |
| lw(14.9n) lw(55.1n). |
| T{ |
| Decorations |
| T}@T{ |
| Description |
| T} |
| _ |
| T{ |
| \f[CB]time\f[R] or \f[CB]t\f[R] |
| T}@T{ |
| Current time and date in ISO\-8601 format. |
| T} |
| T{ |
| \f[CB]utctime\f[R] or \f[CB]utc\f[R] |
| T}@T{ |
| Universal Time Coordinated or Coordinated Universal Time. |
| T} |
| T{ |
| \f[CB]uptime\f[R] or \f[CB]u\f[R] |
| T}@T{ |
| Time since the start of the JVM in seconds and milliseconds. |
| For example, 6.567s. |
| T} |
| T{ |
| \f[CB]timemillis\f[R] or \f[CB]tm\f[R] |
| T}@T{ |
| The same value as generated by \f[CB]System.currentTimeMillis()\f[R] |
| T} |
| T{ |
| \f[CB]uptimemillis\f[R] or \f[CB]um\f[R] |
| T}@T{ |
| Milliseconds since the JVM started. |
| T} |
| T{ |
| \f[CB]timenanos\f[R] or \f[CB]tn\f[R] |
| T}@T{ |
| The same value generated by \f[CB]System.nanoTime()\f[R]. |
| T} |
| T{ |
| \f[CB]uptimenanos\f[R] or \f[CB]un\f[R] |
| T}@T{ |
| Nanoseconds since the JVM started. |
| T} |
| T{ |
| \f[CB]hostname\f[R] or \f[CB]hn\f[R] |
| T}@T{ |
| The host name. |
| T} |
| T{ |
| \f[CB]pid\f[R] or \f[CB]p\f[R] |
| T}@T{ |
| The process identifier. |
| T} |
| T{ |
| \f[CB]tid\f[R] or \f[CB]ti\f[R] |
| T}@T{ |
| The thread identifier. |
| T} |
| T{ |
| \f[CB]level\f[R] or \f[CB]l\f[R] |
| T}@T{ |
| The level associated with the log message. |
| T} |
| T{ |
| \f[CB]tags\f[R] or \f[CB]tg\f[R] |
| T}@T{ |
| The tag\-set associated with the log message. |
| T} |
| .TE |
| .SS Convert GC Logging Flags to Xlog |
| .PP |
| .TS |
| tab(@); |
| lw(22.4n) lw(16.5n) lw(31.2n). |
| T{ |
| Legacy Garbage Collection (GC) Flag |
| T}@T{ |
| Xlog Configuration |
| T}@T{ |
| Comment |
| T} |
| _ |
| T{ |
| \f[CB]G1PrintHeapRegions\f[R] |
| T}@T{ |
| \f[CB]\-Xlog:gc+region=trace\f[R] |
| T}@T{ |
| Not Applicable |
| T} |
| T{ |
| \f[CB]GCLogFileSize\f[R] |
| T}@T{ |
| No configuration available |
| T}@T{ |
| Log rotation is handled by the framework. |
| T} |
| T{ |
| \f[CB]NumberOfGCLogFiles\f[R] |
| T}@T{ |
| Not Applicable |
| T}@T{ |
| Log rotation is handled by the framework. |
| T} |
| T{ |
| \f[CB]PrintAdaptiveSizePolicy\f[R] |
| T}@T{ |
| \f[CB]\-Xlog:gc+ergo*=\f[R]\f[I]level\f[R] |
| T}@T{ |
| Use a \f[I]level\f[R] of \f[CB]debug\f[R] for most of the information, or a |
| \f[I]level\f[R] of \f[CB]trace\f[R] for all of what was logged for |
| \f[CB]PrintAdaptiveSizePolicy\f[R]. |
| T} |
| T{ |
| \f[CB]PrintGC\f[R] |
| T}@T{ |
| \f[CB]\-Xlog:gc\f[R] |
| T}@T{ |
| Not Applicable |
| T} |
| T{ |
| \f[CB]PrintGCApplicationConcurrentTime\f[R] |
| T}@T{ |
| \f[CB]\-Xlog:safepoint\f[R] |
| T}@T{ |
| Note that \f[CB]PrintGCApplicationConcurrentTime\f[R] and |
| \f[CB]PrintGCApplicationStoppedTime\f[R] are logged on the same tag and |
| aren\[aq]t separated in the new logging. |
| T} |
| T{ |
| \f[CB]PrintGCApplicationStoppedTime\f[R] |
| T}@T{ |
| \f[CB]\-Xlog:safepoint\f[R] |
| T}@T{ |
| Note that \f[CB]PrintGCApplicationConcurrentTime\f[R] and |
| \f[CB]PrintGCApplicationStoppedTime\f[R] are logged on the same tag and |
| not separated in the new logging. |
| T} |
| T{ |
| \f[CB]PrintGCCause\f[R] |
| T}@T{ |
| Not Applicable |
| T}@T{ |
| GC cause is now always logged. |
| T} |
| T{ |
| \f[CB]PrintGCDateStamps\f[R] |
| T}@T{ |
| Not Applicable |
| T}@T{ |
| Date stamps are logged by the framework. |
| T} |
| T{ |
| \f[CB]PrintGCDetails\f[R] |
| T}@T{ |
| \f[CB]\-Xlog:gc*\f[R] |
| T}@T{ |
| Not Applicable |
| T} |
| T{ |
| \f[CB]PrintGCID\f[R] |
| T}@T{ |
| Not Applicable |
| T}@T{ |
| GC ID is now always logged. |
| T} |
| T{ |
| \f[CB]PrintGCTaskTimeStamps\f[R] |
| T}@T{ |
| \f[CB]\-Xlog:gc+task*=debug\f[R] |
| T}@T{ |
| Not Applicable |
| T} |
| T{ |
| \f[CB]PrintGCTimeStamps\f[R] |
| T}@T{ |
| Not Applicable |
| T}@T{ |
| Time stamps are logged by the framework. |
| T} |
| T{ |
| \f[CB]PrintHeapAtGC\f[R] |
| T}@T{ |
| \f[CB]\-Xlog:gc+heap=trace\f[R] |
| T}@T{ |
| Not Applicable |
| T} |
| T{ |
| \f[CB]PrintReferenceGC\f[R] |
| T}@T{ |
| \f[CB]\-Xlog:gc+ref*=debug\f[R] |
| T}@T{ |
| Note that in the old logging, \f[CB]PrintReferenceGC\f[R] had an effect |
| only if \f[CB]PrintGCDetails\f[R] was also enabled. |
| T} |
| T{ |
| \f[CB]PrintStringDeduplicationStatistics\f[R] |
| T}@T{ |
| `\-Xlog:gc+stringdedup*=debug |
| T}@T{ |
| ` Not Applicable |
| T} |
| T{ |
| \f[CB]PrintTenuringDistribution\f[R] |
| T}@T{ |
| \f[CB]\-Xlog:gc+age*=\f[R]\f[I]level\f[R] |
| T}@T{ |
| Use a \f[I]level\f[R] of \f[CB]debug\f[R] for the most relevant |
| information, or a \f[I]level\f[R] of \f[CB]trace\f[R] for all of what was |
| logged for \f[CB]PrintTenuringDistribution\f[R]. |
| T} |
| T{ |
| \f[CB]UseGCLogFileRotation\f[R] |
| T}@T{ |
| Not Applicable |
| T}@T{ |
| What was logged for \f[CB]PrintTenuringDistribution\f[R]. |
| T} |
| .TE |
| .SS Convert Runtime Logging Flags to Xlog |
| .PP |
| These legacy flags are no longer recognized and will cause an error if |
| used directly. |
| Use their unified logging equivalent instead. |
| .PP |
| .TS |
| tab(@); |
| lw(15.0n) lw(20.2n) lw(34.7n). |
| T{ |
| Legacy Runtime Flag |
| T}@T{ |
| Xlog Configuration |
| T}@T{ |
| Comment |
| T} |
| _ |
| T{ |
| \f[CB]TraceExceptions\f[R] |
| T}@T{ |
| \f[CB]\-Xlog:exceptions=info\f[R] |
| T}@T{ |
| Not Applicable |
| T} |
| T{ |
| \f[CB]TraceClassLoading\f[R] |
| T}@T{ |
| \f[CB]\-Xlog:class+load=\f[R]\f[I]level\f[R] |
| T}@T{ |
| Use \f[I]level\f[R]=\f[CB]info\f[R] for regular information, or |
| \f[I]level\f[R]=\f[CB]debug\f[R] for additional information. |
| In Unified Logging syntax, \f[CB]\-verbose:class\f[R] equals |
| \f[CB]\-Xlog:class+load=info,class+unload=info\f[R]. |
| T} |
| T{ |
| \f[CB]TraceClassLoadingPreorder\f[R] |
| T}@T{ |
| \f[CB]\-Xlog:class+preorder=debug\f[R] |
| T}@T{ |
| Not Applicable |
| T} |
| T{ |
| \f[CB]TraceClassUnloading\f[R] |
| T}@T{ |
| \f[CB]\-Xlog:class+unload=\f[R]\f[I]level\f[R] |
| T}@T{ |
| Use \f[I]level\f[R]=\f[CB]info\f[R] for regular information, or |
| \f[I]level\f[R]=\f[CB]trace\f[R] for additional information. |
| In Unified Logging syntax, \f[CB]\-verbose:class\f[R] equals |
| \f[CB]\-Xlog:class+load=info,class+unload=info\f[R]. |
| T} |
| T{ |
| \f[CB]VerboseVerification\f[R] |
| T}@T{ |
| \f[CB]\-Xlog:verification=info\f[R] |
| T}@T{ |
| Not Applicable |
| T} |
| T{ |
| \f[CB]TraceClassPaths\f[R] |
| T}@T{ |
| \f[CB]\-Xlog:class+path=info\f[R] |
| T}@T{ |
| Not Applicable |
| T} |
| T{ |
| \f[CB]TraceClassResolution\f[R] |
| T}@T{ |
| \f[CB]\-Xlog:class+resolve=debug\f[R] |
| T}@T{ |
| Not Applicable |
| T} |
| T{ |
| \f[CB]TraceClassInitialization\f[R] |
| T}@T{ |
| \f[CB]\-Xlog:class+init=info\f[R] |
| T}@T{ |
| Not Applicable |
| T} |
| T{ |
| \f[CB]TraceLoaderConstraints\f[R] |
| T}@T{ |
| \f[CB]\-Xlog:class+loader+constraints=info\f[R] |
| T}@T{ |
| Not Applicable |
| T} |
| T{ |
| \f[CB]TraceClassLoaderData\f[R] |
| T}@T{ |
| \f[CB]\-Xlog:class+loader+data=\f[R]\f[I]level\f[R] |
| T}@T{ |
| Use \f[I]level\f[R]=\f[CB]debug\f[R] for regular information or |
| \f[I]level\f[R]=\f[CB]trace\f[R] for additional information. |
| T} |
| T{ |
| \f[CB]TraceSafepointCleanupTime\f[R] |
| T}@T{ |
| \f[CB]\-Xlog:safepoint+cleanup=info\f[R] |
| T}@T{ |
| Not Applicable |
| T} |
| T{ |
| \f[CB]TraceSafepoint\f[R] |
| T}@T{ |
| \f[CB]\-Xlog:safepoint=debug\f[R] |
| T}@T{ |
| Not Applicable |
| T} |
| T{ |
| \f[CB]TraceMonitorInflation\f[R] |
| T}@T{ |
| \f[CB]\-Xlog:monitorinflation=debug\f[R] |
| T}@T{ |
| Not Applicable |
| T} |
| T{ |
| \f[CB]TraceBiasedLocking\f[R] |
| T}@T{ |
| \f[CB]\-Xlog:biasedlocking=\f[R]\f[I]level\f[R] |
| T}@T{ |
| Use \f[I]level\f[R]=\f[CB]info\f[R] for regular information, or |
| \f[I]level\f[R]=\f[CB]trace\f[R] for additional information. |
| T} |
| T{ |
| \f[CB]TraceRedefineClasses\f[R] |
| T}@T{ |
| \f[CB]\-Xlog:redefine+class*=\f[R]\f[I]level\f[R] |
| T}@T{ |
| \f[I]level\f[R]=\f[CB]info\f[R], \f[CB]debug\f[R], and \f[CB]trace\f[R] provide |
| increasing amounts of information. |
| T} |
| .TE |
| .SS \-Xlog Usage Examples |
| .PP |
| The following are \f[CB]\-Xlog\f[R] examples. |
| .TP |
| .B \f[CB]\-Xlog\f[R] |
| Logs all messages by using the \f[CB]info\f[R] level to \f[CB]stdout\f[R] |
| with \f[CB]uptime\f[R], \f[CB]levels\f[R], and \f[CB]tags\f[R] decorations. |
| This is equivalent to using: |
| .RS |
| .RS |
| .PP |
| \f[CB]\-Xlog:all=info:stdout:uptime,levels,tags\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-Xlog:gc\f[R] |
| Logs messages tagged with the \f[CB]gc\f[R] tag using \f[CB]info\f[R] level |
| to \f[CB]stdout\f[R]. |
| The default configuration for all other messages at level |
| \f[CB]warning\f[R] is in effect. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-Xlog:gc,safepoint\f[R] |
| Logs messages tagged either with the \f[CB]gc\f[R] or \f[CB]safepoint\f[R] |
| tags, both using the \f[CB]info\f[R] level, to \f[CB]stdout\f[R], with |
| default decorations. |
| Messages tagged with both \f[CB]gc\f[R] and \f[CB]safepoint\f[R] won\[aq]t |
| be logged. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-Xlog:gc+ref=debug\f[R] |
| Logs messages tagged with both \f[CB]gc\f[R] and \f[CB]ref\f[R] tags, using |
| the \f[CB]debug\f[R] level to \f[CB]stdout\f[R], with default decorations. |
| Messages tagged only with one of the two tags won\[aq]t be logged. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-Xlog:gc=debug:file=gc.txt:none\f[R] |
| Logs messages tagged with the \f[CB]gc\f[R] tag using the \f[CB]debug\f[R] |
| level to a file called \f[CB]gc.txt\f[R] with no decorations. |
| The default configuration for all other messages at level |
| \f[CB]warning\f[R] is still in effect. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-Xlog:gc=trace:file=gctrace.txt:uptimemillis,pids:filecount=5,filesize=1024\f[R] |
| Logs messages tagged with the \f[CB]gc\f[R] tag using the \f[CB]trace\f[R] |
| level to a rotating file set with 5 files with size 1 MB with the base |
| name \f[CB]gctrace.txt\f[R] and uses decorations \f[CB]uptimemillis\f[R] and |
| \f[CB]pid\f[R]. |
| .RS |
| .PP |
| The default configuration for all other messages at level |
| \f[CB]warning\f[R] is still in effect. |
| .RE |
| .TP |
| .B \f[CB]\-Xlog:gc::uptime,tid\f[R] |
| Logs messages tagged with the \f[CB]gc\f[R] tag using the default |
| \[aq]info\[aq] level to default the output \f[CB]stdout\f[R] and uses |
| decorations \f[CB]uptime\f[R] and \f[CB]tid\f[R]. |
| The default configuration for all other messages at level |
| \f[CB]warning\f[R] is still in effect. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-Xlog:gc*=info,safepoint*=off\f[R] |
| Logs messages tagged with at least \f[CB]gc\f[R] using the \f[CB]info\f[R] |
| level, but turns off logging of messages tagged with \f[CB]safepoint\f[R]. |
| Messages tagged with both \f[CB]gc\f[R] and \f[CB]safepoint\f[R] won\[aq]t |
| be logged. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-Xlog:disable\ \-Xlog:safepoint=trace:safepointtrace.txt\f[R] |
| Turns off all logging, including warnings and errors, and then enables |
| messages tagged with \f[CB]safepoint\f[R]using \f[CB]trace\f[R]level to the |
| file \f[CB]safepointtrace.txt\f[R]. |
| The default configuration doesn\[aq]t apply, because the command line |
| started with \f[CB]\-Xlog:disable\f[R]. |
| .RS |
| .RE |
| .SS Complex \-Xlog Usage Examples |
| .PP |
| The following describes a few complex examples of using the |
| \f[CB]\-Xlog\f[R] option. |
| .TP |
| .B \f[CB]\-Xlog:gc+class*=debug\f[R] |
| Logs messages tagged with at least \f[CB]gc\f[R] and \f[CB]class\f[R] tags |
| using the \f[CB]debug\f[R] level to \f[CB]stdout\f[R]. |
| The default configuration for all other messages at the level |
| \f[CB]warning\f[R] is still in effect |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-Xlog:gc+meta*=trace,class*=off:file=gcmetatrace.txt\f[R] |
| Logs messages tagged with at least the \f[CB]gc\f[R] and \f[CB]meta\f[R] |
| tags using the \f[CB]trace\f[R] level to the file \f[CB]metatrace.txt\f[R] |
| but turns off all messages tagged with \f[CB]class\f[R]. |
| Messages tagged with \f[CB]gc\f[R], \f[CB]meta\f[R], and \f[CB]class\f[R] |
| aren\[aq]t be logged as \f[CB]class*\f[R] is set to off. |
| The default configuration for all other messages at level |
| \f[CB]warning\f[R] is in effect except for those that include |
| \f[CB]class\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-Xlog:gc+meta=trace\f[R] |
| Logs messages tagged with exactly the \f[CB]gc\f[R] and \f[CB]meta\f[R] tags |
| using the \f[CB]trace\f[R] level to \f[CB]stdout\f[R]. |
| The default configuration for all other messages at level |
| \f[CB]warning\f[R] is still be in effect. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-Xlog:gc+class+heap*=debug,meta*=warning,threads*=off\f[R] |
| Logs messages tagged with at least \f[CB]gc\f[R], \f[CB]class\f[R], and |
| \f[CB]heap\f[R] tags using the \f[CB]trace\f[R] level to \f[CB]stdout\f[R] but |
| only log messages tagged with \f[CB]meta\f[R] with level. |
| The default configuration for all other messages at the level |
| \f[CB]warning\f[R] is in effect except for those that include |
| \f[CB]threads\f[R]. |
| .RS |
| .RE |
| .SH VALIDATE JAVA VIRTUAL MACHINE FLAG ARGUMENTS |
| .PP |
| You use values provided to all Java Virtual Machine (JVM) command\-line |
| flags for validation and, if the input value is invalid or |
| out\-of\-range, then an appropriate error message is displayed. |
| .PP |
| Whether they\[aq]re set ergonomically, in a command line, by an input |
| tool, or through the APIs (for example, classes contained in the package |
| \f[CB]java.lang.management\f[R]) the values provided to all Java Virtual |
| Machine (JVM) command\-line flags are validated. |
| Ergonomics are described in Java Platform, Standard Edition HotSpot |
| Virtual Machine Garbage Collection Tuning Guide. |
| .PP |
| Range and constraints are validated either when all flags have their |
| values set during JVM initialization or a flag\[aq]s value is changed |
| during runtime (for example using the \f[CB]jcmd\f[R] tool). |
| The JVM is terminated if a value violates either the range or constraint |
| check and an appropriate error message is printed on the error stream. |
| .PP |
| For example, if a flag violates a range or a constraint check, then the |
| JVM exits with an error: |
| .IP |
| .nf |
| \f[CB] |
| java\ \-XX:AllocatePrefetchStyle=5\ \-version |
| intx\ AllocatePrefetchStyle=5\ is\ outside\ the\ allowed\ range\ [\ 0\ ...\ 3\ ] |
| Improperly\ specified\ VM\ option\ \[aq]AllocatePrefetchStyle=5\[aq] |
| Error:\ Could\ not\ create\ the\ Java\ Virtual\ Machine. |
| Error:\ A\ fatal\ exception\ has\ occurred.\ Program\ will\ exit. |
| \f[R] |
| .fi |
| .PP |
| The flag \f[CB]\-XX:+PrintFlagsRanges\f[R] prints the range of all the |
| flags. |
| This flag allows automatic testing of the flags by the values provided |
| by the ranges. |
| For the flags that have the ranges specified, the type, name, and the |
| actual range is printed in the output. |
| .PP |
| For example, |
| .IP |
| .nf |
| \f[CB] |
| intx\ \ \ ThreadStackSize\ [\ 0\ ...\ 9007199254740987\ ]\ {pd\ product} |
| \f[R] |
| .fi |
| .PP |
| For the flags that don\[aq]t have the range specified, the values |
| aren\[aq]t displayed in the print out. |
| For example: |
| .IP |
| .nf |
| \f[CB] |
| size_t\ NewSize\ \ \ \ \ \ \ \ \ [\ \ \ ...\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ]\ {product} |
| \f[R] |
| .fi |
| .PP |
| This helps to identify the flags that need to be implemented. |
| The automatic testing framework can skip those flags that don\[aq]t have |
| values and aren\[aq]t implemented. |
| .SH LARGE PAGES |
| .PP |
| You use large pages, also known as huge pages, as memory pages that are |
| significantly larger than the standard memory page size (which varies |
| depending on the processor and operating system). |
| Large pages optimize processor Translation\-Lookaside Buffers. |
| .PP |
| A Translation\-Lookaside Buffer (TLB) is a page translation cache that |
| holds the most\-recently used virtual\-to\-physical address |
| translations. |
| A TLB is a scarce system resource. |
| A TLB miss can be costly because the processor must then read from the |
| hierarchical page table, which may require multiple memory accesses. |
| By using a larger memory page size, a single TLB entry can represent a |
| larger memory range. |
| This results in less pressure on a TLB, and memory\-intensive |
| applications may have better performance. |
| .PP |
| However, using large pages can negatively affect system performance. |
| For example, when a large amount of memory is pinned by an application, |
| it may create a shortage of regular memory and cause excessive paging in |
| other applications and slow down the entire system. |
| Also, a system that has been up for a long time could produce excessive |
| fragmentation, which could make it impossible to reserve enough large |
| page memory. |
| When this happens, either the OS or JVM reverts to using regular pages. |
| .PP |
| Linux and Windows support large pages. |
| .SS Large Pages Support for Linux |
| .PP |
| Linux supports large pages since version 2.6. |
| To check if your environment supports large pages, try the following: |
| .IP |
| .nf |
| \f[CB] |
| #\ cat\ /proc/meminfo\ |\ grep\ Huge |
| HugePages_Total:\ 0 |
| HugePages_Free:\ 0 |
| \&... |
| Hugepagesize:\ 2048\ kB |
| \f[R] |
| .fi |
| .PP |
| If the output contains items prefixed with "Huge", then your system |
| supports large pages. |
| The values may vary depending on environment. |
| The \f[CB]Hugepagesize\f[R] field shows the default large page size in |
| your environment, and the other fields show details for large pages of |
| this size. |
| Newer kernels have support for multiple large page sizes. |
| To list the supported page sizes, run this: |
| .IP |
| .nf |
| \f[CB] |
| #\ ls\ /sys/kernel/mm/hugepages/ |
| hugepages\-1048576kB\ \ hugepages\-2048kB |
| \f[R] |
| .fi |
| .PP |
| The above environment supports 2 MB and 1 GB large pages, but they need |
| to be configured so that the JVM can use them. |
| When using large pages and not enabling transparent huge pages (option |
| \f[CB]\-XX:+UseTransparentHugePages\f[R]), the number of large pages must |
| be pre\-allocated. |
| For example, to enable 8 GB of memory to be backed by 2 MB large pages, |
| login as \f[CB]root\f[R] and run: |
| .RS |
| .PP |
| \f[CB]#\ echo\ 4096\ >\ /sys/kernel/mm/hugepages/hugepages\-2048kB/nr_hugepages\f[R] |
| .RE |
| .PP |
| It is always recommended to check the value of \f[CB]nr_hugepages\f[R] |
| after the request to make sure the kernel was able to allocate the |
| requested number of large pages. |
| .PP |
| When using the option \f[CB]\-XX:+UseSHM\f[R] to enable large pages you |
| also need to make sure the \f[CB]SHMMAX\f[R] parameter is configured to |
| allow large enough shared memory segments to be allocated. |
| To allow a maximum shared segment of 8 GB, login as \f[CB]root\f[R] and |
| run: |
| .RS |
| .PP |
| \f[CB]#\ echo\ 8589934592\ >\ /proc/sys/kernel/shmmax\f[R] |
| .RE |
| .PP |
| In some environments this is not needed since the default value is large |
| enough, but it is important to make sure the value is large enough to |
| fit the amount of memory intended to be backed by large pages. |
| .RS |
| .PP |
| \f[B]Note:\f[R] The values contained in \f[CB]/proc\f[R] and \f[CB]/sys\f[R] |
| reset after you reboot your system, so may want to set them in an |
| initialization script (for example, \f[CB]rc.local\f[R] or |
| \f[CB]sysctl.conf\f[R]). |
| .RE |
| .PP |
| If you configure the OS kernel parameters to enable use of large pages, |
| the Java processes may allocate large pages for the Java heap as well as |
| other internal areas, for example: |
| .IP \[bu] 2 |
| Code cache |
| .IP \[bu] 2 |
| Marking bitmaps |
| .PP |
| Consequently, if you configure the \f[CB]nr_hugepages\f[R] parameter to |
| the size of the Java heap, then the JVM can still fail to allocate the |
| heap using large pages because other areas such as the code cache might |
| already have used some of the configured large pages. |
| .SS Large Pages Support for Windows |
| .PP |
| To use large pages support on Windows, the administrator must first |
| assign additional privileges to the user who is running the application: |
| .IP "1." 3 |
| Select \f[B]Control Panel\f[R], \f[B]Administrative Tools\f[R], and then |
| \f[B]Local Security Policy\f[R]. |
| .IP "2." 3 |
| Select \f[B]Local Policies\f[R] and then \f[B]User Rights Assignment\f[R]. |
| .IP "3." 3 |
| Double\-click \f[B]Lock pages in memory\f[R], then add users and/or |
| groups. |
| .IP "4." 3 |
| Reboot your system. |
| .PP |
| Note that these steps are required even if it\[aq]s the administrator |
| who\[aq]s running the application, because administrators by default |
| don\[aq]t have the privilege to lock pages in memory. |
| .SH APPLICATION CLASS DATA SHARING |
| .PP |
| Application Class Data Sharing (AppCDS) extends class data sharing (CDS) |
| to enable application classes to be placed in a shared archive. |
| .PP |
| In addition to the core library classes, AppCDS supports \f[B]Class Data |
| Sharing\f[R] |
| [https://docs.oracle.com/en/java/javase/12/vm/class\-data\-sharing.html#GUID\-7EAA3411\-8CF0\-4D19\-BD05\-DF5E1780AA91] |
| from the following locations: |
| .IP \[bu] 2 |
| Platform classes from the runtime image |
| .IP \[bu] 2 |
| Application classes from the runtime image |
| .IP \[bu] 2 |
| Application classes from the class path |
| .IP \[bu] 2 |
| Application classes from the module path |
| .PP |
| Archiving application classes provides better start up time at runtime. |
| When running multiple JVM processes, AppCDS also reduces the runtime |
| footprint with memory sharing for read\-only metadata. |
| .PP |
| CDS/AppCDS supports archiving classes from JAR files only. |
| .PP |
| Prior to JDK 11, a non\-empty directory was reported as a fatal error in |
| the following conditions: |
| .IP \[bu] 2 |
| For base CDS, a non\-empty directory cannot exist in the |
| \f[CB]\-Xbootclasspath/a\f[R] path |
| .IP \[bu] 2 |
| With \f[CB]\-XX:+UseAppCDS\f[R], a non\-empty directory could not exist in |
| the \f[CB]\-Xbootclasspath/a\f[R] path, class path, and module path. |
| .PP |
| In JDK 11 and later, \f[CB]\-XX:+UseAppCDS\f[R] is obsolete and the |
| behavior for a non\-empty directory is based on the class types in the |
| classlist. |
| A non\-empty directory is reported as a fatal error in the following |
| conditions: |
| .IP \[bu] 2 |
| If application classes or platform classes are not loaded, dump time |
| only reports an error if a non\-empty directory exists in |
| \f[CB]\-Xbootclasspath/a\f[R] path |
| .IP \[bu] 2 |
| If application classes or platform classes are loaded, dump time reports |
| an error for a non\-empty directory that exists in |
| \f[CB]\-Xbootclasspath/a\f[R] path, class path, or module path |
| .PP |
| In JDK 11 and later, using |
| \f[CB]\-XX:DumpLoadedClassList=\f[R]\f[I]class_list_file\f[R] results a |
| generated classlist with all classes (both system library classes and |
| application classes) included. |
| You no longer have to specify \f[CB]\-XX:+UseAppCDS\f[R] with |
| \f[CB]\-XX:DumpLoadedClassList\f[R] to produce a complete class list. |
| .PP |
| In JDK 11 and later, because \f[CB]UseAppCDS\f[R] is obsolete, |
| \f[CB]SharedArchiveFile\f[R] becomes a product flag by default. |
| Specifying \f[CB]+UnlockDiagnosticVMOptions\f[R] for |
| \f[CB]SharedArchiveFile\f[R] is no longer needed in any configuration. |
| .PP |
| Class Data Sharing (CDS)/AppCDS does not support archiving array classes |
| in a class list. |
| When an array in the class list is encountered, CDS dump time gives the |
| explicit error message: |
| .RS |
| .PP |
| \f[CB]Preload\ Warning:\ Cannot\ find\f[R] \f[I]array_name\f[R] |
| .RE |
| .PP |
| Although an array in the class list is not allowed, some array classes |
| can still be created at CDS/AppCDS dump time. |
| Those arrays are created during the execution of the Java code used by |
| the Java class loaders (\f[CB]PlatformClassLoader\f[R] and the system |
| class loader) to load classes at dump time. |
| The created arrays are archived with the rest of the loaded classes. |
| .SS Extending Class Data Sharing to Support the Module Path |
| .PP |
| In JDK 11, Class Data Sharing (CDS) has been improved to support |
| archiving classes from the module path. |
| .IP \[bu] 2 |
| To create a CDS archive using the \f[CB]\-\-module\-path\f[R] VM option, |
| use the following command line syntax: |
| .RS 2 |
| .RS |
| .PP |
| \f[CB]java\ \-Xshare:dump\ \-XX:SharedClassListFile=\f[R]\f[I]class_list_file\f[R] |
| \f[CB]\-XX:SharedArchiveFile=\f[R]\f[I]shared_archive_file\f[R] |
| \f[CB]\-\-module\-path=\f[R]\f[I]path_to_modular_jar\f[R] \f[CB]\-m\f[R] |
| \f[I]module_name\f[R] |
| .RE |
| .RE |
| .IP \[bu] 2 |
| To run with a CDS archive using the \f[CB]\-\-module\-path\f[R] VM option, |
| use the following the command line syntax: |
| .RS 2 |
| .RS |
| .PP |
| \f[CB]java\ \-XX:SharedArchiveFile=\f[R]\f[I]shared_archive_file\f[R] |
| \f[CB]\-\-module\-path=\f[R]\f[I]path_to_modular_jar\f[R] \f[CB]\-m\f[R] |
| \f[I]module_name\f[R] |
| .RE |
| .RE |
| .PP |
| The following table describes how the VM options related to module paths |
| can be used along with the \f[CB]\-Xshare\f[R] option. |
| .PP |
| .TS |
| tab(@); |
| l l l. |
| T{ |
| Option |
| T}@T{ |
| \-Xshare:dump |
| T}@T{ |
| \-Xshare:{on,auto} |
| T} |
| _ |
| T{ |
| \f[CB]\-\-module\-path\f[R][1] \f[I]mp\f[R] |
| T}@T{ |
| Allowed |
| T}@T{ |
| Allowed[2] |
| T} |
| T{ |
| \f[CB]\-\-module\f[R] |
| T}@T{ |
| Allowed |
| T}@T{ |
| Allowed |
| T} |
| T{ |
| \f[CB]\-\-add\-module\f[R] |
| T}@T{ |
| Allowed |
| T}@T{ |
| Allowed |
| T} |
| T{ |
| \f[CB]\-\-upgrade\-module\-path\f[R][3] |
| T}@T{ |
| Disallowed (exits if specified) |
| T}@T{ |
| Allowed (disables CDS) |
| T} |
| T{ |
| \f[CB]\-\-patch\-module\f[R][4] |
| T}@T{ |
| Disallowed (exits if specified) |
| T}@T{ |
| Allowed (disables CDS) |
| T} |
| T{ |
| \f[CB]\-\-limit\-modules\f[R][5] |
| T}@T{ |
| Disallowed (exits if specified) |
| T}@T{ |
| Allowed (disables CDS) |
| T} |
| .TE |
| .PP |
| [1] Although there are two ways of specifying a module in a |
| \f[CB]\-\-module\-path\f[R], that is, modular JAR or exploded module, only |
| modular JARs are supported. |
| .PP |
| [2] Different \f[I]mp\f[R] can be specified during dump time versus run |
| time. |
| If an archived class K was loaded from \f[CB]mp1.jar\f[R] at dump time, |
| but changes in \f[I]mp\f[R] cause it to be available from a different |
| \f[CB]mp2.jar\f[R] at run time, then the archived version of K will be |
| disregarded at run time; K will be loaded dynamically. |
| .PP |
| [3] Currently, only two system modules are upgradeable |
| (\f[CB]java.compiler\f[R] and \f[CB]jdk.internal.vm.compiler\f[R]). |
| However, these modules are seldom upgraded in production software. |
| .PP |
| [4] As documented in JEP 261, using \f[CB]\-\-patch\-module\f[R] is |
| strongly discouraged for production use. |
| .PP |
| [5] \f[CB]\-\-limit\-modules\f[R] is intended for testing purposes. |
| It is seldom used in production software. |
| .PP |
| If \f[CB]\-\-upgrade\-module\-path\f[R], \f[CB]\-\-patch\-module\f[R], or |
| \f[CB]\-\-limit\-modules\f[R] is specified at dump time, an error will be |
| printed and the JVM will exit. |
| For example, if the \f[CB]\-\-limit\-modules\f[R] option is specified at |
| dump time, the user will see the following error: |
| .IP |
| .nf |
| \f[CB] |
| Error\ occurred\ during\ initialization\ of\ VM |
| Cannot\ use\ the\ following\ option\ when\ dumping\ the\ shared\ archive:\ \-\-limit\-modules |
| \f[R] |
| .fi |
| .PP |
| If \f[CB]\-\-upgrade\-module\-path\f[R], \f[CB]\-\-patch\-module\f[R], or |
| \f[CB]\-\-limit\-modules\f[R] is specified at run time, a warning message |
| will be printed indicating that CDS is disabled. |
| For example, if the \f[CB]\-\-limit\-modules\f[R] options is specified at |
| run time, the user will see the following warning: |
| .IP |
| .nf |
| \f[CB] |
| Java\ HotSpot(TM)\ 64\-Bit\ Server\ VM\ warning:\ CDS\ is\ disabled\ when\ the\ \-\-limit\-modules\ option\ is\ specified. |
| \f[R] |
| .fi |
| .PP |
| Several other noteworthy things include: |
| .IP \[bu] 2 |
| Any valid combinations of \f[CB]\-cp\f[R] and \f[CB]\-\-module\-path\f[R] |
| are supported. |
| .IP \[bu] 2 |
| A non\-empty directory in the module path causes a fatal error. |
| The user will see the following error messages: |
| .RS 2 |
| .IP |
| .nf |
| \f[CB] |
| Error:\ non\-empty\ directory\ <directory>\ Hint:\ enable\ \-Xlog:class+path=info\ to\ diagnose\ the\ failure\ Error\ occurred\ during\ initialization\ of\ VM\ Cannot\ have\ non\-empty\ directory\ in\ paths |
| \f[R] |
| .fi |
| .RE |
| .IP \[bu] 2 |
| Unlike the class path, there\[aq]s no restriction that the module path |
| at dump time must be equal to or be a prefix of the module path at run |
| time. |
| .IP \[bu] 2 |
| The archive is invalidated if an existing JAR in the module path is |
| updated after archive generation. |
| .IP \[bu] 2 |
| Removing a JAR from the module path does not invalidate the shared |
| archive. |
| Archived classes from the removed JAR are not used at runtime. |
| .SS Dynamic CDS archive |
| .PP |
| Dynamic CDS archive extends AppCDS to allow archiving of classes when a |
| Java application exits. |
| It improves the usability of AppCDS by eliminating the trial run step |
| for creating a class list for each application. |
| The archived classes include all loaded application classes and library |
| classes that are not present in the default CDS archive which is |
| included in the JDK. |
| .PP |
| A base archive is required when creating a dynamic archive. |
| If the base archive is not specified, the default CDS archive is used as |
| the base archive. |
| .PP |
| To create a dynamic CDS archive with the default CDS archive as the base |
| archive, just add the |
| \f[CB]\-XX:ArchiveClassesAtExit=<dynamic\ archive>\f[R] option to the |
| command line for running the Java application. |
| .PP |
| If the default CDS archive does not exist, the VM will exit with the |
| following error: |
| .IP |
| .nf |
| \f[CB] |
| ArchiveClassesAtExit\ not\ supported\ when\ base\ CDS\ archive\ is\ not\ loaded |
| \f[R] |
| .fi |
| .PP |
| To run the Java application using a dynamic CDS archive, just add the |
| \f[CB]\-XX:SharedArchiveFile=<dynamic\ archive>\f[R] option to the command |
| line for running the Java application. |
| .PP |
| The base archive is not required to be specified in the command line. |
| The base archive information, including its name and full path, will be |
| retrieved from the dynamic archive header. |
| Note that the user could also use the \f[CB]\-XX:SharedArchiveFile\f[R] |
| option for specifying a regular AppCDS archive. |
| Therefore, the specified archive in the \f[CB]\-XX:SharedArchiveFile\f[R] |
| option could be either a regular or dynamic archive. |
| During VM start up the specified archive header will be read. |
| If \f[CB]\-XX:SharedArchiveFile\f[R] refers to a regular archive, then the |
| behavior will be unchanged. |
| If \f[CB]\-XX:SharedArchiveFile\f[R] refers to a dynamic archive, the VM |
| will retrieve the base archive location from the dynamic archive. |
| If the dynamic archive was created with the default CDS archive, then |
| the current default CDS archive will be used, and will be found relative |
| to the current run time environment. |
| .PP |
| Please refer to \f[B]JDK\-8221706\f[R] |
| [https://bugs.openjdk.java.net/browse/JDK\-8221706] for details on error |
| checking during dynamic CDS archive dump time and run time. |
| .SS Creating a Shared Archive File and Using It to Run an Application |
| .SS AppCDS archive |
| .PP |
| The following steps create a shared archive file that contains all the |
| classes used by the \f[CB]test.Hello\f[R] application. |
| The last step runs the application with the shared archive file. |
| .IP "1." 3 |
| Create a list of all classes used by the \f[CB]test.Hello\f[R] |
| application. |
| The following command creates a file named \f[CB]hello.classlist\f[R] that |
| contains a list of all classes used by this application: |
| .RS 4 |
| .RS |
| .PP |
| \f[CB]java\ \-Xshare:off\ \-XX:DumpLoadedClassList=hello.classlist\ \-cp\ hello.jar\ test.Hello\f[R] |
| .RE |
| .PP |
| Note that the classpath specified by the \f[CB]\-cp\f[R] parameter must |
| contain only JAR files. |
| .RE |
| .IP "2." 3 |
| Create a shared archive, named \f[CB]hello.jsa\f[R], that contains all the |
| classes in \f[CB]hello.classlist\f[R]: |
| .RS 4 |
| .RS |
| .PP |
| \f[CB]java\ \-Xshare:dump\ \-XX:SharedArchiveFile=hello.jsa\ \-XX:SharedClassListFile=hello.classlist\ \-cp\ hello.jar\f[R] |
| .RE |
| .PP |
| Note that the classpath used at archive creation time must be the same |
| as (or a prefix of) the classpath used at run time. |
| .RE |
| .IP "3." 3 |
| Run the application \f[CB]test.Hello\f[R] with the shared archive |
| \f[CB]hello.jsa\f[R]: |
| .RS 4 |
| .RS |
| .PP |
| \f[CB]java\ \-XX:SharedArchiveFile=hello.jsa\ \-cp\ hello.jar\ test.Hello\f[R] |
| .RE |
| .RE |
| .IP "4." 3 |
| \f[B]Optional\f[R] Verify that the \f[CB]test.Hello\f[R] application is |
| using the class contained in the \f[CB]hello.jsa\f[R] shared archive: |
| .RS 4 |
| .RS |
| .PP |
| \f[CB]java\ \-XX:SharedArchiveFile=hello.jsa\ \-cp\ hello.jar\ \-verbose:class\ test.Hello\f[R] |
| .RE |
| .PP |
| The output of this command should contain the following text: |
| .IP |
| .nf |
| \f[CB] |
| Loaded\ test.Hello\ from\ shared\ objects\ file\ by\ sun/misc/Launcher$AppClassLoader |
| \f[R] |
| .fi |
| .RE |
| .SS Dynamic CDS archive |
| .PP |
| The following steps create a dynamic CDS archive file that contains the |
| classes used by the \f[CB]test.Hello\f[R] application and are not included |
| in the default CDS archive. |
| The second step runs the application with the dynamic CDS archive. |
| .IP "1." 3 |
| Create a dynamic CDS archive, named \f[CB]hello.jsa\f[R], that contains |
| all the classes in \f[CB]hello.jar\f[R] loaded by the application |
| \f[CB]test.Hello\f[R]: |
| .RS 4 |
| .RS |
| .PP |
| \f[CB]java\ \-XX:ArchiveClassesAtExit=hello.jsa\ \-cp\ hello.jar\ Hello\f[R] |
| .RE |
| .PP |
| Note that the classpath used at archive creation time must be the same |
| as (or a prefix of) the classpath used at run time. |
| .RE |
| .IP "2." 3 |
| Run the application \f[CB]test.Hello\f[R] with the shared archive |
| \f[CB]hello.jsa\f[R]: |
| .RS 4 |
| .RS |
| .PP |
| \f[CB]java\ \-XX:SharedArchiveFile=hello.jsa\ \-cp\ hello.jar\ test.Hello\f[R] |
| .RE |
| .RE |
| .IP "3." 3 |
| \f[B]Optional\f[R] Repeat step 4 of the previous section to verify that |
| the \f[CB]test.Hello\f[R] application is using the class contained in the |
| \f[CB]hello.jsa\f[R] shared archive. |
| .PP |
| To automate the above steps 1 and 2, one can write a script such as the |
| following: |
| .IP |
| .nf |
| \f[CB] |
| \ \ \ \ ARCHIVE=hello.jsa |
| \ \ \ \ if\ test\ \-f\ $ARCHIVE;\ then |
| \ \ \ \ \ \ \ \ FLAG="\-XX:SharedArchiveFile=$ARCHIVE" |
| \ \ \ \ else |
| \ \ \ \ \ \ \ \ FLAG="\-XX:ArchiveClassesAtExit=$ARCHIVE" |
| \ \ \ \ fi |
| \ \ \ \ $JAVA_HOME/bin/java\ \-cp\ hello.jar\ $FLAG\ test.Hello |
| \f[R] |
| .fi |
| .PP |
| Like an AppCDS archive, the archive needs to be re\-generated if the |
| Java version has changed. |
| The above script could be adjusted to account for the Java version as |
| follows: |
| .IP |
| .nf |
| \f[CB] |
| \ \ \ \ ARCHIVE=hello.jsa |
| \ \ \ \ VERSION=foo.version |
| \ \ \ \ if\ test\ \-f\ $ARCHIVE\ \-a\ \-f\ $VERSION\ &&\ cmp\ \-s\ $VERSION\ $JAVA_HOME/release;\ then |
| \ \ \ \ \ \ \ \ FLAG="\-XX:SharedArchiveFile=$ARCHIVE" |
| \ \ \ \ else |
| \ \ \ \ \ \ \ \ FLAG="\-XX:ArchiveClassesAtExit=$ARCHIVE" |
| \ \ \ \ \ \ \ \ cp\ \-f\ $JAVA_HOME/release\ $VERSION |
| \ \ \ \ fi |
| \ \ \ \ $JAVA_HOME/bin/java\ \-cp\ hello.jar\ $FLAG\ test.Hello |
| \f[R] |
| .fi |
| .PP |
| Currently, we don\[aq]t support concurrent dumping operations to the |
| same CDS archive. |
| Care should be taken to avoid multiple writers to the same CDS archive. |
| .PP |
| The user could also create a dynamic CDS archive with a specific base |
| archive, e.g. |
| named as \f[CB]base.jsa\f[R] as follows: |
| .RS |
| .PP |
| \f[CB]java\ \-XX:SharedArchiveFile=base.jsa\ \-XX:ArchiveClassesAtExit=hello.jsa\ \-cp\ hello.jar\ Hello\f[R] |
| .RE |
| .PP |
| To run the application using the dynamic CDS archive \f[CB]hello.jsa\f[R] |
| and a specific base CDS archive \f[CB]base.jsa\f[R]: |
| .RS |
| .PP |
| \f[CB]java\ \-XX:SharedArchiveFile=base.jsa:hello.jsa\ \-cp\ hello.jar\ Hello\f[R] |
| .RE |
| .PP |
| Note that on Windows, the above path delimiter \f[CB]:\f[R] should be |
| replaced with \f[CB];\f[R]. |
| .PP |
| The above command for specifying a base archive is useful if the base |
| archive used for creating the dynamic archive has been moved. |
| Normally, just specifying the dynamic archive should be sufficient since |
| the base archive info can be retrieved from the dynamic archive header. |
| .SS Sharing a Shared Archive Across Multiple Application Processes |
| .PP |
| You can share the same archive file across multiple applications |
| processes. |
| This reduces memory usage because the archive is memory\-mapped into the |
| address space of the processes. |
| The operating system automatically shares the read\-only pages across |
| these processes. |
| .PP |
| The following steps demonstrate how to create a common archive that can |
| be shared by different applications. |
| Classes from \f[CB]common.jar\f[R], \f[CB]hello.jar\f[R] and \f[CB]hi.jar\f[R] |
| are archived in the \f[CB]common.jsa\f[R] because they are all in the |
| classpath during the archiving step (step 3). |
| .PP |
| To include classes from \f[CB]hello.jar\f[R] and \f[CB]hi.jar\f[R], the |
| \f[CB]\&.jar\f[R] files must be added to the classpath specified by the |
| \f[CB]\-cp\f[R] parameter. |
| .IP "1." 3 |
| Create a list of all classes used by the \f[CB]Hello\f[R] application and |
| another list for the \f[CB]Hi\f[R] application: |
| .RS 4 |
| .RS |
| .PP |
| \f[CB]java\ \-XX:DumpLoadedClassList=hello.classlist\ \-cp\ common.jar:hello.jar\ Hello\f[R] |
| .RE |
| .RS |
| .PP |
| \f[CB]java\ \-XX:DumpLoadedClassList=hi.classlist\ \-cp\ common.jar:hi.jar\ Hi\f[R] |
| .RE |
| .RE |
| .IP "2." 3 |
| Create a single list of classes used by all the applications that will |
| share the shared archive file. |
| .RS 4 |
| .PP |
| \f[B]Linux and macOS\f[R] The following commands combine the files |
| \f[CB]hello.classlist\f[R] and \f[CB]hi.classlist\f[R] into one file, |
| \f[CB]common.classlist\f[R]: |
| .RS |
| .PP |
| \f[CB]cat\ hello.classlist\ hi.classlist\ >\ common.classlist\f[R] |
| .RE |
| .PP |
| \f[B]Windows\f[R] The following commands combine the files |
| \f[CB]hello.classlist\f[R] and \f[CB]hi.classlist\f[R] into one file, |
| \f[CB]common.classlist\f[R]: |
| .RS |
| .PP |
| \f[CB]type\ hello.classlist\ hi.classlist\ >\ common.classlist\f[R] |
| .RE |
| .RE |
| .IP "3." 3 |
| Create a shared archive named \f[CB]common.jsa\f[R] that contains all the |
| classes in \f[CB]common.classlist\f[R]: |
| .RS 4 |
| .RS |
| .PP |
| \f[CB]java\ \-Xshare:dump\ \-XX:SharedArchiveFile=common.jsa\ \-XX:SharedClassListFile=common.classlist\ \-cp\ common.jar:hello.jar:hi.jar\f[R] |
| .RE |
| .PP |
| The classpath parameter used is the common class path prefix shared by |
| the \f[CB]Hello\f[R] and \f[CB]Hi\f[R] applications. |
| .RE |
| .IP "4." 3 |
| Run the \f[CB]Hello\f[R] and \f[CB]Hi\f[R] applications with the same shared |
| archive: |
| .RS 4 |
| .RS |
| .PP |
| \f[CB]java\ \-XX:SharedArchiveFile=common.jsa\ \-cp\ common.jar:hello.jar:hi.jar\ Hello\f[R] |
| .RE |
| .RS |
| .PP |
| \f[CB]java\ \-XX:SharedArchiveFile=common.jsa\ \-cp\ common.jar:hello.jar:hi.jar\ Hi\f[R] |
| .RE |
| .RE |
| .SS Specifying Additional Shared Data Added to an Archive File |
| .PP |
| The \f[CB]SharedArchiveConfigFile\f[R] option is used to specify |
| additional shared data to add to the archive file. |
| .RS |
| .PP |
| \f[CB]\-XX:SharedArchiveConfigFile=\f[R]\f[I]shared_config_file\f[R] |
| .RE |
| .PP |
| JDK 9 and later supports adding both symbols and string objects to an |
| archive for memory sharing when you have multiple JVM processes running |
| on the same host. |
| An example of this is having multiple JVM processes that use the same |
| set of Java EE classes. |
| When these common classes are loaded and used, new symbols and strings |
| may be created and added to the JVM\[aq]s internal "symbol" and "string" |
| tables. |
| At runtime, the symbols or string objects mapped from the archive file |
| can be shared across multiple JVM processes, resulting in a reduction of |
| overall memory usage. |
| In addition, archiving strings also provides added performance benefits |
| in both startup time and runtime execution. |
| .PP |
| In JDK 10 and later, CONSTANT_String entries in archived classes are |
| resolved to interned String objects at dump time, and all interned |
| String objects are archived. |
| However, even though all CONSTANT_String literals in all archived |
| classes are resolved, it might still beneficial to add additional |
| strings that are not string literals in class files, but are likely to |
| be used by your application at run time. |
| .PP |
| Symbol data should be generated by the \f[CB]jcmd\f[R] tool attaching to a |
| running JVM process. |
| See \f[B]jcmd\f[R]. |
| .PP |
| The following is an example of the symbol dumping command in |
| \f[CB]jcmd\f[R]: |
| .RS |
| .PP |
| \f[CB]jcmd\f[R] \f[I]pid\f[R] \f[CB]VM.symboltable\ \-verbose\f[R] |
| .RE |
| .RS |
| .PP |
| \f[B]Note:\f[R] The first line (process ID) and the second line |
| (\f[CB]\@VERSION\ ...\f[R]) of this \f[CB]jcmd\f[R] output should be |
| excluded from the configuration file. |
| .RE |
| .SS Example of a Configuration File |
| .PP |
| The following is an example of a configuration file: |
| .IP |
| .nf |
| \f[CB] |
| VERSION:\ 1.0 |
| \@SECTION:\ Symbol |
| 10\ \-1:\ linkMethod |
| \f[R] |
| .fi |
| .PP |
| In the configuration file example, the \f[CB]\@SECTION:\ Symbol\f[R] entry |
| uses the following format: |
| .RS |
| .PP |
| \f[I]length\f[R] \f[I]refcount\f[R]\f[CB]:\f[R] \f[I]symbol\f[R] |
| .RE |
| .PP |
| The \f[I]refcount\f[R] for a shared symbol is always \f[CB]\-1\f[R]. |
| .PP |
| \f[CB]\@SECTION\f[R] specifies the type of the section that follows it. |
| All data within the section must be the same type that\[aq]s specified |
| by \f[CB]\@SECTION\f[R]. |
| Different types of data can\[aq]t be mixed. |
| Multiple separated data sections for the same type specified by |
| different \f[CB]\@SECTION\f[R] are allowed within one |
| \f[CB]shared_config_file\f[R] . |
| .SH PERFORMANCE TUNING EXAMPLES |
| .PP |
| You can use the Java advanced runtime options to optimize the |
| performance of your applications. |
| .SS Tuning for Higher Throughput |
| .PP |
| Use the following commands and advanced options to achieve higher |
| throughput performance for your application: |
| .RS |
| .PP |
| \f[CB]java\ \-server\ \-XX:+UseParallelGC\ \-XX:+UseLargePages\ \-Xmn10g\ \ \-Xms26g\ \-Xmx26g\f[R] |
| .RE |
| .SS Tuning for Lower Response Time |
| .PP |
| Use the following commands and advanced options to achieve lower |
| response times for your application: |
| .RS |
| .PP |
| \f[CB]java\ \-XX:+UseG1GC\ \-XX:MaxGCPauseMillis=100\f[R] |
| .RE |
| .SS Keeping the Java Heap Small and Reducing the Dynamic Footprint of |
| Embedded Applications |
| .PP |
| Use the following advanced runtime options to keep the Java heap small |
| and reduce the dynamic footprint of embedded applications: |
| .RS |
| .PP |
| \f[CB]\-XX:MaxHeapFreeRatio=10\ \-XX:MinHeapFreeRatio=5\f[R] |
| .RE |
| .RS |
| .PP |
| \f[B]Note:\f[R] The defaults for these two options are 70% and 40% |
| respectively. |
| Because performance sacrifices can occur when using these small |
| settings, you should optimize for a small footprint by reducing these |
| settings as much as possible without introducing unacceptable |
| performance degradation. |
| .RE |
| .SH EXIT STATUS |
| .PP |
| The following exit values are typically returned by the launcher when |
| the launcher is called with the wrong arguments, serious errors, or |
| exceptions thrown by the JVM. |
| However, a Java application may choose to return any value by using the |
| API call \f[CB]System.exit(exitValue)\f[R]. |
| The values are: |
| .IP \[bu] 2 |
| \f[CB]0\f[R]: Successful completion |
| .IP \[bu] 2 |
| \f[CB]>0\f[R]: An error occurred |