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

[Peter B. Kessler]

On 12/ 3/15 02:33 PM, Kim Barrett wrote:
> 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.

In a paragraph about when references are cleared and queued, the important point is that you can tell whether the referent of a soft or weak reference is no longer reachable either by testing whether get() returns null, or by polling the queue for the reference.  In contrast, phantom references always return null from get(), so to determine if the referent is no longer reachable, you have to look at the queue with which the phantom reference was registered.

			... peter

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