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

[Mandy Chung]

On Mon, 19 Oct 2020 23:17:32 GMT, Mandy Chung <mchung at openjdk.org> wrote:

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

@kimbarrett  your reworded text is okay.  I think "if it initially had some other referent value" can be dropped.

For a `Reference` constructed with a `null` referent, we can clarify in the spec that such reference object will never
get cleared and enqueued.  I suggest to file a separate issue to follow up.

-------------

PR: https://git.openjdk.java.net/jdk/pull/498