Merge pull request #1591 from Sreekala-Gopakumar/1584XXCpuLoad

-XX:[+|-]CpuLoadCompatibility Documentation Updates

Author: babsingh

docs/version0.56.md

@@ -0,0 +1,51 @@
+<!--
+* Copyright (c) 2017, 2025 IBM Corp. and others
+*
+* This program and the accompanying materials are made
+* available under the terms of the Eclipse Public License 2.0
+* which accompanies this distribution and is available at
+* https://www.eclipse.org/legal/epl-2.0/ or the Apache
+* License, Version 2.0 which accompanies this distribution and
+* is available at https://www.apache.org/licenses/LICENSE-2.0.
+*
+* This Source Code may also be made available under the
+* following Secondary Licenses when the conditions for such
+* availability set forth in the Eclipse Public License, v. 2.0
+* are satisfied: GNU General Public License, version 2 with
+* the GNU Classpath Exception [1] and GNU General Public
+* License, version 2 with the OpenJDK Assembly Exception [2].
+*
+* [1] https://www.gnu.org/software/classpath/license.html
+* [2] https://openjdk.org/legal/assembly-exception.html
+*
+* SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0 OR GPL-2.0-only WITH OpenJDK-assembly-exception-1.0
+-->
+
+# What's new in version 0.56.0
+
+The following new features and notable changes since version 0.55.0 are included in this release:
+
+- [New binaries and changes to supported environments](#binaries-and-supported-environments)
+- [Change in the `getCpuLoad()` method return value based on the platform](#change-in-the-getcpuload-method-return-value-based-on-the-platform)
+
+## Features and changes
+
+### Binaries and supported environments
+
+Eclipse OpenJ9&trade; release 0.56.0 supports OpenJDK 8, 11, 17, 21, and 25.
+
+To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see [Supported environments](openj9_support.md).
+
+### Change in the `getCpuLoad()` method return value based on the platform
+
+In all platforms except z/OS&reg;, if the `-XX:+CpuLoadCompatibility` option is set to enable the OpenJDK behavior of the `getProcessCpuLoad()` and `getCpuLoad()` methods in OpenJ9, the `getCpuLoad()` method now collects two internal samples so that a valid CPU usage value can be returned instead of `0` return value on the first call.
+
+On z/OS, the CPU load that is reported by the `getCpuLoad` method is obtained directly from the system control blocks, without the need to collect samples. The `-XX:[+|-]CpuLoadCompatibility` option has no effect on z/OS, and a valid CPU usage value is always returned whatever be the setting of this option.
+
+For more information, [`-XX:[+|-]CpuLoadCompatibility`](xxcpuloadcompatibility.md).
+
+## Known problems and full release information
+
+To see known problems and a complete list of changes between Eclipse OpenJ9 v0.55.0 and v0.56.0 releases, see the [Release notes](https://github.com/eclipse-openj9/openj9/blob/master/doc/release-notes/0.56/0.56.md).
+
+<!-- ==== END OF TOPIC ==== version0.56.md ==== -->

docs/xxcpuloadcompatibility.md

@@ -23,7 +23,9 @@
 
 # -XX:[+|-]CpuLoadCompatibility
 
-This option enables or disables the OpenJDK behavior of the `getProcessCpuLoad()` and `getSystemCpuLoad()` methods in OpenJ9.
+This option enables or disables the OpenJDK behavior of the `getProcessCpuLoad()` and `getCpuLoad()` methods in OpenJ9.
+
+:fontawesome-solid-pencil:{: .note aria-hidden="true"} **Note:** Before OpenJDK 14, the `getCpuLoad()` method name was `getSystemCpuLoad()`. Because OpenJDK 14 is no longer supported, the relevant LTS release where this change is visible is OpenJDK 17 and later.
 
 ## Syntax
 
@@ -36,14 +38,17 @@ This option enables or disables the OpenJDK behavior of the `getProcessCpuLoad()
 
 ## Explanation
 
-The `getProcessCpuLoad()` method in the `com.sun.management.OperatingSystemMXBean` class returns the recent CPU usage value for the Java virtual machine process, while the `getSystemCpuLoad()` method returns the recent CPU usage value for the whole system. When these methods were called in OpenJ9 for the first time, these methods were returning `-1` to indicate that the recent CPU usage is not available. It was difficult to identify whether the reason for the `-1` value was an error or because the call was the first call and therefore, no recent CPU usage was available.
+The `getProcessCpuLoad()` method in the `com.sun.management.OperatingSystemMXBean` class returns the recent CPU usage value for the Java virtual machine process, while the `getCpuLoad()` method returns the recent CPU usage value for the whole system. When these methods were called in OpenJ9 for the first time, these methods were returning `-1` to indicate that the recent CPU usage is not available. It was difficult to identify whether the reason for the `-1` value was an error or because the call was the first call and therefore, no recent CPU usage was available.
+
+In OpenJDK, `getProcessCpuLoad()` returns `0` value on the first call, while `getCpuLoad()` collects two internal samples so that a valid CPU usage value can be returned. This `0` return value on the first call and the two internal samples make it easier to differentiate between the first call behavior and an error that needs further investigation.
 
-In OpenJDK, these methods return `0` value in the case of the first call, which makes it easier to differentiate between the first call behavior and an error that needs further investigation.
+The `-XX:+CpuLoadCompatibility` option is used to enable the OpenJDK behavior of the `getProcessCpuLoad()` and `getCpuLoad()` methods in OpenJ9.
 
-The `-XX:+CpuLoadCompatibility` option is used to enable the OpenJDK behavior of the `getProcessCpuLoad()` and `getSystemCpuLoad()` methods in OpenJ9.
+:fontawesome-solid-pencil:{: .note aria-hidden="true"} **Note:** The `-XX:[+|-]CpuLoadCompatibility` option is applicable to all platforms except z/OS®. On z/OS, the CPU load that is reported by the `getCpuLoad` method is obtained directly from the system control blocks, without the need to collect samples. The `-XX:[+|-]CpuLoadCompatibility` option has no effect on z/OS, and a valid CPU usage value is always returned whatever be the setting of this option.
 
 ## See also
 
 - [What's new in version 0.43.0](version0.43.md#new-xx-cpuloadcompatibility-option-added)
+- [What's new in version 0.56.0](version0.56.md#change-in-the-getcpuload-method-return-value-based-on-the-platform)
 
 <!-- ==== END OF TOPIC ==== xxcpuloadcompatibility.md ==== -->

mkdocs.yml

@@ -101,6 +101,7 @@ nav:
 
     - "Release notes" :
         - "Overview"                                                             : openj9_releases.md
+        - "Version 0.56.0"                                                       : version0.56.md
         - "Version 0.55.0"                                                       : version0.55.md
         - "Version 0.54.0"                                                       : version0.54.md
         - "Version 0.53.0"                                                       : version0.53.md