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

[Tao Mao]

Hi Kim,

34  * <p> Suppose the garbage collector determines at a certain point
in time  35  * that an object is <a
href="package-summary.html#reachability">  36  * phantom
reachable</a>.  At that time it will atomically clear  37  * all
phantom references to that object and all phantom references to  38  *
any other phantom-reachable objects from which that object is
reachable.  39  * At the same time or at some later time it will
enqueue those newly-cleared  40  * phantom references that are
registered with reference queues.


XYZRefenrece concept is never being understood too well besides the authors
who spend time grinding words. WeakReference (
https://docs.oracle.com/javase/7/docs/api/java/lang/ref/WeakReference.html)
states this: "At that time it will atomically clear all weak references to
that object and all weak references to any other weakly-reachable objects
from which that object is reachable through a chain of strong and soft
references."

On line 38, can we also add "through a chain of strong, soft, and weak
references." to the above, which I think is the case?

In addition,
in src/java.base/share/classes/java/lang/ref/package-info.java, can we add
WeakHashMap (
https://docs.oracle.com/javase/7/docs/api/java/util/WeakHashMap.html) as a
concrete example of so-called canonicalized mappings to help readers
understand its usage? I always need to look up for what "canonicalized
mappings" really means and end up with "OK, it's WeakHashMap".

Thanks.
Tao Mao



On Thu, Dec 17, 2015 at 1:30 PM, Kim Barrett <kim.barrett at oracle.com> wrote:

> On Dec 4, 2015, at 1:07 PM, Kim Barrett <kim.barrett at oracle.com> wrote:
> >
> > On Dec 3, 2015, at 6:04 PM, Mandy Chung <mandy.chung at oracle.com> wrote:
> >>
> >>> [Indeed, this whole section isn't strictly necessary; all of it can be
> >>> inferred from information in other places.]
> >>
> >> Agree.  This section is no longer necessary and maybe just remove it:
> >
> > I wasn't actually intending to suggest removal.  It seems like there
> > is useful overview information to be had here, rather than requiring
> > readers to make not necessarily obvious inferences.  My impression is
> > that readability is valued more highly than terseness in Java
> > documentation.
>
> Sorry for the long gap in the discussion.  Mandy and I have been
> talking about what to do about the "Automatically-cleared references"
> section that was the topic of some debate.  We've decided to eliminate
> it, which led us to some additional modifications.
>
> Here's the latest set of webrevs:
> http://cr.openjdk.java.net/~kbarrett/8071507/jdk.06/
> http://cr.openjdk.java.net/~kbarrett/8071507/hotspot.06/
>
> They've been rebased to hs-rt tip, which required resolving a minor
> merge conflict with a nearby change to logging in
> referenceProcessor.cpp.  Other than that, there are only specification
> wording changes.  Here's the incremental change from the previous
> version:
> http://cr.openjdk.java.net/~kbarrett/8071507/jdk.06.inc/
>
> We are treating the discussions around changing PhantomReference to
> forbid a null queue as out of scope for this change.  As Mandy said
> earlier, she might propose a separate change for that in the future.
>
>