Modified -Xmint/-Xmaxt and -Xminf/-Xmaxf for balanced GC

eclipse-openj9#835

-Xmint/-Xmaxt, -Xminf/-Xmaxf, Heap allocation and -Xgcpolicy topics modified to reflect the changes applicable for the balanced GC policy.

Included the change specified in eclipse-openj9#833 in xgcpolicy topic.

Signed-off-by: Sreekala Gopakumar sreekala.gopakumar@ibm.com

docs/allocation.md

@@ -89,7 +89,7 @@ The overall size of the LOA is calculated when the heap is initialized, and reca
 
 You can control the size of the LOA by using the [`-Xloainitial`, `-Xloaminimum`, and `-Xloamaximum`](xloaminimum.md) command line options. If the LOA is not used, the garbage collector contracts the LOA after a few cycles, down to the value of `-Xloaminimum`. You can also specify [`-Xnoloa`](xloa.md) to prevent an LOA being created.
 
-An SOA and LOA are used by the OpenJ9 GC policies: `gencon`, `optavgpause` and `optthruput`. For the `gencon` policy, the LOA and SOA are contained within the tenure area, which is designated for ageing objects. For more information about policies, see [Garbage collection policies](gc.md).
+An SOA and LOA are used by the OpenJ9 GC policies: `gencon`, `optavgpause`, and `optthruput`. For the `gencon` policy, the LOA and SOA are contained within the tenure area, which is designated for ageing objects. For more information about policies, see [Garbage collection policies](gc.md).
 
 ### Region-based heaps
 
@@ -109,7 +109,7 @@ There are a number of advantages to using arraylets.
 
 - Additionally, the garbage collector never needs to move an arraylet leaf once it has been allocated. The cost of relocating an array is therefore limited to the cost of relocating the spine, so large arrays do not contribute to higher defragmentation times.
 
-:fontawesome-solid-pencil-alt:{: .note aria-hidden="true"} **Note:** Despite the general advantage of using arraylets, they can slow down processing when the Java Native Interface (JNI) is being used. The JNI provides flexibility by enabling Java programs to call native code; for example C or C++, and if direct addressability to the inside of an object is needed, a JNI critical section can be used. However, that requires the object to be in a contiguous region of memory, or at least _appear_ to be so. The JNI therefore creates a temporary contiguous array that is the same size as the original array and copies everything, element by element, to the temporary array. After the JNI critical section is finished, everything is copied from the temporary array back to the arraylet, element by element.
+:fontawesome-solid-pencil-alt:{: .note aria-hidden="true"} **Note:** Despite the general advantage of using arraylets, they can slow down processing when the Java Native Interface (JNI) is being used. The JNI provides flexibility by enabling Java programs to call native code; for example, C or C++, and if direct addressability to the inside of an object is needed, a JNI critical section can be used. However, that requires the object to be in a contiguous region of memory, or at least _appear_ to be so. The JNI, therefore, creates a temporary contiguous array that is the same size as the original array and copies everything, element by element, to the temporary array. After the JNI critical section is finished, everything is copied from the temporary array back to the arraylet, element by element.
 
 ## Heap sizing
 
@@ -139,13 +139,26 @@ Heap contraction occurs under certain conditions and might be preceded by heap c
 
 When the heap contracts, physical memory is not released unless paging is supported by the underlying operating system.
 
+#### `balanced` GC policy
+
+For the `balanced` GC policy, if the `-Xminf`/`-Xmaxf` and/or `-Xmint`/`-Xmaxt` criteria are not being met and this results in a heap resize, then the heap resize that occurs, happens only on non-eden heap (similar to how these options apply to tenure part for gencon).
+
+The non-eden heap resizing occurs at the end of a GMP cycle, or global collection. At this point, heap resizing decision is made by observing both `-Xmint`/`-Xmaxt` and `-Xminf`/`-Xmaxf` and comparing them to the appropriate proportion of time spent in GC, and free heap respectively.
+
+If either `-Xmint`/`-Xmaxt` and/or `-Xminf`/`-Xmaxf` criteria are not being met, there is no guarantee that a heap resize will occur. The heap sizing logic is looking at the following two things:
+
+- if % of time in GC pauses is between `-Xmint`/`-Xmaxt`. If it's greater than `-Xmaxt`, the VM will try to expand the heap, if it's less than `-Xmint`, then contract it.
+- if % of free heap is between `-Xminf`/`-Xmaxf`. If it's too high, i.e. greater than `-Xmaxf`(too much free), heap size will contract, if too low, i.e. lesser than `-Xminf`, it will expand.
+
+Since these two criteria may be providing opposite recommendations (for example, lots of free memory, but high % of time in GC) causing oscillations in heap size, the `balanced` GC heap sizing logic finds a balance between these two criteria.
+
 
 ### Compressed references
 
 On 64-bit systems, 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. By storing objects in a 32-bit representation, the object size is identical to that in a 32-bit VM, which creates a smaller memory footprint. These 4 byte (32-bit) compressed references are converted to 64-bit values at runtime with minimal overhead. Smaller objects enable larger heap sizes that result in less frequent garbage collection and improve memory cache utilization. Overall, the performance of 64-bit applications that store compressed rather than uncompressed 64-bit object references is significantly improved.
 
 Compressed references are used by default when the maximum Java heap size is in the range 0 - 57 GB on AIX®, Linux®, and Windows® systems. The upper limit is also 57 GB on z/OS® systems that have APAR OA49416
