Documentation for -XX:[+/-]CpuLoadCompatibility

eclipse-openj9#1232

Created a new topic for -XX:[+/-]CpuLoadCompatibility. Updated the What's new in version 0.43.0 and mkdocs.yml file

Closes eclipse-openj9#1232
Signed-off-by: Sreekala Gopakumar <[email protected]>

Author: Sreekala-Gopakumar

docs/version0.43.md

@@ -30,6 +30,7 @@ The following new features and notable changes since version 0.42.0 are included
 - [Change in the large page memory allocation behavior](#change-in-the-large-page-memory-allocation-behavior)
 - ![Start of content that applies to Java 11 (LTS) and later](cr/java11plus.png) [New `-XX:[+|-]CRIUSecProvider` option added](#new-xx-criusecprovider-option-added) ![End of content that applies to Java 11 (LTS) and later](cr/java_close.png)
 - [New `-XX:Compatibility` option added](#new-xxcompatibility-option-added)
+- [New `-XX:[+|-]CpuLoadCompatibility` option added](#new-xx-cpuloadcompatibility-option-added)
 
 ## Features and changes
 
@@ -73,6 +74,16 @@ In release 0.43.0, the compatibility mode is provided for the Elasticsearch appl
 
 For more information, see [`-XX:Compatibility`](xxcompatibility.md).
 
+### New `-XX:[+|-]CpuLoadCompatibility` option added
+
+The `getProcessCpuLoad()` and `getSystemCpuLoad()` methods were returning `-1` to indicate that the recent CPU usage is not available when these methods were called in OpenJ9 for the first time. 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, 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 `getSystemCpuLoad()` methods in OpenJ9 so that these methods return `0` when called in OpenJ9 for the first time.
+
+For more information, see [`-XX:[+|-]CpuLoadCompatibility`](xxcpuloadcompatibility.md).
+
 ## Known problems and full release information
 
 To see known problems and a complete list of changes between Eclipse OpenJ9 v0.42.0 and v0.43.0 releases, see the [Release notes](https://github.com/eclipse-openj9/openj9/blob/master/doc/release-notes/0.43/0.43.md).

docs/xxcpuloadcompatibility.md

@@ -0,0 +1,47 @@
+<!--
+* Copyright (c) 2017, 2024 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
+-->
+
+# -XX:[+|-]CpuLoadCompatibility
+
+This option enables or disables the OpenJDK behavior of the `getProcessCpuLoad()` and `getSystemCpuLoad()` methods in OpenJ9.
+
+## Syntax
+
+        -XX:[+|-]CpuLoadCompatibility
+
+| Setting               | Effect  | Default                                                                            |
+|-----------------------|---------|:----------------------------------------------------------------------------------:|
+| `-XX:+CpuLoadCompatibility` |  Enable   |   :fontawesome-solid-check:{: .yes aria-hidden="true"}<span class="sr-only">yes</span>                                 |
+| `-XX:-CpuLoadCompatibility` |  Disable  |     |
+
+## 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.
+
+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 `getSystemCpuLoad()` methods in OpenJ9.
+
+
+
+<!-- ==== END OF TOPIC ==== xxcpuloadcompatibility.md ==== -->

mkdocs.yml

@@ -388,6 +388,7 @@ nav:
             - "-XX:codecachetotalMaxRAMPercentage"                               : xxcodecachetotalmaxrampercentage.md
             - "-XX:[+|-]CompactStrings"                                          : xxcompactstrings.md
             - "-XX:ContinuationCache"                                            : xxcontinuationcache.md
+            - "-XX:[+|-]CpuLoadCompatibility"                                    : xxcpuloadcompatibility.md
             - "-XX:DiagnoseSyncOnValueBasedClasses"                              : xxdiagnosesynconvaluebasedclasses.md
             - "-XX:[+|-]DisableExplicitGC"                                       : xxdisableexplicitgc.md
             - "-XX:[+|-]DisclaimJitScratch"                                      : xxdisclaimjitscratch.md