RFR: 8335625: Update Javadoc for GetCpuLoad [v2]

[Daniel Fuchs]

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

src/jdk.management/share/classes/com/sun/management/OperatingSystemMXBean.java line 145:

> 143:      * call made to this method, or {@link #getCpuLoad()}. For the very first
> 144:      * invocation of this method, the recent period of observation is undefined.
> 145:      *

I wonder if the text would read better as:

     * @apiNote The recent period of observation is typically the duration since the last


Since this is an MBean, many different callers could be calling this method, including other Monitor MBeans that may have been registered. Adding _typically_ will soften the assertion, give more leeway to implementations, and still be informative enough for readers to better understand the API?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/20546#discussion_r1725176645