-installed (25 GB without APAR OA49416). All GC policies observe these limits except for the [`metronome`](gc.md#metronome-policy) policy, which can only support a heap size of up to 25 GB with compressed references.
+installed (25 GB without APAR OA49416). All GC policies observe these limits except for the [`metronome`](gc.md#metronome-policy) policy, which can support a heap size of up to 25 GB only with compressed references.
 
 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.
 

docs/version0.30.md

@@ -30,7 +30,7 @@ The following new features and notable changes since version 0.29.0 are included
 - [Changes to the shared classes cache generation number](#changes-to-the-shared-classes-cache-generation-number)
 - [Ignored options now captured in java dumps](#ignored-options-captured-in-java-dumps)
 - [New `-XX:[+|-]EnsureHashed` option added](#new-xx-ensurehashed-option-added)
-- [Redesigned heap resizing for the the `balanced` GC policy](#redesigned-heap-resizing-for-the-balanced-gc-policy)
+- [Redesigned heap resizing for the `balanced` GC policy](#redesigned-heap-resizing-for-the-balanced-gc-policy)
 
 ## Features and changes
 
@@ -65,7 +65,7 @@ This option specifies/unspecifies classes of objects that will be hashed and ext
 
 Heap resizing heuristics have been redesigned for the `balanced` GC policy. This includes both total heap resizing including eden and non-eden components independently, and also balancing between these two components when the heap is fully expanded. The heuristics now combine both the CPU overhead (for Partial GCs as well as Global Mark Phase) and the heap occupancy criteria. The balancing between eden and non-eden for fully expanded heaps is far more dynamic (instead of being mostly fixed in the ratio 1:4).
 
-As a consequence, there should typically be less need for heap sizing tuning options, most notably for eden sizing options [-Xmn, -Xmns, and -Xmnx](xmn.md). 
+As a consequence, there should typically be less need for heap sizing tuning options, most notably for eden sizing options [-Xmn, -Xmns, and -Xmnx](xmn.md).
 
 Also, a new soft limit pause target is added for Partial GCs, which defaults to 200ms. This criterion is combined with the PGC CPU overhead criterion for a balanced compromise between minimizing footprint, maximizing throughput, and meeting the paused time target.
 
@@ -75,7 +75,7 @@ More details about the new heuristics can be found at:
 
 The heuristics now obey the following existing options that were previously used for the `optthruput`, `optavgpause`, and `gencon` GC policies:
 
-- [-Xmint/-Xmaxt](xmint.md)  
+- [-Xmint/-Xmaxt](xmint.md)
 - [-Xgc:dnssExpectedTimeRatioMaximum/Minimum](xgc.md#dnssexpectedtimeratiomaximum)
 
 The heuristics also use the [-Xgc:targetPausetime](xgc.md#targetpausetime) option that was previously used only for the `metronome` GC policy.

docs/xgcpolicy.md

@@ -61,7 +61,7 @@ For a detailed description of the policies, when to use them, and how they work,
 
 : The `balanced` policy also exploits large systems that have Non-Uniform Memory Architecture (NUMA) characteristics (x86 and POWER™ platforms only), which might further improve application throughput.
 
-: :fontawesome-solid-pencil-alt:{: .note aria-hidden="true"} **Note:** If you are using this GC policy in a Docker container that uses the default `seccomp` Docker profile, you must start the container with `--security-opt seccomp=unconfined` to exploit NUMA characteristics. These options are not required if you are running in Kubernetes, because `unconfined` is set by default (see [Seccomp]( https://kubernetes.io/docs/concepts/policy/pod-security-policy/#seccomp)).
+: :fontawesome-solid-pencil-alt:{: .note aria-hidden="true"} **Note:** If you are using this GC policy in a Docker container that uses the default `seccomp` Docker profile, you must start the container with `--security-opt seccomp=unconfined` to exploit NUMA characteristics. These options are not required if you are running in Kubernetes because `unconfined` is set by default (see [Seccomp]( https://kubernetes.io/docs/concepts/policy/pod-security-policy/#seccomp)).
 
 : To learn more about this policy, how it works, and when to use it, see [Garbage collection: `balanced` policy](gc.md#balanced-policy).
 
@@ -109,6 +109,9 @@ The behavior of the following options is different when specified with `-Xgcpoli
 [`-Xnocompactexplicitgc`](xcompactexplicitgc.md)
 : Disables compaction in explicit Global GC cycles. Compaction in implicit Global GC remains optional, triggered by internal heuristics.
 
+[`-Xgc:targetPausetime`](xgc.md#targetpausetime)
+: Uses the specified GC pause time as a soft GC pause time target.
+
 The following options are ignored when specified with `-Xgcpolicy:balanced`:
 
 - `-Xconcurrentbackground<number>`
@@ -162,10 +165,11 @@ The following options are specific to the `metronome` GC policy:
 - [`-Xgc:nosynchronousGCOnOOM`](xgc.md#nosynchronousgconoom)
 - [`-Xgc:overrideHiresTimerCheck`](xgc.md#overridehirestimercheck)
 - [`-Xgc:synchronousGCOnOOM`](xgc.md#synchronousgconoom)
-- [`-Xgc:targetPausetime`](xgc.md#targetpausetime)
 - [`-Xgc:targetUtilization`](xgc.md#targetutilization)
 - [`-Xgc:verbosegcCycleTime`](xgc.md#verbosegccycletime)
 
+[`-Xgc:targetPausetime`](xgc.md#targetpausetime) option also applies to the `metronome` GC policy. This option applies only to the `metronome` and `balanced` GC policies.
+
 ### `nogc`
 
         -Xgcpolicy:nogc

docs/xminf.md

@@ -38,14 +38,16 @@ If the free space is above or below these limits, the OpenJ9 VM attempts to adju
 
 The value range is 0.0 - 1.0.
 
+- For the `balanced` GC policy, these values apply only to the non-eden space part of the heap. The non-eden heap resizing decision is made by observing both `-Xmint`/`-Xmaxt` and `-Xminf`/`-Xmaxf`. Free memory in eden space is not considered for `-Xminf`/`-Xmaxf` purposes.
 - For the `gencon` GC policy, the values apply only to the tenure part of the heap and only at global GC points.
 - For the `optthruput` and `optavgpause` GC policies, these values apply to the whole heap at every GC point.
-
-This option cannot be used with the metronome GC policy (`-Xgcpolicy:metronome`) because the heap is always fully expanded.
+- This option cannot be used with the metronome GC policy (`-Xgcpolicy:metronome`) because the heap is always fully expanded.
 
 ## See also
 
 - [Heap expansion and contraction](allocation.md#expansion-and-contraction)
+- [Garbage collection policies](gc.md)
+
 
 
 <!-- ==== END OF TOPIC ==== xminf.md ==== -->

docs/xmint.md

@@ -25,7 +25,7 @@
 # -Xmint / -Xmaxt
 
 
-Sets the minimum and maximum proportion of time to spend in the garbage collection (GC) process as a percentage of the overall running time that included the last three GC runs.
+Sets the minimum and maximum proportion of time to spend in the garbage collection (GC) process as a percentage of the overall running time that included the last three GC runs. Therefore, the time spent in the GC process includes time spent in global mark phase and global GC operations but excludes partial garbage collection pauses because the latter apply only to the eden space.
 
 - If the percentage of time drops to less than the minimum, the OpenJ9 VM tries to shrink the heap.
 - If the percentage of time exceeds the maximum, the VM tries to expand the heap.
@@ -37,16 +37,21 @@ Sets the minimum and maximum proportion of time to spend in the garbage collecti
 
 ## Syntax
 
-| Setting        | Effect                 | Default |
-|----------------|------------------------|---------|
-|`-Xmint<value>` | Set minimum time in GC | 0.05       |
-|`-Xmaxt<value>` | Set maximum time in GC | 0.13      |
+| Setting        | Effect                 | Default for balanced policy|Default for other policies|
+|----------------|------------------------|:---------:|:-------------------------------:|
+|`-Xmint<value>` | Set minimum time in GC | 0.02    |0.05                          |
+|`-Xmaxt<value>` | Set maximum time in GC | 0.05   |0.13                           |
+
+- For the `balanced` GC policy, the values apply only to the non-eden space part of the heap. The non-eden heap resizing decision is made by observing both `-Xmint`/`-Xmaxt` and `-Xminf`/`-Xmaxf`.
+- For the `gencon` GC policy, the values apply only to the tenure part of the heap.
+- For the `optthruput`, and `optavgpause` GC policies, these values apply to the whole heap.
+- This option cannot be used with the `metronome` GC policy (`-Xgcpolicy:metronome`) because the heap is always fully expanded.
 
-For the `gencon` GC policy, the values apply only to the tenure part of the heap. For the `balanced`, `optthruput`, and `optavgpause` GC policies, these values apply to the whole heap. This option cannot be used with the metronome GC policy (`-Xgcpolicy:metronome`) because the heap is always fully expanded.
 
 ## See also
 
 - [Heap expansion and contraction](allocation.md#expansion-and-contraction)
+- [Garbage collection policies](gc.md)
 
 <!-- ==== END OF TOPIC ==== xmint.md ==== -->
 <!-- ==== END OF TOPIC ==== xmaxt.md ==== -->