7.13.3 Controlling application target of the Explicit Memory Management functionality by using a configuration file
If objects in the Java heap are referenced from objects in Explicit memory blocks generated by the automatic placement functionality, the objects in the Java heap are moved to the Explicit heap based on reference relations when GC occurs. The functionality for specifying classes to be excluded from the application of the Explicit Memory Management functionality excludes the objects, which are to be moved on the basis of this reference relation, from application target of the Explicit Memory Management functionality by using a configuration file and does not let the objects move to Explicit heap. You can use this functionality to exclude objects that are not reclaimed even by Full GC, such as objects used until the application stops, from the targets of the Explicit Memory Management functionality. For details on the movement based on reference relation of objects, see 7.6.5 Moving the objects from the Java heap to the Explicit memory block based on a reference relation.
- Organization of this subsection
(1) Types of configuration files
The following two types of files are used in the functionality for specifying classes to be excluded from the application of the Explicit Memory Management functionality:
-
Configuration file for Explicit Memory Management functionality application exclusion
Specify classes of the objects, which you do not want to move to an Explicit heap. The objects of the classes specified in this file do not move to the Explicit heap when GC occurs. The objects move to Tenured area at the time of rising.
A configuration file for Explicit Memory Management functionality application exclusion contains files provided by the system. If you enable the functionality for specifying classes to be excluded from the application of the Explicit Memory Management functionality, the configuration file for Explicit Memory Management functionality application exclusion provided by the system is used. The following is the file path of the configuration file for Explicit Memory Management functionality application exclusion, which is provided by the system:
- In Windows
-
JDK-installation-directory\lib\explicitmemory\sysexmemexcludeclass1100.cfg
- In UNIX
-
/opt/Cosminexus/jdk/lib/explicitmemory/sysexmemexcludeclass1100.cfg
If you want to add classes for exclusion from application target of the Explicit Memory Management functionality, update the file in the following file path or create a new file:
- In Windows
-
JDK-installation-directory\usrconf\exmemexcludeclass.cfg
- In UNIX
-
/opt/Cosminexus/jdk/usrconf/exmemexcludeclass.cfg
If you create a new configuration file for Explicit Memory Management functionality application exclusion, specify the file path in -XX:ExplicitMemoryExcludeClassListFile option.
-
Configuration file for disabling application exclusion of the Explicit Memory Management functionality
Specify the classes, for which the settings of application exclusion are to be disabled, from among the classes specified in the configuration file for Explicit Memory Management functionality application exclusion. The objects of the classes specified in this file move to the Explicit heap when GC occurs.
If you want to disable the classes excluded from application target of the Explicit Memory Management functionality, update the file in the file path given below or create a new file. You can also disable settings of the classes specified in the configuration file for Explicit Memory Management functionality application exclusion, which is provided by the system.
- In Windows
-
JDK-installation-directory\usrconf\exmemnotexcludeclass.cfg
- In UNIX
-
/opt/Cosminexus/jdk/usrconf/exmemnotexcludeclass.cfg
If you create a new configuration file for disabling application exclusion of the Explicit Memory Management functionality, specify file path in -XX:ExplicitMemoryNotExcludeClassListFile option.
(2) Specifying configuration file and scope of application of the Explicit Memory Management functionality
Priority is given to specification of configuration file for disabling application exclusion of the Explicit Memory Management functionality than the specification of configuration file for Explicit Memory Management functionality application exclusion.
This subsection describes specification of configuration file and scope of application of the Explicit Memory Management functionality considering com.sample package as an example. com.sample package contains two classes - ClassA and ClassB. Specify each configuration file as shown below.
-
Example of specifying a configuration file for Explicit Memory Management functionality application exclusion
com.sample.*
-
Example of specifying a configuration file for disabling application exclusion of the Explicit Memory Management functionality
com.sample.ClassB
Both ClassA and ClassB are included in specification of the configuration file for Explicit Memory Management functionality application exclusion. However, because specification of the configuration file for disabling application exclusion of the Explicit Memory Management functionality is preferred, only ClassA is excluded from the application of the Explicit Memory Management functionality and Explicit Memory Management functionality is applied to ClassB, as shown in the following figure.
(3) Format for coding a configuration file
The following is the format for coding a configuration file.
-
When using a type other than array
Fully-qualified-class-name-of-specified-class# #Comment : Fully-qualified-class-name-of-specified-class#
- #
-
You can omit the class name by using *.
-
When using array type
[-part-in-number-of-dimensions-of-array#L Fully-qualified-class-name-of-specified-class;
- #
-
In case of a multi-dimensional array, specify [ continuously for the number of dimensions. In case of three-dimensional array, it will be [[[.
- (Example) In case of one-dimensional array of aaa.bbb.Myclass class
-
[Laaa.bbb.Myclass;
- Tip
-
-
Code one class name on a line.
-
You can code up to 1,024 characters on one line. This number includes null characters and comments. If you code 1,025 or more characters on one line, parsing fails, a warning message is output, the line is ignored, and read processing continues.
-
You can omit the class name if you specify package-name.*. Unlike import declaration * in Java language, classes in sub-package are also targeted.
-
One or more line feed characters (\n or 0x0A) or recovery characters (\r or 0x0D) are considered as the end-of-line.
-
Blank characters are considered as single space character (0x20) or tab characters (\t or 0x90). If you code blank characters in the configuration file, those are ignored.
-
A comment starts with # and all characters starting from # to end-of-line are considered as a comment.
-
(4) Coding example of configuration file
Coding examples of the configuration file for Explicit Memory Management functionality application exclusion and configuration file for disabling application exclusion of the Explicit Memory Management functionality are described below.
The coding example described here is a class structure shown in the following figure having package name as com.sample.
|
-
When specifying in a fully qualified class name
The following is an example of a configuration file for Explicit Memory Management functionality application exclusion when specifying in a fully qualified class name:
com.sample.aaa.ClassA com.sample.aaa.ClassC com.sample.ddd.ClassD
In this example, the objects of ClassA class, ClassC class, and ClassD class move to Tenured area.
-
When specifying by omitting the class name
The following are coding examples of a configuration file for Explicit Memory Management functionality application exclusion and configuration file for disabling application exclusion of the Explicit Memory Management functionality when specifying by omitting class name.
-
Coding example of configuration file for Explicit Memory Management functionality application exclusion
com.sample.*
-
Coding example of configuration file for disabling application exclusion of the Explicit Memory Management functionality
com.sample.aaa.ClassB com.sample.ddd.ClassE
In this example, not only the classes in the same package but all the classes including the classes in subpackages are targeted to move to Tenured area because of the coding in the configuration file for Explicit Memory Management functionality application exclusion. However, the objects of ClassB class and ClassE class are targeted to move to the Explicit memory block because of the coding in the configuration file for Explicit Memory Management functionality application. Hence, the objects of ClassA class, ClassC class and ClassD class move to Tenured area.
- Tip
-
About whether to specify in fully qualified class name or by omitting class name, we recommend that you specify in such that the amount of coding in a configuration file is less. Both coding examples have same control. In this case, specifying by omitting class name is preferable.
-