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

[Mandy Chung]

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

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.

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

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