<html>
  <head>
    <meta content="text/html; charset=windows-1252"
      http-equiv="Content-Type">
  </head>
  <body text="#000000" bgcolor="#FFFFFF">
    <br>
    <br>
    <div class="moz-cite-prefix">On 06/09/2015 01:41 AM, Kim Barrett
      wrote:<br>
    </div>
    <blockquote
      cite="mid:770B325C-9DB1-42C7-AA5F-7E42B7FC0027@oracle.com"
      type="cite">
      <pre wrap="">On Jun 8, 2015, at 1:45 PM, Rezaei, Mohammad A. <a class="moz-txt-link-rfc2396E" href="mailto:Mohammad.Rezaei@gs.com"><Mohammad.Rezaei@gs.com></a> wrote:
</pre>
      <blockquote type="cite">
        <pre wrap="">
If that's the case, the documentation needs to be more clear :-) It currently says:

"Clears this reference object.  Invoking this method will not cause this object to be enqueued."

I interpret that as meaning the reference will not be put on the queue as a part of the clear() call. 

The bit of code that prevents this queuing is nowhere to be seen
</pre>
      </blockquote>
      <pre wrap="">
It’s in the VM; see callers of (C++) discover_reference, which all skip that call if the referent is null.

For example: 
<a class="moz-txt-link-freetext" href="http://hg.openjdk.java.net/jdk9/hs-rt/hotspot/annotate/431b1333b1c1/src/share/vm/oops/instanceRefKlass.inline.hpp">http://hg.openjdk.java.net/jdk9/hs-rt/hotspot/annotate/431b1333b1c1/src/share/vm/oops/instanceRefKlass.inline.hpp</a>
circa line 47

</pre>
    </blockquote>
    <br>
    Moh,<br>
    <br>
    If you're looking for javadoc part where this is described, then see
    the part of for example WeakReference class documentation which
    says:<br>
    <br>
    "Suppose that the garbage collector determines at a certain point in
    time that an object is *weakly reachable*. 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.
    At the same time it will declare all of the formerly
    weakly-reachable objects to be finalizable. At the same time or at
    some later time it will enqueue those newly-cleared weak references
    that are registered with reference queues."<br>
    <br>
    ...and in addition, the description of "weakly-reachable" and
    reachability in general:<br>
    <br>
    <ul>
      <li> An object is <em>strongly reachable</em> if it can be
        reached by some
        thread without traversing any reference objects. A newly-created
        object is
        strongly reachable by the thread that created it.
      </li>
      <li> An object is <em>softly reachable</em> if it is not strongly
        reachable but
        can be reached by traversing a soft reference.
      </li>
      <li> An object is <b><em>weakly reachable</em></b> if it is
        neither strongly nor
        softly reachable but can be reached by traversing a weak
        reference. When the
        weak references to a weakly-reachable object are cleared, the
        object becomes
        eligible for finalization.
      </li>
      <li> An object is <em>phantom reachable</em> if it is neither
        strongly, softly,
        nor weakly reachable, it has been finalized, and some phantom
        reference refers
        to it.
      </li>
      <li> Finally, an object is <em>unreachable</em>, and therefore
        eligible for
        reclamation, when it is not reachable in any of the above ways.
      </li>
    </ul>
    <br>
    ...so for an object to be "weakly-reachable" it has to be reachable
    by traversing a WeakReference. If you manually clear all
    WeakReferences pointing to an object, It will not be
    weakly-reachable any more, so GC will not do any actions that would
    make WeakReferences that formerly pointed to that object being
    enqueued at a later time. It can't do any actions, since those
    WeakReferences are not in any way associated with a referent any
    more after they are manually cleared.<br>
    <br>
    Regards, Peter<br>
    <br>
  </body>
</html>