On 12/ 3/15 02:33 PM, Kim Barrett wrote:
On Dec 3, 2015, at 1:14 PM, Peter Levart <peter.lev...@gmail.com> wrote:
On 12/03/2015 06:01 PM, Mandy Chung wrote:
On Dec 3, 2015, at 5:01 AM, Peter Levart <peter.lev...@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.]
