<div dir="ltr">Hi Kim,<div><br><div><pre style="color:rgb(0,0,0);background-color:rgb(238,238,238)"><span class="" style="color:blue">34  * <p> Suppose the garbage collector determines at a certain point in time</span>
<span class="" style="color:blue">  35  * that an object is <a href="package-summary.html#reachability"></span>
<span class="" style="color:blue">  36  * phantom reachable</a>.  At that time it will atomically clear</span>
<span class="" style="color:blue">  37  * all phantom references to that object and all phantom references to</span>
<span class="" style="color:blue">  38  * any other phantom-reachable objects from which that object is reachable.</span>
<span class="" style="color:blue">  39  * At the same time or at some later time it will enqueue those newly-cleared</span>
<span class="" style="color:blue">  40  * phantom references that are registered with reference queues.</span></pre></div><div><br></div><div>XYZRefenrece concept is never being understood too well besides the authors who spend time grinding words. WeakReference (<a href="https://docs.oracle.com/javase/7/docs/api/java/lang/ref/WeakReference.html">https://docs.oracle.com/javase/7/docs/api/java/lang/ref/WeakReference.html</a>) 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."</div><div><br></div><div>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?</div><div><br></div><div>In addition, in src/java.base/share/classes/java/lang/ref/package-info.java, can we add WeakHashMap (<a href="https://docs.oracle.com/javase/7/docs/api/java/util/WeakHashMap.html">https://docs.oracle.com/javase/7/docs/api/java/util/WeakHashMap.html</a>) 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".</div><div><br></div><div>Thanks.</div><div>Tao Mao</div><div><br></div><div><br></div></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Thu, Dec 17, 2015 at 1:30 PM, Kim Barrett <span dir="ltr"><<a href="mailto:kim.barrett@oracle.com" target="_blank">kim.barrett@oracle.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="HOEnZb"><div class="h5">On Dec 4, 2015, at 1:07 PM, Kim Barrett <<a href="mailto:kim.barrett@oracle.com">kim.barrett@oracle.com</a>> wrote:<br>
><br>
> On Dec 3, 2015, at 6:04 PM, Mandy Chung <<a href="mailto:mandy.chung@oracle.com">mandy.chung@oracle.com</a>> wrote:<br>
>><br>
>>> [Indeed, this whole section isn't strictly necessary; all of it can be<br>
>>> inferred from information in other places.]<br>
>><br>
>> Agree.  This section is no longer necessary and maybe just remove it:<br>
><br>
> I wasn't actually intending to suggest removal.  It seems like there<br>
> is useful overview information to be had here, rather than requiring<br>
> readers to make not necessarily obvious inferences.  My impression is<br>
> that readability is valued more highly than terseness in Java<br>
> documentation.<br>
<br>
</div></div>Sorry for the long gap in the discussion.  Mandy and I have been<br>
talking about what to do about the "Automatically-cleared references"<br>
section that was the topic of some debate.  We've decided to eliminate<br>
it, which led us to some additional modifications.<br>
<br>
Here's the latest set of webrevs:<br>
<a href="http://cr.openjdk.java.net/~kbarrett/8071507/jdk.06/" rel="noreferrer" target="_blank">http://cr.openjdk.java.net/~kbarrett/8071507/jdk.06/</a><br>
<a href="http://cr.openjdk.java.net/~kbarrett/8071507/hotspot.06/" rel="noreferrer" target="_blank">http://cr.openjdk.java.net/~kbarrett/8071507/hotspot.06/</a><br>
<br>
They've been rebased to hs-rt tip, which required resolving a minor<br>
merge conflict with a nearby change to logging in<br>
referenceProcessor.cpp.  Other than that, there are only specification<br>
wording changes.  Here's the incremental change from the previous<br>
version:<br>
<a href="http://cr.openjdk.java.net/~kbarrett/8071507/jdk.06.inc/" rel="noreferrer" target="_blank">http://cr.openjdk.java.net/~kbarrett/8071507/jdk.06.inc/</a><br>
<br>
We are treating the discussions around changing PhantomReference to<br>
forbid a null queue as out of scope for this change.  As Mandy said<br>
earlier, she might propose a separate change for that in the future.<br>
<br>
</blockquote></div><br></div>