RFR: 8188055: (ref) Add Reference::refersTo predicate [v5]

[Kim Barrett]

> On Oct 19, 2020, at 7:20 PM, Mandy Chung <mchung at openjdk.java.net> wrote:
> 
> On Mon, 19 Oct 2020 23:10:23 GMT, Mandy Chung <mchung at openjdk.org> wrote:
> 
>>> Looks good.
>> 
>>> That's the crux of it: what exactly is meant by "the referent"? Does it
>>> mean the original object that was used as the referent, or does it mean
>>> the current value of the "referent" field inside the Reference (as get
>>> might return)?
>> 
>> "the referent" is the object a `Reference` object refers to.
>> 
>> as it's described in java.lang.ref package description:
>> 
>>> Each reference-object type is implemented by a subclass of the abstract base Reference class. An instance of one of
>>> these subclasses encapsulates a single reference to a particular object, called the referent.
>> 
>> See also `@return` in `Reference::get`:
>>> @return The object to which this reference refers, or null if this reference object has been cleared

In light of David's comments, I now think get's @return text is inconsistent
with the rest of get's description, which starts off with

* Returns this reference object's referent.

That seems definitional to me.  It then goes on to say

* If this reference object has
* been cleared, either by the program or by the garbage collector, then
* this method returns {@code null}.

which is just noting that the referent is null after clearing.

But the @return seems to be suggesting some distinction between the referent
and the post-clear result of calling get. If there is such a distinction
then the first sentence of the description is factually false. I think this
would be improved by changing "or" to "which is" in the @return description.

> I also personally prefer to use the "refers to" wording in the specification as well (IIRC I suggested that wordings).
> What about:
> 
> * Tests if this reference object refers to {@code obj}.
> * If {@code obj} is {@code null}, this method returns {@code true} if
> * this reference object was constructed with a {@code null} referent
> * or has been cleared.
> and
> @return {@code true} if {@code obj} is the object to which this reference refers,
>              or if {@code obj} is {@code null} and this reference has been cleared.

I think the @param description of refersTo has the same problem. I don't
think there's any need to mention null at all in the description of
refersTo. I originally thought, and still think, the following is sufficient
and accurate, (esp. with the above wording tweak for get's @return text).

/**
 * Tests if the referent of this reference object is {@code obj}.
 *
 * @param  obj the object to compare with this reference object's referent
 * @return {@code true} if {@code obj} is the referent of this reference object
 * @since 16
 */

Mandy asked for additional discussion around null, but I've come around to
agreeing the current text isn't ideal. Rather than just rewording the
current @return text though, how about this:

/**
 * Tests if the referent of this reference object is {@code obj}.
 * Using a {@code null} {@code obj} allows detection of a reference that 
 * has been cleared, if it initially had some other referent value. 
 *
 * @param  obj the object to compare with this reference object's referent
 * @return {@code true} if {@code obj} is the referent of this reference object
 * @since 16
 */