RFR: 8071507: (ref) Clear phantom reference as soft and weak references do

[Kim Barrett]

On Dec 3, 2015, at 1:14 PM, Peter Levart <peter.levart at gmail.com> wrote:
> 
> On 12/03/2015 06:01 PM, Mandy Chung wrote:
>>> On Dec 3, 2015, at 5:01 AM, Peter Levart <peter.levart at gmail.com>
>>>  wrote:
>>> 
>>>  I would only rephrase this statement in package-info.java a bit:
>>> 
>>>  96  * Soft and weak references are automatically cleared by the collector
>>>  97  * before being added to the queues with which they are registered, if any,
>>>  98  * hence they need not be registered with a queue in order to be useful.
>>>  99  * Phantom references, by contrast, do not allow their referents to be
>>> 100  * retrieved, so they must be registered with a queue.
>>> 
>> Kim brought up the potential confusion on the above wordings.  […]
>> 
>>   * <h3>Automatically-cleared references</h3>
>>   *
>> - * Soft and weak references are automatically cleared by the collector
>> - * before being added to the queues with which they are registered, if
>> - * any.  Therefore soft and weak references need not be registered
>> - * with a queue in order to be useful, while phantom references do.
>> - * An object that is reachable via phantom references will remain so
>> - * until all such references are cleared or themselves become
>> - * unreachable.
>> + * References are automatically cleared by the collector before being
>> + * added to the queues with which they are registered, if any.
>> + * Soft and weak references allow their referents to be retrieved,
>> + * hence they need not be registered with a queue in order to be useful.
>> + * Phantom references, by contrast, do not allow their referents to be
>> + * retrieved, so they must be registered with a queue.
>> 
> 
> Or:
> 
> ..., so they are only useful if they are registered with a queue.

Drawing on the various suggestions so far, how about this:

----- 

Soft, weak, and phantom references are automatically cleared by the
collector before being added to the queues with which they are
registered, if any. Soft and weak references allow access to the
referent before they are cleared, and hence need not be registered
with a queue in order to be useful. Phantom references, by contrast,
prevent access to the referent, so they are only useful when
registered with a queue.

-----

I prefer the explicit list in the opening sentence, rather than
collapsing that to just "References", to avoid any possible confusion
that this might apply to (the internal and undocumented, but visible
in the code) FinalReference.

I included a serial comma in the list; I generally prefer that usage,
and it's consistent with earlier usage on the same page.

In the final sentence, I prefer to avoid the use of "must", especially
without any "to be useful" qualification, as that sounds like it might
be a formal requirement, and that would be inconsistent with the
PhantomReference constructor documentation.

The second sentence (about soft and weak references) could be deleted,
along with the "by contrast" phrase in the third, without loss of
information.  It does save the reader a bit of inference though.

[Indeed, this whole section isn't strictly necessary; all of it can be
inferred from information in other places.]