On Mon, 19 Oct 2020 23:17:32 GMT, Mandy Chung <mch...@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
