Add documentation for -Xgc suballocator options

Documents: - suballocatorInitialSize - suballocatorIncrementSize - suballocatorCommitSize - suballocatorQuickAllocEnable - suballocatorQuickAllocDisable Signed-off-by: Nathan Henderson <[email protected]>
eclipse-openj9 · Sep 26, 2024 · 2bb959a · 2bb959a
1 parent f3822d5
commit 2bb959a
Show file tree

Hide file tree

Showing 2 changed files with 52 additions and 0 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.
 
+The following options allow for further control of the compressed reference allocation:
+
+- [`-Xgc:suballocatorInitialSize=<bytes>`](xgc.md#suballocatorinitialsize)
+- [`-Xgc:suballocatorIncrementSize=<bytes>`](xgc.md#suballocatorincrementsize)
+- [`-Xgc:suballocatorCommitSize=<bytes>`](xgc.md#suballocatorcommitsize)
+- [`-Xgc:suballocatorQuickAllocEnable`](xgc.md#suballocatorquickallocenable)
+- [`-Xgc:suballocatorQuickAllocDisable`](xgc.md#suballocatorquickallocdisable)
+
 To turn off compressed references, use the [`-Xnocompressedrefs`](xcompressedrefs.md) command-line option.
 
 

diff --git a/docs/xgc.md b/docs/xgc.md
@@ -59,6 +59,11 @@ Options that change the behavior of the garbage collector.
 | [`tlhMaximumSize`                   ](#tlhmaximumsize                   ) | Sets the maximum size of the thread local heap.                                                           |
 | [`verboseFormat`                    ](#verboseformat                    ) | Sets the verbose GC format.                                                                               |
 | [`verbosegcCycleTime`               ](#verbosegccycletime                    ) | Sets the criteria for verbose GC logging.                                                                              |
+| [`suballocatorInitialSize`          ](#suballocatorinitialsize          ) | Sets the initial size in bytes for the heap used for compressed references.                               |
+| [`suballocatorIncrementSize`        ](#suballocatorincrementsize        ) | Sets the reservation increment size in bytes for the heap used for compressed references.                 |
+| [`suballocatorCommitSize`           ](#suballocatorcommitsize           ) | Sets the commit size in bytes for the heap used for compressed references.                                |
+| [`suballocatorQuickAllocEnable`     ](#suballocatorquickallocenable     ) | Enables mmap-based allocation for compressed references (affects Linux only).                             |
+| [`suballocatorQuickAllocDisable`    ](#suballocatorquickallocdisable    ) | Disable mmap-based allocation for compressed references (affects Linux only).                             |
 
 ### `breadthFirstScanOrdering`
 
@@ -357,4 +362,43 @@ Larger TLHs can help reduce heap lock contention, but might also reduce heap uti
 
 : This option applies only to the `metronome` GC policy.
 
+### `suballocatorInitialSize`
+
+        -Xgc:suballocatorInitialSize=<bytes>
+
+: Sets the initial size of the heap used for compressed references. The default size is 200 MB.
+
+: This option can be used with all OpenJ9 GC policies. It only affects builds using compressed references.
+
+### `suballocatorIncrementSize`
+
+        -Xgc:suballocatorIncrementSize=<bytes>
+
+: Sets the reservation increment size of the heap used for compressed references. When the memory of the current heap space is exhausted, the increment size determines the amount of additional memory to reserve. The default size is 8 MB for most platforms. The exception is AIX which defaults to 256 MB.
+
+: This option can be used with all OpenJ9 GC policies. It only affects builds using compressed references.
+
+### `suballocatorCommitSize`
+
+        -Xgc:suballocatorCommitSize=<bytes>
+
+: Sets the commit size of the heap used for compressed references. The default size is 50 MB.
+
+: This option can be used with all OpenJ9 GC policies. It only affects builds using compressed references.
+
+### `suballocatorQuickAllocEnable`
+
+        -Xgc:suballocatorQuickAllocEnable
+
+: Enables mmap-based allocation for compressed references (affects Linux only). Enabled by default.
+
+: This option can be used with all OpenJ9 GC policies. It only affects builds using compressed references.
+
+### `suballocatorQuickAllocDisable`
+
+        -Xgc:suballocatorQuickAllocDisable
+
+: Disables mmap-based allocation for compressed references (affects Linux only).
+
+: This option can be used with all OpenJ9 GC policies. It only affects builds using compressed references.
 <!-- ==== END OF TOPIC ==== xgc.md ==== -->