RFR: 8335625: Update Javadoc for GetCpuLoad [v2]

[Joakim Nordström]

On Wed, 21 Aug 2024 22:27:27 GMT, David Holmes <dholmes at openjdk.org> wrote:

>> I want to provide advice for how this API should be used.
>> 
>> The "recent period of time observed" is vague (Who's the observer? Who decides the "recent period"? The API user or the JVM?). In essence it is the time between two consecutive calls, but that is not very clear from the description -- this has been seen to cause confusion.
>> 
>> I hesitated to add "idempotent", but also I felt that it added something. Without it, the rest of the sentence is basically just the same words as in the first paragraph, so they can be easily missed. Also, the best practices I've seen is that "getters" should be idempotent, so stating this one isn't signals there's something to take note of here.
>> 
>> Adding `@apiNote` might be enough of signal. Have updated with the tag and removed "idempotent".
>
>> "Idempotence is the property of certain operations in mathematics and computer science whereby they can be applied multiple times without changing the result beyond the initial application. "
> 
> So the notion of idempotency on a getter method just doesn't make sense in general  and in this case in particular as you calculate a new result each time.

Right, I agree. The confusing thing here is that it isn't obvious by the name (nor the docs, until now hopefully) that it does calculate a new result each time it is called. 

What I think user's want, and mistakes this method for, is something of the commandline `top` equivalent. By not being able to define the period of observation, or even reliably tell what it is, I think many assumes it's something reasonable. To add to this, looking at the Windows implementation you have a minimum duration of 500 ticks, so you'll never see the outliers you see on Linux where you can get a duration of just 2 ticks, and get return values like 1.0, 0.5, or 0.0.

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

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