RFR 8220238 : Enhancing j.l.Runtime/System::gc specification with an explicit 'no guarantee' statement

[Chris Hegarty]

Roger,

On 28/05/2019 21:54, Roger Riggs wrote:
> Hi Aleksey,
> 
> The </p> is always optional (in html5).

The way that the source documentation is structured suggests that a new
paragraph, `<p>`, is missing HERE ( see below ).

  642      * Runs the garbage collector in the Java Virtual Machine.
  643      *
  644      * <HERE> Calling this method suggests that the Java Virtual 
Machine


> The issue with the "when control returns" and "best effort" sentence is 
> that is implies that something has been done
> and that is not necessarily true.  At best, it could say is that the 
> implementation may have done something or done nothing
> and anything in between.

Commenting only on "when control returns".

Whether GC occurs or not is orthogonal to "when control returns". I read
"when control returns" to mean that once the invocation of `gc`
completes successfully ( without throwing ), then there will be no
further side-effects of this method. The suggested wording removes that
restriction. Is that intentional?

-Chris.

> Suggestions welcome.
> 
> Thanks, Roger
> 
> 
> 
> On 05/28/2019 02:06 PM, Aleksey Shipilev wrote:
>> On 5/28/19 7:58 PM, Roger Riggs wrote:
>>> Please review a change to the javadoc of Runtime.gc() and System.gc() 
>>> to clarify
>>> that invoking these methods does not guarantee any specific result or 
>>> timeliness
>>> of completion.
>>>
>>> The revised text is:
>>>
>>>        * Runs the garbage collector in the Java Virtual Machine.
>>>        *
>>>        * Calling this method suggests that the Java Virtual Machine
>>>        * expend effort toward recycling unused objects in order to
>>>        * make the memory they currently occupy available for reuse
>>>        * by the Java Virtual Machine.
>>>        * There is no guarantee that this effort will recycle any 
>>> particular
>>>        * number of unused objects, reclaim any particular amount of 
>>> space,
>>>        * or complete at any particular time, if at all.
>>>
>>> Issue:
>>>    https://bugs.openjdk.java.net/browse/JDK-8220238
>>>
>>> CSR:
>>>    https://bugs.openjdk.java.net/browse/JDK-8224760
>>>
>>> Webrev:
>>>    http://cr.openjdk.java.net/~rriggs/webrev-gc-8220238/index.html
>> Thank you.
>>
>> It feels like <p/> is missing between paragraphs?
>>
>> Also, I don't think it is sensible to drop the blocking behavior 
>> ("When control returns...") -- I
>> think some programs enjoy that property, and certainly many GCs have 
>> special tests to enforce this
>> property, even if GC is fully concurrent.
>>
>