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
Show whitespace changes
Inline Side-by-side
src/java.base/share/man/java.1
+ 129
− 470
View file @ d6eb2818
.\" 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.
.\"
.\" This code is free software; you can redistribute it and/or modify it
......@@ -1078,8 +1078,10 @@ Require using shared class data, otherwise fail.
.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.
purposes only.
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.
.RE
.TP
......@@ -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.
.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.
Application Class Data Sharing (AppCDS) stores classes used by your
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
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
Classes in the CDS archive are stored in an optimized format that\[aq]s
about 2 to 5 times larger than classes stored in JAR files or the JDK
runtime image.
Therefore, it\[aq]s a good idea to archive only those classes that are
actually used by your application.
These usually are just a small portion of all available classes.
For example, your application may use only a few APIs provided by a
large library.
.SS Using CDS Archives
.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.
By default, in most JDK distributions, unless \f[CB]\-Xshare:off\f[R] is
specified, the JVM starts up with a default CDS archive, which is
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
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
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
\f[CB]\-XX:SharedArchiveFile=<static_archive>:<dynamic_archive>\f[R]
.RE
.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:
The \f[CB]<static_archive>\f[R] overrides the default CDS archive.
.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
The \f[CB]<dynamic_archive>\f[R] provides additional classes that can be
loaded on top of those in the \f[CB]<static_archive>\f[R].
.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.
On Windows, the above path delimiter \f[CB]:\f[R] should be replaced with
\f[CB];\f[R]
.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.
(The names "static" and "dyanmic" are used for historical reasons.
The only significance is that the "static" archive is loaded first and
the "dynamic" archive is loaded second).
.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:
The JVM can use up to two archives.
To use only a single \f[CB]<static_archive>\f[R], you can omit the
\f[CB]<dynamic_archive>\f[R] portion:
.RS
.PP
\f[CB]Preload\ Warning:\ Cannot\ find\f[R] \f[I]array_name\f[R]
\f[CB]\-XX:SharedArchiveFile=<static_archive>\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
For convenience, the \f[CB]<dynamic_archive>\f[R] records the location of
the \f[CB]<static_archive>\f[R].
Therefore, you can omit the \f[CB]<static_archive>\f[R] by saying only:
.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
\f[CB]\-XX:SharedArchiveFile=<dynamic_archive>\f[R]
.RE
.SS Creating CDS Archives
.PP
The following table describes how the VM options related to module paths
can be used along with the \f[CB]\-Xshare\f[R] option.
.PP
.TS
tab(@);
l l l.
T{
Option
T}@T{
\-Xshare:dump
T}@T{
\-Xshare:{on,auto}
T}
_
T{
\f[CB]\-\-module\-path\f[R][1] \f[I]mp\f[R]
T}@T{
Allowed
T}@T{
Allowed[2]
T}
T{
\f[CB]\-\-module\f[R]
T}@T{
Allowed
T}@T{
Allowed
T}
T{
\f[CB]\-\-add\-module\f[R]
T}@T{
Allowed
T}@T{
Allowed
T}
T{
\f[CB]\-\-upgrade\-module\-path\f[R][3]
T}@T{
Disallowed (exits if specified)
T}@T{
Allowed (disables CDS)
T}
T{
\f[CB]\-\-patch\-module\f[R][4]
T}@T{
Disallowed (exits if specified)
T}@T{
Allowed (disables CDS)
T}
T{
\f[CB]\-\-limit\-modules\f[R][5]
T}@T{
Disallowed (exits if specified)
T}@T{
Allowed (disables CDS)
T}
.TE
.PP
[1] Although there are two ways of specifying a module in a
\f[CB]\-\-module\-path\f[R], that is, modular JAR or exploded module, only
modular JARs are supported.
.PP
[2] Different \f[I]mp\f[R] can be specified during dump time versus run
time.
If an archived class K was loaded from \f[CB]mp1.jar\f[R] at dump time,
but changes in \f[I]mp\f[R] cause it to be available from a different
\f[CB]mp2.jar\f[R] at run time, then the archived version of K will be
disregarded at run time; K will be loaded dynamically.
.PP
[3] Currently, only two system modules are upgradeable
(\f[CB]java.compiler\f[R] and \f[CB]jdk.internal.vm.compiler\f[R]).
However, these modules are seldom upgraded in production software.
.PP
[4] As documented in JEP 261, using \f[CB]\-\-patch\-module\f[R] is
strongly discouraged for production use.
.PP
[5] \f[CB]\-\-limit\-modules\f[R] is intended for testing purposes.
It is seldom used in production software.
.PP
If \f[CB]\-\-upgrade\-module\-path\f[R], \f[CB]\-\-patch\-module\f[R], or
\f[CB]\-\-limit\-modules\f[R] is specified at dump time, an error will be
printed and the JVM will exit.
For example, if the \f[CB]\-\-limit\-modules\f[R] option is specified at
dump time, the user will see the following error:
.IP
.nf
\f[CB]
Error\ occurred\ during\ initialization\ of\ VM
Cannot\ use\ the\ following\ option\ when\ dumping\ the\ shared\ archive:\ \-\-limit\-modules
\f[R]
.fi
.PP
If \f[CB]\-\-upgrade\-module\-path\f[R], \f[CB]\-\-patch\-module\f[R], or
\f[CB]\-\-limit\-modules\f[R] is specified at run time, a warning message
will be printed indicating that CDS is disabled.
For example, if the \f[CB]\-\-limit\-modules\f[R] options is specified at
run time, the user will see the following warning:
.IP
.nf
\f[CB]
Java\ HotSpot(TM)\ 64\-Bit\ Server\ VM\ warning:\ CDS\ is\ disabled\ when\ the\ \-\-limit\-modules\ option\ is\ specified.
\f[R]
.fi
.PP
Several other noteworthy things include:
.IP \[bu] 2
Any valid combinations of \f[CB]\-cp\f[R] and \f[CB]\-\-module\-path\f[R]
are supported.
.IP \[bu] 2
A non\-empty directory in the module path causes a fatal error.
The user will see the following error messages:
.RS 2
.IP
.nf
\f[CB]
Error:\ non\-empty\ directory\ <directory>\ Hint:\ enable\ \-Xlog:class+path=info\ to\ diagnose\ the\ failure\ Error\ occurred\ during\ initialization\ of\ VM\ Cannot\ have\ non\-empty\ directory\ in\ paths
\f[R]
.fi
.RE
CDS archives can be created with several methods:
.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.
\f[CB]\-Xshare:dump\f[R]
.IP \[bu] 2
The archive is invalidated if an existing JAR in the module path is
updated after archive generation.
\f[CB]\-XX:ArchiveClassesAtExit\f[R]
.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.
\f[CB]jcmd\ VM.cds\f[R]
.PP
To create a dynamic CDS archive with the default CDS archive as the base
archive, just add the
\f[CB]\-XX:ArchiveClassesAtExit=<dynamic\ archive>\f[R] option to the
command line for running the Java application.
One common operation in all these methods is a "trial run", where you
run the application once to determine the classes that should be stored
in the archive.
.SS Creating a Static CDS Archive File with \-Xshare:dump
.PP
If the default CDS archive does not exist, the VM will exit with the
following error:
.IP
.nf
\f[CB]
ArchiveClassesAtExit\ not\ supported\ when\ base\ CDS\ archive\ is\ not\ loaded
\f[R]
.fi
.PP
To run the Java application using a dynamic CDS archive, just add the
\f[CB]\-XX:SharedArchiveFile=<dynamic\ archive>\f[R] option to the command
line for running the Java application.
.PP
The base archive is not required to be specified in the command line.
The base archive information, including its name and full path, will be
retrieved from the dynamic archive header.
Note that the user could also use the \f[CB]\-XX:SharedArchiveFile\f[R]
option for specifying a regular AppCDS archive.
Therefore, the specified archive in the \f[CB]\-XX:SharedArchiveFile\f[R]
option could be either a regular or dynamic archive.
During VM start up the specified archive header will be read.
If \f[CB]\-XX:SharedArchiveFile\f[R] refers to a regular archive, then the
behavior will be unchanged.
If \f[CB]\-XX:SharedArchiveFile\f[R] refers to a dynamic archive, the VM
will retrieve the base archive location from the dynamic archive.
If the dynamic archive was created with the default CDS archive, then
the current default CDS archive will be used, and will be found relative
to the current run time environment.
.PP
Please refer to \f[B]JDK\-8221706\f[R]
[https://bugs.openjdk.java.net/browse/JDK\-8221706] for details on error
checking during dynamic CDS archive dump time and run time.
.SS Creating a Shared Archive File and Using It to Run an Application
.SS AppCDS archive
.PP
The following steps create a shared archive file that contains all the
classes used by the \f[CB]test.Hello\f[R] application.
The last step runs the application with the shared archive file.
The following steps create a static CDS archive file that contains all
the classes used by the \f[CB]test.Hello\f[R] application.
.IP "1." 3
Create a list of all classes used by the \f[CB]test.Hello\f[R]
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]
.RE
.PP
Note that the classpath specified by the \f[CB]\-cp\f[R] parameter must
contain only JAR files.
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
Create a static 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
Run the application \f[CB]test.Hello\f[R] with the archive
\f[CB]hello.jsa\f[R]:
.RS 4
.RS
......@@ -5615,23 +5404,27 @@ 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]
\f[CB]java\ \-XX:SharedArchiveFile=hello.jsa\ \-cp\ hello.jar\ \-Xlog:class+load\ 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
.RS
.PP
\f[CB][info][class,load]\ test.Hello\ source:\ shared\ objects\ file\f[R]
.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
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.
classes that are used by the \f[CB]test.Hello\f[R] application, excluding
those that are already in the default 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
......@@ -5641,9 +5434,6 @@ all the classes in \f[CB]hello.jar\f[R] loaded by the application
.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
......@@ -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
\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:
It\[aq]s also possible to create a dynamic CDS archive with a
non\-default static CDS archive.
E.g.,
.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]:
To run the application using this dynamic CDS archive:
.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
(On Windows, the above path delimiter \f[CB]:\f[R] should be replaced with
\f[CB];\f[R])
.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]:
As mention above, the name of the static archive can be skipped:
.RS
.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
.SS Creating CDS Archive Files with jcmd
.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
The previous two sections require you to modify the application\[aq]s
start\-up script in order to create a CDS archive.
Sometimes this could be difficult, for example, if the application\[aq]s
class path is set up by complex routines.
.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
The \f[CB]jcmd\ VM.cds\f[R] command provides a less intrusive way for
creating a CDS archive by connecting to a running JVM process.
You can create either a static:
.RS
.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
.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
or a dynamic archive:
.RS
.PP
\f[CB]java\ \-XX:SharedArchiveFile=common.jsa\ \-cp\ common.jar:hello.jar:hi.jar\ Hi\f[R]
.RE
\f[CB]jcmd\ <pid>\ VM.cds\ dynamic_dump\ my_dynamic_archive.jsa\f[R]
.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.
To use the resulting archive file in a subsequent run of the application
without modifying the application\[aq]s start\-up script, you can use
the following technique:
.RS
.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
.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]:
Note: to use \f[CB]jcmd\ <pid>\ VM.cds\ dynamic_dump\f[R], the JVM process
identified by \f[CB]<pid>\f[R] must be started with
\f[CB]\-XX:+RecordDynamicDumpInfo\f[R], which can also be passed to the
application start\-up script with the same technique:
.RS
.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
.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] .
.SS Restrictions on Class Path and Module Path
.IP \[bu] 2
Neither the class path (\f[CB]\-classpath\f[R] and
\f[CB]\-Xbootclasspath/a\f[R]) nor the module path
(\f[CB]\-\-module\-path\f[R]) can contain non\-empty directories.
.IP \[bu] 2
Only modular JAR files are supported in \f[CB]\-\-module\-path\f[R].
Exploded modules are not supported.
.IP \[bu] 2
The class path used at archive creation time must be the same as (or a
prefix of) the class path used at run time.
(There\[aq]s no such requirement for the module path.)
.IP \[bu] 2
The CDS archive cannot be loaded if any JAR files in the class path or
module path are modified after the archive is generated.
.IP \[bu] 2
If any of the VM options \f[CB]\-\-upgrade\-module\-path\f[R],
\f[CB]\-\-patch\-module\f[R] or \f[CB]\-\-limit\-modules\f[R] are specified,
CDS is disabled.
This means that the JVM will execute without loading any CDS archives.
In addition, if you try to create a CDS archive with any of these 3
options specified, the JVM will report an error.
.SH PERFORMANCE TUNING EXAMPLES
.PP
You can use the Java advanced runtime options to optimize the
......
src/jdk.jcmd/share/man/jcmd.1
+ 51
− 1
View file @ d6eb2818
.\" 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.
.\"
.\" 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
(BOOLEAN, false)
.RE
.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]
Prints statistics about all ClassLoaders.
.RS
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment

AEI Privacy Policy Imprint