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
(2) Specifying configuration file and scope of application of the Explicit Memory Management functionality
(3) Format for coding a configuration file
(4) Coding example of configuration file

(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.

To Page Top

(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.

[Figure]

To Page Top

(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.

To Page Top

(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.

Figure 7‒26: Example of class structure

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.

To Page Top