Name: boT120536 Date: 11/07/2000


(see also # 4278871)

java version "1.2"
Solaris VM (build Solaris_JDK_1.2_01_dev06_fcsV, native treads, sunwjit)

The documentation for java.lang.ref makes many references to a Reference
being "cleared" or "enqueued". Reference has methods called clear() and
enqueue().

A logical inference is that when a Reference is cleared (enqueued) that what
is meant is that its clear() (enqueue()) method is called.

However this is not so. The GC actually changes the Reference's referent
to null, and places the Reference on its ReferenceQueue whithout ever calling
those methods.

I can certianly understand WHY the clear() method is not used, the GC cannot
trust it to actually clear the Reference. It's not so clear what is wrong with
using enqueue().

In any case, there is no way to know the behavior of these objects from the
documentation. The user should not be required to run experiments to determine
this. If the GC causes a Reference to refer to null or puts it on a queue, the
documentation should say that. Saying that it is "cleared" or "enqueued" is not
correct.
(Review ID: 111092)
======================================================================