On Wed, 21 Aug 2024 13:42:18 GMT, Joakim Nordström <jnordst...@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
