jmx-dev RFR: 8335625: Update Javadoc for GetCpuLoad

[Alan Bateman]

On Wed, 21 Aug 2024 11:27:44 GMT, David Holmes <dholmes 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.
>
> src/jdk.management/share/classes/com/sun/management/OperatingSystemMXBean.java line 142:
> 
>> 140:      * negative value.
>> 141:      *
>> 142:      * <p> This method is not idempotent. The recent period of observation
> 
> I would not expect this method to be "idempotent" so it seems very odd to me to state this. Overall this sounds like you are now specifying an implementation limitation as the only way this can be done. Maybe this should be an `@ImplNote` ?

You beat me to it. We specify some methods (close, dispose, ...) as idempotent. Specifying a getter as non-idempotent looks very strange here.

I can't tell if you are looking to specify implementation behavior (as David asks) or whether you want to provide advice for users of this API, in which case an apiNote may be the tag you need.

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

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