Add documentation for -Xgc suballocator options

#1418 Added new `-Xgc` suballocator options in related topics. Incorporated the review feedback. Closes #1418 Signed-off-by: Sreekala Gopakumar [email protected]
eclipse-openj9 · Jan 13, 2025 · dfccd8b · dfccd8b
1 parent d4d5bc6
commit dfccd8b
Show file tree

Hide file tree

Showing 4 changed files with 78 additions and 4 deletions.
diff --git a/docs/allocation.md b/docs/allocation.md
@@ -161,6 +161,14 @@ installed (25 GB without APAR OA49416). All GC policies observe these limits exc
 
 When the VM uses compressed references, classes, threads, and monitors are stored in the lowest 4 GB of address space. However, this area of memory is also used by native libraries, the operating system, and for small Java heaps. If you receive native memory `OutOfMemoryError` exceptions in the lowest 4 GB when running with compressed references enabled, these errors might result from the lowest 4 GB of address space becoming full. Try specifying a large heap with the [`-Xmx`](xms.md) option, which puts the Java heap into a higher area of address space or using the [`-Xmcrs`](xmcrs.md) option to reserve space in the lowest 4 GB of address space for compressed references.
 
+You can control the compressed reference allocation with the following options:
+
+ - [`-Xgc:suballocatorCommitSize=<size>`](xgc.md#suballocatorcommitsize)
+ - [`-Xgc:suballocatorIncrementSize=<size>`](xgc.md#suballocatorincrementsize)
+ - [`-Xgc:suballocatorInitialSize=<size>`](xgc.md#suballocatorinitialsize)
+ - [`-Xgc:suballocatorQuickAllocDisable`](xgc.md#suballocatorquickallocdisable)
+ - [`-Xgc:suballocatorQuickAllocEnable`](xgc.md#suballocatorquickallocenable)
+
 To turn off compressed references, use the [`-Xnocompressedrefs`](xcompressedrefs.md) command-line option.
 
 

diff --git a/docs/version0.49.md b/docs/version0.49.md
@@ -28,6 +28,7 @@ The following new features and notable changes since version 0.48.0 are included
 - [New binaries and changes to supported environments](#binaries-and-supported-environments)
 - [Change to the shared classes cache generation number](#change-to-the-shared-classes-cache-generation-number)
 - [New shared classes cache suboption added to adjust the number of startup hints that can be stored](#new-shared-classes-cache-suboption-added-to-adjust-the-number-of-startup-hints-that-can-be-stored)
+- [`subAllocator` related `-Xgc` options are added to control the compressed reference allocation](#suballocator-related-xgc-options-are-added-to-control-the-compressed-reference-allocation)
 
 ## Features and changes
 
@@ -53,6 +54,18 @@ You can use the `-Xshareclasses:extraStartupHints=<number>` option to adjust the
 
 For more information, see [`-Xshareclasses:extraStartupHints`](xshareclasses.md#extrastartuphints).
 
+### `subAllocator` related `-Xgc` options are added to control the compressed reference allocation
+
+The VM can use compressed references to decrease the size of Java objects and make better use of the available space in the Java heap. You can now control the compressed reference allocation with the following options:
+
+ - [`-Xgc:suballocatorCommitSize=<size>`](xgc.md#suballocatorcommitsize)
+ - [`-Xgc:suballocatorIncrementSize=<size>`](xgc.md#suballocatorincrementsize)
+ - [`-Xgc:suballocatorInitialSize=<size>`](xgc.md#suballocatorinitialsize)
+ - [`-Xgc:suballocatorQuickAllocDisable`](xgc.md#suballocatorquickallocdisable)
+ - [`-Xgc:suballocatorQuickAllocEnable`](xgc.md#suballocatorquickallocenable)
+
+For more information, see [Compressed references](allocation.md#compressed-references).
+
 ## Known problems and full release information
 
 To see known problems and a complete list of changes between Eclipse OpenJ9 v0.48.0 and v0.49.0 releases, see the [Release notes](https://github.com/eclipse-openj9/openj9/blob/master/doc/release-notes/0.49/0.49.md).

diff --git a/docs/xgc.md b/docs/xgc.md
@@ -51,6 +51,11 @@ Options that change the behavior of the garbage collector.
 | [`scvNoAdaptiveTenure`              ](#scvnoadaptivetenure              ) | Turns off the adaptive tenure age in the generational concurrent GC policy.                               |
 | [`scvTenureAge`                     ](#scvtenureage                     ) | Sets the initial scavenger tenure age in the generational concurrent GC policy.                           |
 | [`stdGlobalCompactToSatisfyAllocate`](#stdglobalcompacttosatisfyallocate) | Prevents the GC from performing a compaction unless absolutely required.                                  |
+| [`suballocatorCommitSize`           ](#suballocatorcommitsize           ) | Sets the commit size in bytes for the `subAllocator` area that is used for compressed references.                                |
+| [`suballocatorIncrementSize`        ](#suballocatorincrementsize        ) | Sets the reservation increment size in bytes for the `subAllocator` area that is used for compressed references.                 |
+| [`suballocatorInitialSize`          ](#suballocatorinitialsize          ) | Sets the initial size in bytes for the `subAllocator` area that is used for compressed references.                               |
+| [`suballocatorQuickAllocDisable`    ](#suballocatorquickallocdisable    ) | Disables mmap-based allocation of the compressed references `subAllocator` area. (Linux only)                            |
+| [`suballocatorQuickAllocEnable`     ](#suballocatorquickallocenable     ) | Enables mmap-based allocation of the compressed references `subAllocator` area. (Linux only)                            |
 | [`synchronousGCOnOOM`               ](#synchronousgconoom               )     | Stops an application to allow GC activity.                                                                             |
 | [`targetPausetime`                  ](#targetpausetime                  )   | Sets the target GC pause time for the `metronome` and `balanced` GC policies.                            |
 | [`targetUtilization`                ](#targetutilization                )   | Sets application utilization for the `metronome` GC policy.                                                   |
@@ -272,6 +277,55 @@ the dynamic compaction triggers that look at heap occupancy. This option works o
 
 : This option is not supported with the balanced GC policy (`-Xgcpolicy:balanced`) or metronome GC policy (`-Xgcpolicy:metronome`).
 
+### `suballocatorCommitSize`
+
+        -Xgc:suballocatorCommitSize=<size>
+
+: For more information about the `<size>` parameter, see [Using -X command-line options](x_jvm_commands.md).
+
+: Sets the commit size of the area in memory that is reserved within the lowest 4 GB memory area for any native classes, monitors, and threads that are used by compressed references. The default size is 50 MB.
+
+: This option is supported by all OpenJ9 GC policies. The option affects only those builds that use compressed references.
+
+### `suballocatorIncrementSize`
+
+        -Xgc:suballocatorIncrementSize=<size>
+
+: For more information about the `<size>` parameter, see [Using -X command-line options](x_jvm_commands.md).
+
+: Sets the reservation increment size of the area in memory that is reserved within the lowest 4 GB memory area for any native classes, monitors, and threads that are used by compressed references. When the memory of the current space is exhausted, the increment size determines the amount of additional memory to reserve. The default size is 8 MB for all platforms except AIX. The default size for AIX is 256 MB.
+
+: This option is supported by all OpenJ9 GC policies. The option affects only those builds that use compressed references.
+
+### `suballocatorInitialSize`
+
+        -Xgc:suballocatorInitialSize=<size>
+
+: For more information about the `<size>` parameter, see [Using -X command-line options](x_jvm_commands.md).
+
+: Sets the initial size of the area in memory that is reserved within the lowest 4 GB memory area for any native classes, monitors, and threads that are used by compressed references. The default size is 200 MB.
+
+: This option is supported by all OpenJ9 GC policies. The option affects only those builds that use compressed references.
+
+: The `-Xgc:suballocatorInitialSize` option overrides the [`-Xmcrs`](xmcrs.md) option irrespective of the order of the options on the command line. If the `-Xmcrs` option is thus overridden, the `-Xmcrs` output of `-verbose:sizes` shows the `suballocatorInitialSize` value.
+
+### `suballocatorQuickAllocDisable`
+**Linux only**
+
+        -Xgc:suballocatorQuickAllocDisable
+
+: Disables mmap-based allocation of an area in memory that is reserved within the lowest 4 GB memory area for any native classes, monitors, and threads that are used by compressed references.
+
+: This option is supported by all OpenJ9 GC policies. The option affects only those builds that use compressed references.
+
+### `suballocatorQuickAllocEnable`
+**Linux only**
+
+        -Xgc:suballocatorQuickAllocEnable
+
+: Enables mmap-based allocation of an area in memory that is reserved within the lowest 4 GB memory area for any native classes, monitors, and threads that are used by compressed references. This option is enabled by default.
+
+: This option is supported by all OpenJ9 GC policies. The option affects only those builds that use compressed references.
 
 ### `synchronousGCOnOOM`
 

diff --git a/docs/xmcrs.md b/docs/xmcrs.md
@@ -24,22 +24,21 @@
 # -Xmcrs 
 
 
-Sets an initial size for an area in memory that is reserved for any native classes, monitors, and threads that are used by compressed references within the lowest 4 GB memory area.
+Sets an initial size for an area in memory that is reserved within the lowest 4 GB memory area for any native classes, monitors, and threads that are used by compressed references.
 
 You can use the `-verbose:sizes` option to find out the value that is being used by the VM.
 
 :fontawesome-solid-pencil:{: .note aria-hidden="true"} **Notes:**
 
 - Native memory `OutOfMemoryError` exceptions might occur when using compressed references if the lowest 4 GB of address space becomes full, particularly when loading classes, starting threads, or using monitors. 
 - If you are not using compressed references and this option is set, the option is ignored and the output of `-verbose:sizes` shows `-Xmcrs0`.
-
-
+- This option is overridden by the [`-Xgc:suballocatorInitialSize`](xgc.md#suballocatorinitialsize) option, irrespective of the order of the options on the command line. If the `-Xmcrs` option is thus overridden, the `-Xmcrs` output of `-verbose:sizes` shows the `suballocatorInitialSize` value.
 
 ## Syntax
 
         -Xmcrs<size>
 
-See [Using -X command-line options](x_jvm_commands.md) for more information about the `<size>` parameter.
+For more information about the `<size>` parameter, see [Using -X command-line options](x_jvm_commands.md).
 
 
 <!-- ==== END OF TOPIC ==== xmcrs.md ==== -->