On Wed, 21 Aug 2024 22:27:27 GMT, David Holmes <dhol...@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
