Skip to content
Snippets Groups Projects
Commit d6eb2818 authored by Thomas Stuefe's avatar Thomas Stuefe
Browse files

8280543: Update the "java" and "jcmd" tool specification for CDS

Reviewed-by: mdoerr
Backport-of: 39165613aa0430861e361a33a4925b85ea24fff1
parent d19ec6f8
No related branches found
No related tags found
No related merge requests found
.\" Copyright (c) 1994, 2021, Oracle and/or its affiliates. All rights reserved. .\" Copyright (c) 1994, 2022, Oracle and/or its affiliates. All rights reserved.
.\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. .\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
.\" .\"
.\" This code is free software; you can redistribute it and/or modify it .\" This code is free software; you can redistribute it and/or modify it
...@@ -1078,8 +1078,10 @@ Require using shared class data, otherwise fail. ...@@ -1078,8 +1078,10 @@ Require using shared class data, otherwise fail.
.RS .RS
.PP .PP
\f[B]Note:\f[R] The \f[CB]\-Xshare:on\f[R] option is used for testing \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 purposes only.
address space layout randomization by the operation system. It may cause the VM to unexpectedly exit during start\-up when the CDS
archive cannot be used (for example, when certain VM parameters are
changed, or when a different JDK is used).
This option should not be used in production environments. This option should not be used in production environments.
.RE .RE
.TP .TP
...@@ -5287,293 +5289,83 @@ who\[aq]s running the application, because administrators by default ...@@ -5287,293 +5289,83 @@ who\[aq]s running the application, because administrators by default
don\[aq]t have the privilege to lock pages in memory. don\[aq]t have the privilege to lock pages in memory.
.SH APPLICATION CLASS DATA SHARING .SH APPLICATION CLASS DATA SHARING
.PP .PP
Application Class Data Sharing (AppCDS) extends class data sharing (CDS) Application Class Data Sharing (AppCDS) stores classes used by your
to enable application classes to be placed in a shared archive. applications in an archive file.
Since these classes are stored in a format that can be loaded very
quickly (compared to classes stored in a JAR file), AppCDS can improve
the start\-up time of your applications.
In addition, AppCDS can reduce the runtime memory footprint by sharing
parts of these classes across multiple processes.
.PP .PP
In addition to the core library classes, AppCDS supports \f[B]Class Data Classes in the CDS archive are stored in an optimized format that\[aq]s
Sharing\f[R] about 2 to 5 times larger than classes stored in JAR files or the JDK
[https://docs.oracle.com/en/java/javase/12/vm/class\-data\-sharing.html#GUID\-7EAA3411\-8CF0\-4D19\-BD05\-DF5E1780AA91] runtime image.
from the following locations: Therefore, it\[aq]s a good idea to archive only those classes that are
.IP \[bu] 2 actually used by your application.
Platform classes from the runtime image These usually are just a small portion of all available classes.
.IP \[bu] 2 For example, your application may use only a few APIs provided by a
Application classes from the runtime image large library.
.IP \[bu] 2 .SS Using CDS Archives
Application classes from the class path
.IP \[bu] 2
Application classes from the module path
.PP .PP
Archiving application classes provides better start up time at runtime. By default, in most JDK distributions, unless \f[CB]\-Xshare:off\f[R] is
When running multiple JVM processes, AppCDS also reduces the runtime specified, the JVM starts up with a default CDS archive, which is
footprint with memory sharing for read\-only metadata. usually located in \f[CB]JAVA_HOME/lib/server/classes.jsa\f[R] (or
\f[CB]JAVA_HOME\\bin\\server\\classes.jsa\f[R] on Windows).
This archive contains about 1300 core library classes that are used by
most applications.
.PP .PP
CDS/AppCDS supports archiving classes from JAR files only. To use CDS for the exact set of classes used by your application, you
can use the \f[CB]\-XX:SharedArchiveFile\f[R] option, which has the
general form:
.RS
.PP .PP
Prior to JDK 11, a non\-empty directory was reported as a fatal error in \f[CB]\-XX:SharedArchiveFile=<static_archive>:<dynamic_archive>\f[R]
the following conditions: .RE
.IP \[bu] 2
For base CDS, a non\-empty directory cannot exist in the
\f[CB]\-Xbootclasspath/a\f[R] path
.IP \[bu] 2 .IP \[bu] 2
With \f[CB]\-XX:+UseAppCDS\f[R], a non\-empty directory could not exist in The \f[CB]<static_archive>\f[R] overrides the default CDS archive.
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 .IP \[bu] 2
If application classes or platform classes are not loaded, dump time The \f[CB]<dynamic_archive>\f[R] provides additional classes that can be
only reports an error if a non\-empty directory exists in loaded on top of those in the \f[CB]<static_archive>\f[R].
\f[CB]\-Xbootclasspath/a\f[R] path
.IP \[bu] 2 .IP \[bu] 2
If application classes or platform classes are loaded, dump time reports On Windows, the above path delimiter \f[CB]:\f[R] should be replaced with
an error for a non\-empty directory that exists in \f[CB];\f[R]
\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 .PP
In JDK 11 and later, because \f[CB]UseAppCDS\f[R] is obsolete, (The names "static" and "dyanmic" are used for historical reasons.
\f[CB]SharedArchiveFile\f[R] becomes a product flag by default. The only significance is that the "static" archive is loaded first and
Specifying \f[CB]+UnlockDiagnosticVMOptions\f[R] for the "dynamic" archive is loaded second).
\f[CB]SharedArchiveFile\f[R] is no longer needed in any configuration.
.PP .PP
Class Data Sharing (CDS)/AppCDS does not support archiving array classes The JVM can use up to two archives.
in a class list. To use only a single \f[CB]<static_archive>\f[R], you can omit the
When an array in the class list is encountered, CDS dump time gives the \f[CB]<dynamic_archive>\f[R] portion:
explicit error message:
.RS .RS
.PP .PP
\f[CB]Preload\ Warning:\ Cannot\ find\f[R] \f[I]array_name\f[R] \f[CB]\-XX:SharedArchiveFile=<static_archive>\f[R]
.RE .RE
.PP .PP
Although an array in the class list is not allowed, some array classes For convenience, the \f[CB]<dynamic_archive>\f[R] records the location of
can still be created at CDS/AppCDS dump time. the \f[CB]<static_archive>\f[R].
Those arrays are created during the execution of the Java code used by Therefore, you can omit the \f[CB]<static_archive>\f[R] by saying only:
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 .RS
.PP .PP
\f[CB]java\ \-XX:SharedArchiveFile=\f[R]\f[I]shared_archive_file\f[R] \f[CB]\-XX:SharedArchiveFile=<dynamic_archive>\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 .RE
.SS Creating CDS Archives
.PP .PP
The following table describes how the VM options related to module paths CDS archives can be created with several methods:
can be used along with the \f[CB]\-Xshare\f[R] option.
.PP
.TS
tab(@);
l l l.
T{
Option
T}@T{
\-Xshare:dump
T}@T{
\-Xshare:{on,auto}
T}
_
T{
\f[CB]\-\-module\-path\f[R][1] \f[I]mp\f[R]
T}@T{
Allowed
T}@T{
Allowed[2]
T}
T{
\f[CB]\-\-module\f[R]
T}@T{
Allowed
T}@T{
Allowed
T}
T{
\f[CB]\-\-add\-module\f[R]
T}@T{
Allowed
T}@T{
Allowed
T}
T{
\f[CB]\-\-upgrade\-module\-path\f[R][3]
T}@T{
Disallowed (exits if specified)
T}@T{
Allowed (disables CDS)
T}
T{
\f[CB]\-\-patch\-module\f[R][4]
T}@T{
Disallowed (exits if specified)
T}@T{
Allowed (disables CDS)
T}
T{
\f[CB]\-\-limit\-modules\f[R][5]
T}@T{
Disallowed (exits if specified)
T}@T{
Allowed (disables CDS)
T}
.TE
.PP
[1] Although there are two ways of specifying a module in a
\f[CB]\-\-module\-path\f[R], that is, modular JAR or exploded module, only
modular JARs are supported.
.PP
[2] Different \f[I]mp\f[R] can be specified during dump time versus run
time.
If an archived class K was loaded from \f[CB]mp1.jar\f[R] at dump time,
but changes in \f[I]mp\f[R] cause it to be available from a different
\f[CB]mp2.jar\f[R] at run time, then the archived version of K will be
disregarded at run time; K will be loaded dynamically.
.PP
[3] Currently, only two system modules are upgradeable
(\f[CB]java.compiler\f[R] and \f[CB]jdk.internal.vm.compiler\f[R]).
However, these modules are seldom upgraded in production software.
.PP
[4] As documented in JEP 261, using \f[CB]\-\-patch\-module\f[R] is
strongly discouraged for production use.
.PP
[5] \f[CB]\-\-limit\-modules\f[R] is intended for testing purposes.
It is seldom used in production software.
.PP
If \f[CB]\-\-upgrade\-module\-path\f[R], \f[CB]\-\-patch\-module\f[R], or
\f[CB]\-\-limit\-modules\f[R] is specified at dump time, an error will be
printed and the JVM will exit.
For example, if the \f[CB]\-\-limit\-modules\f[R] option is specified at
dump time, the user will see the following error:
.IP
.nf
\f[CB]
Error\ occurred\ during\ initialization\ of\ VM
Cannot\ use\ the\ following\ option\ when\ dumping\ the\ shared\ archive:\ \-\-limit\-modules
\f[R]
.fi
.PP
If \f[CB]\-\-upgrade\-module\-path\f[R], \f[CB]\-\-patch\-module\f[R], or
\f[CB]\-\-limit\-modules\f[R] is specified at run time, a warning message
will be printed indicating that CDS is disabled.
For example, if the \f[CB]\-\-limit\-modules\f[R] options is specified at
run time, the user will see the following warning:
.IP
.nf
\f[CB]
Java\ HotSpot(TM)\ 64\-Bit\ Server\ VM\ warning:\ CDS\ is\ disabled\ when\ the\ \-\-limit\-modules\ option\ is\ specified.
\f[R]
.fi
.PP
Several other noteworthy things include:
.IP \[bu] 2
Any valid combinations of \f[CB]\-cp\f[R] and \f[CB]\-\-module\-path\f[R]
are supported.
.IP \[bu] 2
A non\-empty directory in the module path causes a fatal error.
The user will see the following error messages:
.RS 2
.IP
.nf
\f[CB]
Error:\ non\-empty\ directory\ <directory>\ Hint:\ enable\ \-Xlog:class+path=info\ to\ diagnose\ the\ failure\ Error\ occurred\ during\ initialization\ of\ VM\ Cannot\ have\ non\-empty\ directory\ in\ paths
\f[R]
.fi
.RE
.IP \[bu] 2 .IP \[bu] 2
Unlike the class path, there\[aq]s no restriction that the module path \f[CB]\-Xshare:dump\f[R]
at dump time must be equal to or be a prefix of the module path at run
time.
.IP \[bu] 2 .IP \[bu] 2
The archive is invalidated if an existing JAR in the module path is \f[CB]\-XX:ArchiveClassesAtExit\f[R]
updated after archive generation.
.IP \[bu] 2 .IP \[bu] 2
Removing a JAR from the module path does not invalidate the shared \f[CB]jcmd\ VM.cds\f[R]
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 .PP
To create a dynamic CDS archive with the default CDS archive as the base One common operation in all these methods is a "trial run", where you
archive, just add the run the application once to determine the classes that should be stored
\f[CB]\-XX:ArchiveClassesAtExit=<dynamic\ archive>\f[R] option to the in the archive.
command line for running the Java application. .SS Creating a Static CDS Archive File with \-Xshare:dump
.PP .PP
If the default CDS archive does not exist, the VM will exit with the The following steps create a static CDS archive file that contains all
following error: the classes used by the \f[CB]test.Hello\f[R] application.
.IP
.nf
\f[CB]
ArchiveClassesAtExit\ not\ supported\ when\ base\ CDS\ archive\ is\ not\ loaded
\f[R]
.fi
.PP
To run the Java application using a dynamic CDS archive, just add the
\f[CB]\-XX:SharedArchiveFile=<dynamic\ archive>\f[R] option to the command
line for running the Java application.
.PP
The base archive is not required to be specified in the command line.
The base archive information, including its name and full path, will be
retrieved from the dynamic archive header.
Note that the user could also use the \f[CB]\-XX:SharedArchiveFile\f[R]
option for specifying a regular AppCDS archive.
Therefore, the specified archive in the \f[CB]\-XX:SharedArchiveFile\f[R]
option could be either a regular or dynamic archive.
During VM start up the specified archive header will be read.
If \f[CB]\-XX:SharedArchiveFile\f[R] refers to a regular archive, then the
behavior will be unchanged.
If \f[CB]\-XX:SharedArchiveFile\f[R] refers to a dynamic archive, the VM
will retrieve the base archive location from the dynamic archive.
If the dynamic archive was created with the default CDS archive, then
the current default CDS archive will be used, and will be found relative
to the current run time environment.
.PP
Please refer to \f[B]JDK\-8221706\f[R]
[https://bugs.openjdk.java.net/browse/JDK\-8221706] for details on error
checking during dynamic CDS archive dump time and run time.
.SS Creating a Shared Archive File and Using It to Run an Application
.SS AppCDS archive
.PP
The following steps create a shared archive file that contains all the
classes used by the \f[CB]test.Hello\f[R] application.
The last step runs the application with the shared archive file.
.IP "1." 3 .IP "1." 3
Create a list of all classes used by the \f[CB]test.Hello\f[R] Create a list of all classes used by the \f[CB]test.Hello\f[R]
application. application.
...@@ -5585,23 +5377,20 @@ contains a list of all classes used by this application: ...@@ -5585,23 +5377,20 @@ contains a list of all classes used by this application:
\f[CB]java\ \-Xshare:off\ \-XX:DumpLoadedClassList=hello.classlist\ \-cp\ hello.jar\ test.Hello\f[R] \f[CB]java\ \-Xshare:off\ \-XX:DumpLoadedClassList=hello.classlist\ \-cp\ hello.jar\ test.Hello\f[R]
.RE .RE
.PP .PP
Note that the classpath specified by the \f[CB]\-cp\f[R] parameter must The classpath specified by the \f[CB]\-cp\f[R] parameter must contain only
contain only JAR files. JAR files.
.RE .RE
.IP "2." 3 .IP "2." 3
Create a shared archive, named \f[CB]hello.jsa\f[R], that contains all the Create a static archive, named \f[CB]hello.jsa\f[R], that contains all the
classes in \f[CB]hello.classlist\f[R]: classes in \f[CB]hello.classlist\f[R]:
.RS 4 .RS 4
.RS .RS
.PP .PP
\f[CB]java\ \-Xshare:dump\ \-XX:SharedArchiveFile=hello.jsa\ \-XX:SharedClassListFile=hello.classlist\ \-cp\ hello.jar\f[R] \f[CB]java\ \-Xshare:dump\ \-XX:SharedArchiveFile=hello.jsa\ \-XX:SharedClassListFile=hello.classlist\ \-cp\ hello.jar\f[R]
.RE .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 .RE
.IP "3." 3 .IP "3." 3
Run the application \f[CB]test.Hello\f[R] with the shared archive Run the application \f[CB]test.Hello\f[R] with the archive
\f[CB]hello.jsa\f[R]: \f[CB]hello.jsa\f[R]:
.RS 4 .RS 4
.RS .RS
...@@ -5615,23 +5404,27 @@ using the class contained in the \f[CB]hello.jsa\f[R] shared archive: ...@@ -5615,23 +5404,27 @@ using the class contained in the \f[CB]hello.jsa\f[R] shared archive:
.RS 4 .RS 4
.RS .RS
.PP .PP
\f[CB]java\ \-XX:SharedArchiveFile=hello.jsa\ \-cp\ hello.jar\ \-verbose:class\ test.Hello\f[R] \f[CB]java\ \-XX:SharedArchiveFile=hello.jsa\ \-cp\ hello.jar\ \-Xlog:class+load\ test.Hello\f[R]
.RE .RE
.PP .PP
The output of this command should contain the following text: The output of this command should contain the following text:
.IP .RS
.nf .PP
\f[CB] \f[CB][info][class,load]\ test.Hello\ source:\ shared\ objects\ file\f[R]
Loaded\ test.Hello\ from\ shared\ objects\ file\ by\ sun/misc/Launcher$AppClassLoader .RE
\f[R]
.fi
.RE .RE
.SS Dynamic CDS archive .SS Creating a Dynamic CDS Archive File with \-XX:SharedArchiveFile
.PP
Advantages of dynamic CDS archives are:
.IP \[bu] 2
They usually use less disk space, since they don\[aq]t need to store the
classes that are already in the static archive.
.IP \[bu] 2
They are created with one fewer step than the comparable static archive.
.PP .PP
The following steps create a dynamic CDS archive file that contains the 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 classes that are used by the \f[CB]test.Hello\f[R] application, excluding
in the default CDS archive. those that are already in the default CDS archive.
The second step runs the application with the dynamic CDS archive.
.IP "1." 3 .IP "1." 3
Create a dynamic CDS archive, named \f[CB]hello.jsa\f[R], that contains 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 all the classes in \f[CB]hello.jar\f[R] loaded by the application
...@@ -5641,9 +5434,6 @@ all the classes in \f[CB]hello.jar\f[R] loaded by the application ...@@ -5641,9 +5434,6 @@ all the classes in \f[CB]hello.jar\f[R] loaded by the application
.PP .PP
\f[CB]java\ \-XX:ArchiveClassesAtExit=hello.jsa\ \-cp\ hello.jar\ Hello\f[R] \f[CB]java\ \-XX:ArchiveClassesAtExit=hello.jsa\ \-cp\ hello.jar\ Hello\f[R]
.RE .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 .RE
.IP "2." 3 .IP "2." 3
Run the application \f[CB]test.Hello\f[R] with the shared archive Run the application \f[CB]test.Hello\f[R] with the shared archive
...@@ -5659,218 +5449,87 @@ Run the application \f[CB]test.Hello\f[R] with the shared archive ...@@ -5659,218 +5449,87 @@ Run the application \f[CB]test.Hello\f[R] with the shared archive
the \f[CB]test.Hello\f[R] application is using the class contained in the the \f[CB]test.Hello\f[R] application is using the class contained in the
\f[CB]hello.jsa\f[R] shared archive. \f[CB]hello.jsa\f[R] shared archive.
.PP .PP
To automate the above steps 1 and 2, one can write a script such as the It\[aq]s also possible to create a dynamic CDS archive with a
following: non\-default static CDS archive.
.IP E.g.,
.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 .RS
.PP .PP
\f[CB]java\ \-XX:SharedArchiveFile=base.jsa\ \-XX:ArchiveClassesAtExit=hello.jsa\ \-cp\ hello.jar\ Hello\f[R] \f[CB]java\ \-XX:SharedArchiveFile=base.jsa\ \-XX:ArchiveClassesAtExit=hello.jsa\ \-cp\ hello.jar\ Hello\f[R]
.RE .RE
.PP .PP
To run the application using the dynamic CDS archive \f[CB]hello.jsa\f[R] To run the application using this dynamic CDS archive:
and a specific base CDS archive \f[CB]base.jsa\f[R]:
.RS .RS
.PP .PP
\f[CB]java\ \-XX:SharedArchiveFile=base.jsa:hello.jsa\ \-cp\ hello.jar\ Hello\f[R] \f[CB]java\ \-XX:SharedArchiveFile=base.jsa:hello.jsa\ \-cp\ hello.jar\ Hello\f[R]
.RE .RE
.PP .PP
Note that on Windows, the above path delimiter \f[CB]:\f[R] should be (On Windows, the above path delimiter \f[CB]:\f[R] should be replaced with
replaced with \f[CB];\f[R]. \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 .PP
\f[B]Linux and macOS\f[R] The following commands combine the files As mention above, the name of the static archive can be skipped:
\f[CB]hello.classlist\f[R] and \f[CB]hi.classlist\f[R] into one file,
\f[CB]common.classlist\f[R]:
.RS .RS
.PP .PP
\f[CB]cat\ hello.classlist\ hi.classlist\ >\ common.classlist\f[R] \f[CB]java\ \-XX:SharedArchiveFile=hello.jsa\ \-cp\ hello.jar\ Hello\f[R]
.RE .RE
.SS Creating CDS Archive Files with jcmd
.PP .PP
\f[B]Windows\f[R] The following commands combine the files The previous two sections require you to modify the application\[aq]s
\f[CB]hello.classlist\f[R] and \f[CB]hi.classlist\f[R] into one file, start\-up script in order to create a CDS archive.
\f[CB]common.classlist\f[R]: Sometimes this could be difficult, for example, if the application\[aq]s
.RS class path is set up by complex routines.
.PP .PP
\f[CB]type\ hello.classlist\ hi.classlist\ >\ common.classlist\f[R] The \f[CB]jcmd\ VM.cds\f[R] command provides a less intrusive way for
.RE creating a CDS archive by connecting to a running JVM process.
.RE You can create either a static:
.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 .RS
.PP .PP
\f[CB]java\ \-Xshare:dump\ \-XX:SharedArchiveFile=common.jsa\ \-XX:SharedClassListFile=common.classlist\ \-cp\ common.jar:hello.jar:hi.jar\f[R] \f[CB]jcmd\ <pid>\ VM.cds\ static_dump\ my_static_archive.jsa\f[R]
.RE .RE
.PP .PP
The classpath parameter used is the common class path prefix shared by or a dynamic archive:
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 .RS
.PP .PP
\f[CB]java\ \-XX:SharedArchiveFile=common.jsa\ \-cp\ common.jar:hello.jar:hi.jar\ Hi\f[R] \f[CB]jcmd\ <pid>\ VM.cds\ dynamic_dump\ my_dynamic_archive.jsa\f[R]
.RE
.RE .RE
.SS Specifying Additional Shared Data Added to an Archive File
.PP .PP
The \f[CB]SharedArchiveConfigFile\f[R] option is used to specify To use the resulting archive file in a subsequent run of the application
additional shared data to add to the archive file. without modifying the application\[aq]s start\-up script, you can use
the following technique:
.RS .RS
.PP .PP
\f[CB]\-XX:SharedArchiveConfigFile=\f[R]\f[I]shared_config_file\f[R] \f[CB]env\ JAVA_TOOL_OPTIONS=\-XX:SharedArchiveFile=my_static_archive.jsa\ bash\ app_start.sh\f[R]
.RE .RE
.PP .PP
JDK 9 and later supports adding both symbols and string objects to an Note: to use \f[CB]jcmd\ <pid>\ VM.cds\ dynamic_dump\f[R], the JVM process
archive for memory sharing when you have multiple JVM processes running identified by \f[CB]<pid>\f[R] must be started with
on the same host. \f[CB]\-XX:+RecordDynamicDumpInfo\f[R], which can also be passed to the
An example of this is having multiple JVM processes that use the same application start\-up script with the same technique:
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 .RS
.PP .PP
\f[CB]jcmd\f[R] \f[I]pid\f[R] \f[CB]VM.symboltable\ \-verbose\f[R] \f[CB]env\ JAVA_TOOL_OPTIONS=\-XX:+RecordDynamicDumpInfo\ bash\ app_start.sh\f[R]
.RE .RE
.RS .SS Restrictions on Class Path and Module Path
.PP .IP \[bu] 2
\f[B]Note:\f[R] The first line (process ID) and the second line Neither the class path (\f[CB]\-classpath\f[R] and
(\f[CB]\@VERSION\ ...\f[R]) of this \f[CB]jcmd\f[R] output should be \f[CB]\-Xbootclasspath/a\f[R]) nor the module path
excluded from the configuration file. (\f[CB]\-\-module\-path\f[R]) can contain non\-empty directories.
.RE .IP \[bu] 2
.SS Example of a Configuration File Only modular JAR files are supported in \f[CB]\-\-module\-path\f[R].
.PP Exploded modules are not supported.
The following is an example of a configuration file: .IP \[bu] 2
.IP The class path used at archive creation time must be the same as (or a
.nf prefix of) the class path used at run time.
\f[CB] (There\[aq]s no such requirement for the module path.)
VERSION:\ 1.0 .IP \[bu] 2
\@SECTION:\ Symbol The CDS archive cannot be loaded if any JAR files in the class path or
10\ \-1:\ linkMethod module path are modified after the archive is generated.
\f[R] .IP \[bu] 2
.fi If any of the VM options \f[CB]\-\-upgrade\-module\-path\f[R],
.PP \f[CB]\-\-patch\-module\f[R] or \f[CB]\-\-limit\-modules\f[R] are specified,
In the configuration file example, the \f[CB]\@SECTION:\ Symbol\f[R] entry CDS is disabled.
uses the following format: This means that the JVM will execute without loading any CDS archives.
.RS In addition, if you try to create a CDS archive with any of these 3
.PP options specified, the JVM will report an error.
\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 .SH PERFORMANCE TUNING EXAMPLES
.PP .PP
You can use the Java advanced runtime options to optimize the You can use the Java advanced runtime options to optimize the
......
.\" Copyright (c) 2012, 2020, Oracle and/or its affiliates. All rights reserved. .\" Copyright (c) 2012, 2022, Oracle and/or its affiliates. All rights reserved.
.\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. .\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
.\" .\"
.\" This code is free software; you can redistribute it and/or modify it .\" This code is free software; you can redistribute it and/or modify it
...@@ -764,6 +764,56 @@ The following \f[I]options\f[R] must be specified using either ...@@ -764,6 +764,56 @@ The following \f[I]options\f[R] must be specified using either
(BOOLEAN, false) (BOOLEAN, false)
.RE .RE
.TP .TP
.B \f[CB]VM.cds\f[R] [\f[I]arguments\f[R]]
Dumps a static or dynamic shared archive that includes all currently
loaded classes.
.RS
.PP
Impact: Medium \-\-\- pause time depends on number of loaded classes
.PP
Permission: \f[CB]java.lang.management.ManagementPermission(monitor)\f[R]
.PP
\f[I]arguments\f[R]:
.IP \[bu] 2
\f[CB]subcmd\f[R]: must be either \f[CB]static_dump\f[R] or
.IP \[bu] 2
\f[CB]filename\f[R]: (Optional) Name of the shared archive to be dumped
(STRING, no default value)
.PP
If \f[CB]filename\f[R] is not specified, a default file name is chosen
using the pid of the target JVM process.
For example, java_pid1234_static.jsa, java_pid5678_dynamic.jsa, etc.
.PP
If \f[CB]filename\f[R] is not specified as an absolute path, the archive
file is created in a directory relative to the current directory of the
target JVM process.
.RE
.TP
.B \f[CB]VM.classloaders\f[R] [\f[I]options\f[R]]
Prints classloader hierarchy.
.RS
.PP
Impact: Medium \-\-\- Depends on number of class loaders and classes
loaded.
.PP
Permission: \f[CB]java.lang.management.ManagementPermission(monitor)\f[R]
.PP
The following \f[I]options\f[R] must be specified using either
\f[I]key\f[R] or \f[I]key\f[R]\f[CB]=\f[R]\f[I]value\f[R] syntax.
.PP
\f[I]options\f[R]:
.IP \[bu] 2
\f[CB]show\-classes\f[R]: (Optional) Print loaded classes.
(BOOLEAN, false)
.IP \[bu] 2
\f[CB]verbose\f[R]: (Optional) Print detailed information.
(BOOLEAN, false)
.IP \[bu] 2
\f[CB]fold\f[R]: (Optional) Show loaders of the same name and class as
one.
(BOOLEAN, true)
.RE
.TP
.B \f[CB]VM.classloader_stats\f[R] .B \f[CB]VM.classloader_stats\f[R]
Prints statistics about all ClassLoaders. Prints statistics about all ClassLoaders.
.RS .RS
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment