From 3242c8919e2e3354e55df9f22c8bc682b49809e6 Mon Sep 17 00:00:00 2001 From: "lingjun.cg" Date: Sun, 6 Oct 2024 09:38:02 +0800 Subject: [PATCH] [Runtime] CRaC: no need to close the files that open with write&append mode when do checkpointing. Summary: Add a new option CRaCAppendOnlyLogFiles to configure the files can be ignored when do checkpointing, and create an empty file if not exist when restore. Testing: jdk/crac/AppendOnlyFileTest.java Reviewers: lei.yul,denghui.ddh Issue: https://github.com/dragonwell-project/dragonwell11/issues/867 --- src/hotspot/os/linux/crac_linux.cpp | 171 + src/hotspot/os/linux/crac_linux.hpp | 84 + src/hotspot/os/linux/os_linux.cpp | 86 +- src/hotspot/share/prims/jvm.cpp | 43 - src/hotspot/share/runtime/globals.hpp | 1 - src/hotspot/share/runtime/globals_ext.hpp | 7 + src/hotspot/share/runtime/os.hpp | 1 - src/java.base/share/man/java.1 | 5940 ----------------- .../unix/native/criuengine/criuengine.c | 16 +- .../jdk/crac/AppendAppClassLoaderTest.java | 22 + test/jdk/jdk/crac/AppendOnlyFileTest.java | 206 + test/jdk/jdk/crac/Foo.java | 22 + .../jdk/crac/PseudoPersistentFileTest.java | 22 + test/jdk/jdk/crac/RestorePipeFdTest.java | 22 + test/jdk/jdk/crac/TestHello.java | 22 + test/lib/jdk/test/lib/crac/CracBuilder.java | 11 + 16 files changed, 608 insertions(+), 6068 deletions(-) create mode 100644 src/hotspot/os/linux/crac_linux.cpp create mode 100644 src/hotspot/os/linux/crac_linux.hpp delete mode 100644 src/java.base/share/man/java.1 create mode 100644 test/jdk/jdk/crac/AppendOnlyFileTest.java diff --git a/src/hotspot/os/linux/crac_linux.cpp b/src/hotspot/os/linux/crac_linux.cpp new file mode 100644 index 00000000000..61d493aac42 --- /dev/null +++ b/src/hotspot/os/linux/crac_linux.cpp @@ -0,0 +1,171 @@ +/* + * Copyright (c) 2024 Alibaba Group Holding Limited. 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. Alibaba designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * 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. + * + */ + +#include +#include +#include +#include + +#include "crac_linux.hpp" +#include "runtime/globals.hpp" + +//the value should equal to PseudoPersistentMode.SKIP_LOG_FILES in criuengine.c +#define SKIP_LOG_FILES_MODE 0x20 + +PseudoPersistent::PseudoPersistent(GrowableArray + *ppfd, const char *config) : + _ppfd(ppfd), _append_files(NULL), _append_file_configs(NULL) { + if (config == NULL) { + return; + } + + _append_file_configs = new(ResourceObj::C_HEAP, mtInternal) GrowableArray(1, true); + if (!strcmp(config, "*")) { + AppendFileConfig *cfg = new AppendFileConfig(all, NULL, NULL); + _append_file_configs->append(cfg); + return; + } + + const char *p = config, *s = config; + while (*p) { + if (*(p + 1) == ',' || *(p + 1) == '\0') { + if (p - s > 2 && *s == '*' && *(s + 1) == '.') { + _append_file_configs->append(new AppendFileConfig(by_extension, s + 2, p + 1)); + } else { + _append_file_configs->append(new AppendFileConfig(by_full_path, s, p + 1)); + } + if (*(p + 1) == ',') { + p += 2; + s = p; + } else { + break; + } + } else { + p++; + } + } +} + + +bool PseudoPersistent::write_marked(const char* image_dir) { + char *path; + if (-1 == asprintf(&path, "%s/pseudopersistent", image_dir)) { + return false; + } + FILE *f = fopen(path, "w"); + if (f == NULL) { + fprintf(stderr, "open file: %s for write failed, error: %s\n", + path, strerror(errno)); + free(path); + return false; + } + + if (_ppfd) { + for(int i = 0 ; i < _ppfd->length();i++) { + PseudoPersistentFileDesc *ppfd = _ppfd->adr_at(i); + if (ppfd->_mark) { + fprintf(f, "%d,%s\n", ppfd->_mode, ppfd->_path); + } + } + } + + if (_append_files) { + for (int i = 0; i < _append_files->length(); i++) { + fprintf(f, "%d,%s\n", SKIP_LOG_FILES_MODE, _append_files->at(i)); + } + } + + fclose(f); + free(path); + return true; +} + +bool PseudoPersistent::in_registered_list(const char *path) { + if (!_ppfd) { + return false; + } + int j = 0; + while (j < _ppfd->length()) { + PseudoPersistentFileDesc *ppfd = _ppfd->adr_at(j); + int r = strcmp(ppfd->_path, path); + if (r == 0) { + ppfd->_mark = true; + return true; + } else if (r > 0) { + return false; + } + ++j; + } + return false; +} + +bool PseudoPersistent::in_configured_list(const char* path, int fd) { + if (_append_file_configs == NULL) { + return false; + } + + int ret = fcntl(fd, F_GETFL); + if (ret != -1 && ((ret & O_ACCMODE) == O_WRONLY) && (ret & O_APPEND)) { + for (int i = 0; i < _append_file_configs->length(); i++) { + if (_append_file_configs->at(i)->match(path)) { + if (_append_files == NULL) { + _append_files = new(ResourceObj::C_HEAP, mtInternal) GrowableArray(2, true); + } + char *copy_path = NEW_C_HEAP_ARRAY(char, strlen(path) + 1, mtInternal); + strcpy(copy_path, path); + _append_files->append(copy_path); + return true; + } + } + } + return false; +} + +bool PseudoPersistent::AppendFileConfig::match(const char *file) { + if (_type == all) { + return true; + } else if (_type == by_extension) { + const char *p = strrchr(file, '.'); + return p != NULL && strlen(p + 1) == _size && !strncmp(p + 1, _start_ext_or_file, _size); + } else if (_type == by_full_path) { + return strlen(file) == _size && !strncmp(file, _start_ext_or_file, _size); + } + return false; +} + +PseudoPersistent::~PseudoPersistent() { + if (_append_files != NULL) { + for (int i = 0; i < _append_files->length(); i++) { + FREE_C_HEAP_ARRAY(char, _append_files->at(i)); + } + delete _append_files; + _append_files = NULL; + } + + if (_append_file_configs != NULL) { + for (int i = 0; i < _append_file_configs->length(); i++) { + delete _append_file_configs->at(i); + } + delete _append_file_configs; + _append_file_configs = NULL; + } +} diff --git a/src/hotspot/os/linux/crac_linux.hpp b/src/hotspot/os/linux/crac_linux.hpp new file mode 100644 index 00000000000..61f71b73278 --- /dev/null +++ b/src/hotspot/os/linux/crac_linux.hpp @@ -0,0 +1,84 @@ +/* + * Copyright (c) 2024 Alibaba Group Holding Limited. 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. Alibaba designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * 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. + * + */ + +#ifndef OS_LINUX_CRAC_LINUX_HPP +#define OS_LINUX_CRAC_LINUX_HPP +#include "utilities/growableArray.hpp" + +struct PseudoPersistentFileDesc { + int _mode; + bool _mark; + const char* _path; + PseudoPersistentFileDesc(int mode, const char *path) : + _mode(mode), + _path(path), + _mark(false) + {} + + PseudoPersistentFileDesc(): + _mode(0), + _path(NULL), + _mark(false) + {} +}; + +class PseudoPersistent { +private: + enum AppendFileConfigType { + all, + by_extension, + by_full_path + }; + + class AppendFileConfig : public CHeapObj { + AppendFileConfigType _type; + size_t _size; + const char *_start_ext_or_file; + public: + AppendFileConfig(AppendFileConfigType type, const char *start_ext_or_file, const char *end_ext_or_file) + : _type(type), _start_ext_or_file(start_ext_or_file), _size(0) { + if (start_ext_or_file && end_ext_or_file) { + _size = end_ext_or_file - start_ext_or_file; + } + } + bool match(const char *file); + }; + +private: + GrowableArray *_ppfd; + GrowableArray *_append_files; + GrowableArray *_append_file_configs; +public: + PseudoPersistent(GrowableArray* ppfd, const char* config); + ~PseudoPersistent(); + + bool test_and_mark(const char *path, int fd) { + return in_registered_list(path) || in_configured_list(path, fd); + } + + bool write_marked(const char* image_dir); +private: + bool in_configured_list(const char* path, int fd); + bool in_registered_list(const char *path); +}; + +#endif //OS_LINUX_CRAC_LINUX_HPP diff --git a/src/hotspot/os/linux/os_linux.cpp b/src/hotspot/os/linux/os_linux.cpp index 8dabf9c0f99..e91fe1faaad 100644 --- a/src/hotspot/os/linux/os_linux.cpp +++ b/src/hotspot/os/linux/os_linux.cpp @@ -32,6 +32,7 @@ #include "code/vtableStubs.hpp" #include "compiler/compileBroker.hpp" #include "compiler/disassembler.hpp" +#include "crac_linux.hpp" #include "interpreter/interpreter.hpp" #include "logging/log.hpp" #include "logging/logStream.hpp" @@ -270,80 +271,6 @@ struct PersistentResourceDesc { {} }; -struct PseudoPersistentFileDesc { - int _mode; - bool _mark; - const char* _path; - PseudoPersistentFileDesc(int mode, const char *path) : - _mode(mode), - _path(path), - _mark(false) - {} - - PseudoPersistentFileDesc(): - _mode(0), - _path(NULL), - _mark(false) - {} -}; - -class PseudoPersistent { -private: - GrowableArray* _ppfd; -public: - PseudoPersistent(GrowableArray* ppfd): - _ppfd(ppfd) - {} - - bool test_and_mark(const char *path) { - if (!_ppfd) { - return false; - } - int j = 0; - while (j < _ppfd->length()) { - PseudoPersistentFileDesc *ppfd = _ppfd->adr_at(j); - int r = strcmp(ppfd->_path, path); - if (r == 0) { - ppfd->_mark = true; - return true; - break; - } else if (r > 0) { - return false; - break; - } - ++j; - } - return false; - } - - bool write_marked(const char *image_dir) { - if (!_ppfd) { - return true; - } - char *path; - if (-1 == asprintf(&path, "%s/pseudopersistent", image_dir)) { - return false; - } - FILE *f = fopen(path, "w"); - if (f == NULL) { - fprintf(stderr, "open file: %s for write failed, error: %s\n", - path, strerror(errno)); - free(path); - return false; - } - int j = 0; - while (j < _ppfd->length()) { - PseudoPersistentFileDesc *ppfd = _ppfd->adr_at(j); - if (ppfd->_mark) { - fprintf(f, "%d,%s\n", ppfd->_mode, ppfd->_path); - } - ++j; - } - fclose(f); - free(path); - return true; - } -}; struct CracFailDep { int _type; @@ -7009,11 +6936,6 @@ int os::compare_file_modified_times(const char* file1, const char* file2) { return diff; } -void os::wake_up(Thread *thread) { - pthread_t tid = thread->osthread()->pthread_id(); - pthread_kill(tid, SIG_WAKE_UP); -} - // CRaC jlong os::Linux::restore_start_time() { @@ -7502,7 +7424,7 @@ void VM_Crac::doit() { do_classpaths(mark_all_in, &fds, Arguments::get_ext_dirs()); mark_persistent(&fds); - PseudoPersistent pp(_pseudo_persistent); + PseudoPersistent pp(_pseudo_persistent, CRaCAppendOnlyLogFiles); int markcnt = 0; // dry-run fails checkpoint @@ -7518,8 +7440,9 @@ void VM_Crac::doit() { const char* details = 0 < linkret ? detailsbuf : ""; print_resources("JVM: FD fd=%d type=%s: details1=\"%s\" ", i, stat2strtype(fds.get_stat(i)->st_mode), details); + struct stat* st = fds.get_stat(i); - if (pp.test_and_mark(detailsbuf)) { + if (S_ISREG(st->st_mode) && pp.test_and_mark(detailsbuf, i)) { markcnt++; print_resources("OK: user registered pseudo persistent file \n"); continue; @@ -7530,7 +7453,6 @@ void VM_Crac::doit() { continue; } - struct stat* st = fds.get_stat(i); if (S_ISCHR(st->st_mode)) { const int mjr = major(st->st_rdev); const int mnr = minor(st->st_rdev); diff --git a/src/hotspot/share/prims/jvm.cpp b/src/hotspot/share/prims/jvm.cpp index 2b44291d21c..55f43a3fe6b 100644 --- a/src/hotspot/share/prims/jvm.cpp +++ b/src/hotspot/share/prims/jvm.cpp @@ -3937,54 +3937,11 @@ JVM_ENTRY(void, JVM_NotifyDump(JNIEnv *env, jclass ignored)) QuickStart::notify_dump(); JVM_END -JVM_LEAF(void, JVM_CollectJVMConf(JNIEnv *env, jclass ignored)) - JVMWrapper("JVM_CollectJVMConf"); - QuickStart::collect_jvm_conf(); -JVM_END - JVM_ENTRY(jboolean, JVM_CheckpointEnabled(JNIEnv *env, jclass ignored)) JVMWrapper("JVM_CheckpointEnabled"); return CRaCCheckpointTo ? JNI_TRUE : JNI_FALSE; JVM_END -JVM_ENTRY(jobjectArray, JVM_GetModuleNames(JNIEnv *env, jclass ignored)) - JVMWrapper("JVM_GetModuleNames"); - - if (!DumpModuleNames) { - return NULL; - } - - JarFileTable* jarTable = SystemDictionary::jarFileTable(); - MutexLocker mu(OpenedJarFile_lock, THREAD); - ResourceMark rm; - const int len = jarTable->number_of_entries(); - const char *arr[len]; - int idx = 0; - for (int pindex = 0; pindex < jarTable->table_size(); pindex++) { - for (JarFileEntry* probe = jarTable->bucket(pindex); - probe != NULL; - probe = probe->next()) { - arr[idx++] = probe->literal()->as_C_string(); - } - } - assert(idx <= len, "out of bound"); - - // Allocate result array - objArrayOop r = oopFactory::new_objArray(SystemDictionary::String_klass(), len, CHECK_NULL); - objArrayHandle result (THREAD, r); - for (int i = 0; i < len; i++) { - Handle str = java_lang_String::create_from_str(arr[i], CHECK_NULL); - result->obj_at_put(i, str()); - } - return (jobjectArray) JNIHandles::make_local(env, result()); -JVM_END - -JVM_ENTRY(jstring, JVM_GetJDKBootClassPathAppend(JNIEnv *env, jclass ignored)) - JVMWrapper("JVM_GetJDKBootClassPathAppend"); - Handle str = java_lang_String::create_from_str(Arguments::get_jdk_boot_class_path_append(), CHECK_NULL); - return (jstring) JNIHandles::make_local(env, str()); -JVM_END - JVM_ENTRY(jobjectArray, JVM_Checkpoint(JNIEnv *env, jboolean dry_run, jlong jcmd_stream)) Handle ret = os::Linux::checkpoint(dry_run, jcmd_stream, CHECK_NULL); return (jobjectArray) JNIHandles::make_local(THREAD, ret()); diff --git a/src/hotspot/share/runtime/globals.hpp b/src/hotspot/share/runtime/globals.hpp index 6574e63c79e..db06b9a263a 100644 --- a/src/hotspot/share/runtime/globals.hpp +++ b/src/hotspot/share/runtime/globals.hpp @@ -2787,7 +2787,6 @@ define_pd_global(uint64_t,MaxRAM, 1ULL*G); * Macros for factoring of globals */ - // Interface macros #define DECLARE_PRODUCT_FLAG(type, name, value, doc) extern "C" type name; #define DECLARE_PD_PRODUCT_FLAG(type, name, doc) extern "C" type name; diff --git a/src/hotspot/share/runtime/globals_ext.hpp b/src/hotspot/share/runtime/globals_ext.hpp index dcec9c1524d..6adf0a8cd76 100644 --- a/src/hotspot/share/runtime/globals_ext.hpp +++ b/src/hotspot/share/runtime/globals_ext.hpp @@ -104,6 +104,13 @@ product(ccstr, CRaCRestoreInheritPipeFds, NULL, \ "Specify the pipe fds that inherit from parent process that need" \ "to restore.If there are multiple fds, separate them with comma.") \ + \ + product(ccstr, CRaCAppendOnlyLogFiles, NULL, \ + "Files that no need to be closed when do checkpointing." \ + "These files must open with write and append mode first." \ + "*: all matched files." \ + "*.log,*.txt: match given extension files." \ + "/x/a.log,/y/b.log: match by full file path") \ //add new AJDK specific flags here diff --git a/src/hotspot/share/runtime/os.hpp b/src/hotspot/share/runtime/os.hpp index 313a80142a9..7554653e256 100644 --- a/src/hotspot/share/runtime/os.hpp +++ b/src/hotspot/share/runtime/os.hpp @@ -1075,7 +1075,6 @@ class os: AllStatic { char fileSep, char pathSep); static bool set_boot_path(char fileSep, char pathSep); - }; #ifndef _WINDOWS diff --git a/src/java.base/share/man/java.1 b/src/java.base/share/man/java.1 deleted file mode 100644 index 28bee9db316..00000000000 --- a/src/java.base/share/man/java.1 +++ /dev/null @@ -1,5940 +0,0 @@ -.\" 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\ \ HelloWorld.java -java\ \-cp\ \ 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:CRaCCheckpointTo=\f[R]\f[I]directory\f[R] -The CRaC (Coordinated Restore at Checkpoint) Project provides checkpointing of -a running Java program into an image directory. Restoring from the image should -solve some of the problematic start-up and warm-up times. -.PP -This option defines a path to the snapshot which is currently a directory. The -directory will be created if it does not exist, but no parent directories are -created. -.RS -.RE -.TP -.B \f[CB]\-XX:CRaCRestoreFrom=\f[R]\f[I]directory\f[R] -Restores a snapshot created by -\f[CB]\-XX:CRaCCheckpointTo=\f[R]\f[I]directory\f[R]. -.RS -.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\-.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.hprof\f[R] where \f[CB]\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\ \ 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=\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=\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 diff --git a/src/java.base/unix/native/criuengine/criuengine.c b/src/java.base/unix/native/criuengine/criuengine.c index 5c3547f5c84..3de335b90ad 100644 --- a/src/java.base/unix/native/criuengine/criuengine.c +++ b/src/java.base/unix/native/criuengine/criuengine.c @@ -60,6 +60,7 @@ enum PseudoPersistentMode { OVERRIDE_WHEN_RESTORE = 0x04, COPY_WHEN_RESTORE = 0x08, SYMLINK_WHEN_RESTORE = 0x10, + SKIP_LOG_FILES = 0x20 }; static int create_cppath(const char *imagedir); @@ -490,7 +491,7 @@ int mkpath(const char *path, mode_t mode) { } static int restore_pseudo_persistent_file(const char *imagedir, int id, int mode, const char *dest) { - if (!(mode & SAVE_RESTORE)) { + if (!(mode & SAVE_RESTORE) && !(mode & SKIP_LOG_FILES)) { return 0; } struct stat st; @@ -519,6 +520,19 @@ static int restore_pseudo_persistent_file(const char *imagedir, int id, int mode dest, src, strerror(errno)); return 1; } + } else if (mode & SKIP_LOG_FILES) { + if (mkpath(dest, S_IRWXU | S_IRWXG | S_IROTH | S_IXOTH)) { + perror(dest); + return 1; + } + //create empty file for skip log files. + FILE *f = fopen(dest, "a"); + if (f == NULL) { + fprintf(stderr, "create file %s for log file failed. error: %s\n", + dest, strerror(errno)); + return 1; + } + fclose(f); } return 0; } diff --git a/test/jdk/jdk/crac/AppendAppClassLoaderTest.java b/test/jdk/jdk/crac/AppendAppClassLoaderTest.java index bf1ff5c6f86..94800bcdc8d 100644 --- a/test/jdk/jdk/crac/AppendAppClassLoaderTest.java +++ b/test/jdk/jdk/crac/AppendAppClassLoaderTest.java @@ -1,3 +1,25 @@ +/* + * Copyright (c) 2024, Alibaba Group Holding Limited. 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. + */ import jdk.test.lib.crac.CracBuilder; import jdk.test.lib.crac.CracProcess; import jdk.test.lib.crac.CracTest; diff --git a/test/jdk/jdk/crac/AppendOnlyFileTest.java b/test/jdk/jdk/crac/AppendOnlyFileTest.java new file mode 100644 index 00000000000..17500d2cb8e --- /dev/null +++ b/test/jdk/jdk/crac/AppendOnlyFileTest.java @@ -0,0 +1,206 @@ +/* + * Copyright (c) 2024, Alibaba Group Holding Limited. 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. + */ +import static jdk.test.lib.Asserts.*; + +import jdk.test.lib.crac.CracBuilder; +import jdk.test.lib.crac.CracProcess; +import jdk.test.lib.crac.CracTest; +import jdk.test.lib.crac.CracTestArg; +import jdk.test.lib.util.FileUtils; + +import javax.crac.*; + +import java.io.BufferedWriter; +import java.io.File; +import java.io.FileWriter; +import java.io.IOException; +import java.io.PrintWriter; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.ArrayList; +import java.util.List; +import java.util.stream.Collectors; + +/** + * @test + * @library /test/lib + * @build AppendOnlyFileTest + * @summary Test C&R when open file with write&append mode that no need closed. + * @run driver/timeout=60 jdk.test.lib.crac.CracTest ALL KEEP_ALL + * @run driver/timeout=60 jdk.test.lib.crac.CracTest BY_EXT REMOVE_ALL + * @run driver/timeout=60 jdk.test.lib.crac.CracTest BY_FULL_PATH REMOVE_ONE_FILE + * @run driver/timeout=60 jdk.test.lib.crac.CracTest EXT_AND_FULL_PATH REMOVE_ONE_DIR + * + */ +public class AppendOnlyFileTest implements CracTest { + private static Path LOG_BASE; + private static List LOG_FILES = new ArrayList<>(); + private static String TEXT_BEFORE_CHECKPOINT = "text before checkpoint"; + private static String TEXT_AFTER_RESTORE = "text after restore"; + private static int DELETE_FILE_INDEX = 0; + private static int DELETE_DIR_INDEX = 2; + + static { + LOG_BASE = Path.of(System.getProperty("user.dir"), "testlogs"); + LOG_FILES.add(LOG_BASE.resolve("a.log")); + LOG_FILES.add(LOG_BASE.resolve("log1").resolve("b.msg")); + LOG_FILES.add(LOG_BASE.resolve("log2").resolve("c.txt")); + } + + private enum IgnoreAppendFileParamType { + ALL, + BY_EXT, + BY_FULL_PATH, + EXT_AND_FULL_PATH; + } + + private enum KeepFilesPolicy { + KEEP_ALL, + REMOVE_ALL, + REMOVE_ONE_FILE, + REMOVE_ONE_DIR + } + + private Resource resource; + + @CracTestArg(0) + IgnoreAppendFileParamType paramType; + + @CracTestArg(1) + KeepFilesPolicy keepFilesPolicy; + + @Override + public void test() throws Exception { + resetLogDir(); + + CracBuilder cracBuilder = new CracBuilder().printResources(true) + .appendOnlyFiles(getAppendOnlyParam(paramType)) + .captureOutput(true); + CracProcess crProcess = cracBuilder.startCheckpoint(); + int ret = crProcess.waitFor(); + if (ret != 137) { + crProcess.outputAnalyzer().reportDiagnosticSummary(); + assertEquals(137, ret, "Checkpointed process was not killed as expected."); + } + + keepFilesByPolicy(keepFilesPolicy); + cracBuilder.doRestore(); + validateFile(keepFilesPolicy); + } + + private static void resetLogDir() throws IOException { + if (LOG_BASE.toFile().exists()) { + FileUtils.deleteFileTreeWithRetry(LOG_BASE); + } + for (Path logFile : LOG_FILES) { + logFile.getParent().toFile().mkdirs(); + } + } + + @Override + public void exec() throws Exception { + List writers = LOG_FILES.stream().map((f) -> { + PrintWriter pw = openWithWriteAppendMode(f); + pw.println(TEXT_BEFORE_CHECKPOINT); + pw.flush(); + return pw; + }).collect(Collectors.toList()); + + Core.checkpointRestore(); + + writers.stream().forEach((pw) -> { + pw.println(TEXT_AFTER_RESTORE); + pw.flush(); + pw.close(); + }); + } + + private PrintWriter openWithWriteAppendMode(Path filePath) { + try { + return new PrintWriter(new BufferedWriter(new FileWriter(filePath.toFile(), true))); + } catch (IOException e) { + throw new RuntimeException(e); + } + } + + private void validateFile(KeepFilesPolicy keepFilesPolicy) throws IOException { + for (int i = 0; i < LOG_FILES.size(); i++) { + Path logFile = LOG_FILES.get(i); + assertTrue(logFile.toFile().exists()); + List lines = Files.lines(logFile).collect(Collectors.toList()); + + assertTrue(lines.stream().anyMatch((t) -> t.equals(TEXT_AFTER_RESTORE))); + + if (keepFilesPolicy == KeepFilesPolicy.KEEP_ALL) { + assertContainBeforeCheckpoint(true, lines); + } else if (keepFilesPolicy == KeepFilesPolicy.REMOVE_ONE_FILE) { + assertContainBeforeCheckpoint(i != DELETE_FILE_INDEX, lines); + } else if (keepFilesPolicy == KeepFilesPolicy.REMOVE_ALL) { + assertContainBeforeCheckpoint(false, lines); + } else if (keepFilesPolicy == KeepFilesPolicy.REMOVE_ONE_DIR) { + assertContainBeforeCheckpoint(i != DELETE_DIR_INDEX, lines); + } + } + } + + private void assertContainBeforeCheckpoint(boolean contain, List lines) { + if (contain) { + assertTrue(lines.stream().anyMatch((t) -> t.equals(TEXT_BEFORE_CHECKPOINT))); + } else { + assertFalse(lines.stream().anyMatch((t) -> t.equals(TEXT_BEFORE_CHECKPOINT))); + } + } + + private void keepFilesByPolicy(KeepFilesPolicy keepFilesPolicy) throws IOException { + if (keepFilesPolicy == KeepFilesPolicy.REMOVE_ALL) { + FileUtils.deleteFileTreeWithRetry(LOG_BASE); + } else if (keepFilesPolicy == KeepFilesPolicy.REMOVE_ONE_FILE) { + assertTrue(LOG_FILES.get(DELETE_FILE_INDEX).toFile().delete()); + } else if (keepFilesPolicy == KeepFilesPolicy.REMOVE_ONE_DIR) { + FileUtils.deleteFileTreeWithRetry(LOG_FILES.get(DELETE_DIR_INDEX)); + } + } + + private String getAppendOnlyParam(IgnoreAppendFileParamType paramType) { + switch (paramType) { + case ALL: + return "*"; + case BY_EXT: + return "*.log,*.txt,*.msg"; + case BY_FULL_PATH: + return LOG_FILES.stream().map((p) -> getCanonicalPath(p)).collect(Collectors.joining(",")); + case EXT_AND_FULL_PATH: + return "*.log,*.msg," + getCanonicalPath(LOG_FILES.get(LOG_FILES.size() - 1)); + default: + throw new RuntimeException("unknown IgnoreAppendFileParamType type : " + paramType); + } + } + + private String getCanonicalPath(Path path) { + try { + return path.toFile().getCanonicalPath(); + } catch (IOException e) { + throw new RuntimeException(e); + } + } +} diff --git a/test/jdk/jdk/crac/Foo.java b/test/jdk/jdk/crac/Foo.java index adc77e8facd..5bc7df62040 100644 --- a/test/jdk/jdk/crac/Foo.java +++ b/test/jdk/jdk/crac/Foo.java @@ -1,3 +1,25 @@ +/* + * Copyright (c) 2024, Alibaba Group Holding Limited. 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. + */ public class Foo { public void hello() { System.out.println("A msg from Foo#hello"); diff --git a/test/jdk/jdk/crac/PseudoPersistentFileTest.java b/test/jdk/jdk/crac/PseudoPersistentFileTest.java index 232ba4aa6f5..e125b3d2244 100644 --- a/test/jdk/jdk/crac/PseudoPersistentFileTest.java +++ b/test/jdk/jdk/crac/PseudoPersistentFileTest.java @@ -1,3 +1,25 @@ +/* + * Copyright (c) 2024, Alibaba Group Holding Limited. 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. + */ import jdk.test.lib.crac.CracBuilder; import jdk.test.lib.crac.CracProcess; import jdk.test.lib.crac.CracTest; diff --git a/test/jdk/jdk/crac/RestorePipeFdTest.java b/test/jdk/jdk/crac/RestorePipeFdTest.java index 99430965d41..49e720d7157 100644 --- a/test/jdk/jdk/crac/RestorePipeFdTest.java +++ b/test/jdk/jdk/crac/RestorePipeFdTest.java @@ -1,3 +1,25 @@ +/* + * Copyright (c) 2024, Alibaba Group Holding Limited. 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. + */ import jdk.crac.*; import jdk.test.lib.crac.CracBuilder; import jdk.test.lib.crac.CracProcess; diff --git a/test/jdk/jdk/crac/TestHello.java b/test/jdk/jdk/crac/TestHello.java index d6924d233fd..690361d8406 100644 --- a/test/jdk/jdk/crac/TestHello.java +++ b/test/jdk/jdk/crac/TestHello.java @@ -1,3 +1,25 @@ +/* + * Copyright (c) 2024, Alibaba Group Holding Limited. 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. + */ public class TestHello { public static void main(String[] args) { System.out.println("hello"); diff --git a/test/lib/jdk/test/lib/crac/CracBuilder.java b/test/lib/jdk/test/lib/crac/CracBuilder.java index aa60c8a5dae..95c91ff3c62 100644 --- a/test/lib/jdk/test/lib/crac/CracBuilder.java +++ b/test/lib/jdk/test/lib/crac/CracBuilder.java @@ -56,6 +56,8 @@ public class CracBuilder { boolean bumpPid; + String appendOnlyFilesParam; + static { String path = System.getenv("CRAC_CRIU_PATH"); if (path == null) { @@ -177,6 +179,12 @@ public CracBuilder dockerOptions(String... options) { return this; } + public CracBuilder appendOnlyFiles(String param) { + assertNull(appendOnlyFilesParam); + this.appendOnlyFilesParam = param; + return this; + } + public void doCheckpoint() throws Exception { startCheckpoint().waitForCheckpointed(); } @@ -453,6 +461,9 @@ private List prepareCommand(List javaPrefix) { if (restorePipeStdOutErr) { cmd.add("-XX:CRaCRestoreInheritPipeFds=1,2"); } + if (appendOnlyFilesParam != null) { + cmd.add("-XX:CRaCAppendOnlyLogFiles=" + appendOnlyFilesParam); + } return cmd; }