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

[Roger Riggs]

Hi Chris,

On 05/29/2019 08:50 AM, Chris Hegarty wrote:
> 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
>
ok
>
>> 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?
Reclaiming memory is described in Runtime.gc() "The JVM performs this 
recycling process automatically as needed"
so typically, it is an ongoing process. Nearly all of the behavior of gc 
could not be considered side effects,
clearing WeakReferences, SoftReferences, etc all of which can happen 
asynchronously to the gc() method call.
Other possible 'side-effects' would include the implementation behavior 
of classes that use j.l.r.References to
maintain their own resources such as DirectByteBuffers, etc. that manage 
off-heap memory.
But those effects are not constrained to be synchronous with the gc() 
method invocation.

Thanks, Roger

>
> -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.
>>>
>>