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

[Mandy Chung]

> On Dec 3, 2015, at 2:33 PM, Kim Barrett <kim.barrett at oracle.com> wrote:
> 
> 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.

The explicit list was what I tried to avoid as it’s repeated in the other sentences.  FinalReference is not part of java.lang.ref spec and I don’t think it could cause any confusion.

> 
> 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.
> 
> [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:

--- a/src/java.base/share/classes/java/lang/ref/package-info.java
+++ b/src/java.base/share/classes/java/lang/ref/package-info.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2003, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2015, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -43,8 +43,7 @@
  * implementing memory-sensitive caches, weak references are for
  * implementing canonicalizing mappings that do not prevent their keys
  * (or values) from being reclaimed, and phantom references are for
- * scheduling pre-mortem cleanup actions in a more flexible way than
- * is possible with the Java finalization mechanism.
+ * scheduling post-mortem cleanup actions.
  *
  * <p> Each reference-object type is implemented by a subclass of the
  * abstract base {@link java.lang.ref.Reference} class.
@@ -64,9 +63,9 @@
  * object with a <em>reference queue</em> at the time the reference
  * object is created.  Some time after the garbage collector
  * determines that the reachability of the referent has changed to the
- * value corresponding to the type of the reference, it will add the
- * reference to the associated queue.  At this point, the reference is
- * considered to be <em>enqueued</em>.  The program may remove
+ * value corresponding to the type of the reference, it will clear the 
+ * reference and add it to the associated queue.  At this point, the
+ * reference is considered to be <em>enqueued</em>.  The program may remove
  * references from a queue either by polling or by blocking until a
  * reference becomes available.  Reference queues are implemented by
  * the {@link java.lang.ref.ReferenceQueue} class.
@@ -92,16 +91,6 @@
  * structure, this check will add little overhead to the hashtable
  * access methods.
  *
- * <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.
- *
  * <a name="reachability"></a>
  * <h3>Reachability</h3>
  *

Mandy