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

[David Holmes]

On 20/10/2020 12:40 pm, Kim Barrett wrote:
>> 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
>   */

I'm okay with that version too. Like Mandy I think the "if it initially 
..." can be dropped.

Thanks,
David
-----

>