Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation for -Xgc suballocator options #1417

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/allocation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.


Expand Down
44 changes: 44 additions & 0 deletions docs/xgc.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`

Expand Down Expand Up @@ -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 ==== -->