RFR: 8335625: Update Javadoc for GetCpuLoad [v2]

[Alan Bateman]

On Wed, 21 Aug 2024 13:42:18 GMT, Joakim Nordström <jnordstrom at openjdk.org> wrote:

>> Can I get a review of this documentation update to clarify the usage of GetCpuLoad (and inherently deprecated GetSystemCpuLoad) and GetProcessCpuLoad.
>> 
>> Calling either of these methods in quick succession can lead to unrepresentative results due to too few data points.
>> 
>> This behavior is easy to reproduce on at least Linux (Windows implementation enforces a 500 ticks duration); when calling GetCpuLoad repeatedly CPU load values of either 0, 0.5, or 1 will be returned.
>> 
>> double cpuLoad1 = getCpuLoad();
>> double cpuLoad2 = getCpuLoad();   // not enough ticks has passed to give representative values
>> 
>> Worth noting is that this holds true even if getSystemCpuLoad() is called. 
>> 
>> double cpuLoad1 = getCpuLoad();
>> double cpuLoad2 = getSystemCpuLoad();   // not enough ticks has passed to give representative values, since getSystemCpuLoad effectively calls getCpuLoad.
>
> Joakim Nordström has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Made it an apiNote

We can't say "since the last call made to this method" without some qualification. If the MXBean is used directly then it immediately begs the question as to whether it means the current thread, any thread, or even from any thread in any process.  If the MXBean is used indirectly (via the MBeanServer) then I don't know what it means.

If I read the bug report correctly then this is really about setting expectations as the data is obtained in a very implementation, and environment, specific way. I don't think you can say much more than that without adding an implNote with some hints on how it implementation in some environments.

-------------

PR Comment: https://git.openjdk.org/jdk/pull/20546#issuecomment-2304001884