Merge pull request #1635 from Sreekala-Gopakumar/1634SilentAdj

Adjustment of default maximum heap size based on initial size

Author: pshipton

docs/version0.53.md

@@ -30,6 +30,7 @@ The following new features and notable changes since version 0.51.0 are included
 - [OpenSSL 3.5.1 is bundled on all platforms](#openssl-351-is-bundled-on-all-platforms)
 - [Offheap support is added for the `balanced` GC policy](#offheap-support-is-added-for-the-balanced-gc-policy)
 - ![Start of content that applies to Java 11 (LTS) and later](cr/java11plus.png) [New JDK Flight Recorder (JFR) events are added in this release](#new-jdk-flight-recorder-jfr-events-are-added-in-this-release) ![End of content that applies only to Java 11 and later](cr/java_close.png)
+- [The default maximum heap size is automatically adjusted based on the initial heap size](#the-default-maximum-heap-size-is-automatically-adjusted-based-on-the-initial-heap-size)
 
 ## Features and changes
 
@@ -68,6 +69,12 @@ In this release, the following new JFR events are added:
 
 For more information, see [`-XX:[+|-]FlightRecorder`](xxflightrecorder.md). ![End of content that applies only to Java 11 and later](cr/java_close.png)
 
+### The default maximum heap size is automatically adjusted based on the initial heap size
+
+If the maximum object heap size is not explicitly set with the `-Xmx` option and the VM uses the default value of `-Xmx`, then even if `-Xms` is greater than `-Xmx` initially, the VM starts successfully. The VM starts because the default `-Xmx` value is increased automatically to match `-Xms`.
+
+Until the 0.53.0 release, if `-Xms` was greater than `-Xmx`, the VM used to fail. For more information, see [`-Xms` / `-Xmx`](xms.md).
+
 ## Known problems and full release information
 
 To see known problems and a complete list of changes between Eclipse OpenJ9 v0.51.0 and v0.53.0 releases, see the [Release notes](https://github.com/eclipse-openj9/openj9/blob/master/doc/release-notes/0.53/0.53.md).

docs/xms.md

@@ -24,11 +24,11 @@
 # -Xms / -Xmx
 
 
-These Oracle® HotSpot™ options set the initial/minimum Java™ heap size, and the maximum heap size respectively. These options are recognized by the Eclipse OpenJ9™ VM.
+The Oracle® HotSpot™ option `-Xms` sets the initial or the minimum Java™ heap size, and the `-Xmx` HotSpot option sets the maximum heap size. These options are recognized by the Eclipse OpenJ9™ VM.
 
 :fontawesome-solid-pencil:{: .note aria-hidden="true"} **Notes:**
 
-- If you set `-Xms` > `-Xmx`, the VM fails with the message `-Xms too large for -Xmx`.
+- If you set `-Xms` &gt; `-Xmx`, the VM fails with the message `-Xms too large for -Xmx`.<br>If you do not explicitly set the maximum object heap size with `-Xmx` and the VM uses the default value of `-Xmx`, then even if `-Xms` is greater than `-Xmx` initially, the VM starts successfully because the default `-Xmx` value is increased automatically to match `-Xms`.<br><br>For example, for a VM with 16 GB RAM, the default maximum size is 25% of RAM, therefore the default value of `Xmx` will be 4 GB. If the initial size is specified as 6 GB (`-Xms6g`), then `-Xms` (6 GB) is greater than `-Xmx` (4 GB) and before the 0.53.0 release that VM used to fail. But now with current adjustment, the default maximum heap size is increased automatically to 6 GB and the VM starts. This change in behavior was added from the 0.53.0 release onwards.
 - If you exceed the limit set by the `-Xmx` option, the VM generates an `OutofMemoryError`.
 - If you set a value for `-Xms`, the [`-XX:InitialRAMPercentage`](xxinitialrampercentage.md) option is ignored.
 - If you set a value for `-Xmx`, the [`-XX:MaxRAMPercentage`](xxinitialrampercentage.md) option is ignored.
@@ -62,11 +62,12 @@ The `-Xmx` option can be used with all OpenJ9 GC policies. However, the `-Xms` o
 :   Heap starts at 50 MB and grows to the default maximum.
 
 `-Xmx256m`
-:   Heap starts at default initial value and grows to a maximum of 256 MB.
+:   Heap starts at the default initial value and grows to a maximum of 256 MB.
 
 ## See also
 
 - [-Xsoftmx (Set "soft" maximum Java heap size)](xsoftmx.md)
+- [What's new in version 0.53.0](version0.53.md#the-default-maximum-heap-size-is-automatically-adjusted-based-on-the-initial-heap-size)