Documentation for -XX:[+/-]CpuLoadCompatibility

[thallium]

Issue or pull request number:
eclipse-openj9/openj9#18636

Overview:
By default, getProcessCpuLoad() and getSystemCpuLoad() return -1 if only one data point has been recorded. By specifying the -XX:+CpuLoadCompatibility flag, they will return zero which matches the behaviour of the RI.

Release target:
Eclipse OpenJ9 0.43.0

Applies to the following JDK versions:
8 and later

Applies to the following platforms:
All platforms

For new command line options:

• Option name and syntax: -XX:[+/-]CpuLoadCompatibility

[Sreekala-Gopakumar]

@thallium - Few clarifications required.

• Why was this change required? What was the problem?
• What do the getProcessCpuLoad() and getSystemCpuLoad() options do?
• What is meant by "return -1 if only one data point has been recorded"? Which data point?
• Why did it have to return zero to match the behaviour of the RI?
• What is RI and how is it connected to this option?

Thanks!

[thallium]

Why was this change required? What was the problem?

It came from a user issue stating getProcessCpuLoad() returns -1 on the first call while OpenJDK doesn't.

What do the getProcessCpuLoad() and getSystemCpuLoad() options do?

Not sure what do you mean by "options". Do you mean "functions"?

What is meant by "return -1 if only one data point has been recorded"? Which data point?

It means CPU time data point (pair of (time, CPU time)).

Why did it have to return zero to match the behaviour of the RI?

My thoughts:

1. Easier for people to migrate to OpenJ9 from OpenJDK
2. People might relate a negative return value to an error, so user will have to manually track if it's the first call if we return -1 in the first call.

What is RI and how is it connected to this option?

RI is OpenJDK, enabling this flag matches the behaviour on the first call to OpenJDK.

[Sreekala-Gopakumar]

Not sure what do you mean by "options". Do you mean "functions"?

Yes.

[Sreekala-Gopakumar]

@thallium - Also, what is the default setting for this option? Is it enabled (-XX:+CpuLoadCompatibility), by default? Thanks!

[Sreekala-Gopakumar]

@thallium - If I were to give a brief explanation of the getProcessCpuLoad() method in the OpenJ9 documents, then should I be saying "getProcessCpuLoad() method of class com.sun.management.OperatingSystemMXBean" or getProcessCpuLoad() method of class com.ibm.lang.management.OperatingSystemMXBean?

Thanks!

[Sreekala-Gopakumar]

@thallium - I have created a new topic for this option. The content is as follows. Please check and let me know if there any changes to be made. Thanks!

-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"}yes
-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.

[Sreekala-Gopakumar]

@thallium - Any update on this? Thanks!

Please check #1258 (comment)

[thallium]

@Sreekala-Gopakumar Sorry for the delay, as I'm working part time this semester.

The flag disabled by default. The explanation looks good to me!