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

[Peter Levart]

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.  To me this is clear when I read it as a fresh reader (not comparing the before and after).  The confusion could be due to the section header “Automatically-cleared references”.  This paragraph talks about the need of registering references (soft/weak refs vs phantom refs).  I thought about (1) changing the section header to “Registering references”, or (2) a small rewording like this:
>
>    * <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.



Better, yes.

Regards, Peter

> Mandy