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

[David Holmes]

On 17/10/2020 1:23 am, Kim Barrett wrote:
> On Fri, 16 Oct 2020 05:41:17 GMT, David Holmes <dholmes at openjdk.org> wrote:
> 
>>> Kim Barrett has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev
>>> excludes the unrelated changes brought in by the merge/rebase. The pull request contains 11 additional commits since
>>> the last revision:
>>>   - Merge branch 'master' into refersto
>>>   - More explicit refersTo0 comment.
>>>   - simplify test
>>>   - cleanup nits from Mandy
>>>   - use Object instead of TestObject
>>>   - improve refersTo0 descriptions
>>>   - basic functional test
>>>   - change referent access
>>>   - expand test
>>>   - remove CMS comment
>>>   - ... and 1 more: https://git.openjdk.java.net/jdk/compare/b5adeaad...ab4e519b
>>
>> src/java.base/share/classes/java/lang/ref/Reference.java line 348:
>>
>>> 346:      * Tests if this reference object refers to {@code obj}.  If {@code obj} is
>>> 347:      * {@code null}, this method returns {@code true} if this reference object
>>> 348:      * refers to {@code null} or has been cleared.
>>
>> Is there actually a distinction between clearing and referring to null?
> 
> A (not very useful) Reference can be created with a null referent.

Yes but you cannot distinguish between the two cases yet this wording is 
trying to make that distinction. My concern is interaction with the 
wording here:

   * @return  {@code true} if and only if {@code obj} is the referent
   *          of this reference object

As written it implies to me that given:

Object o = new Object();
PhantomReference r = new PhantomReference(o);
r.clear();
assert(r.refersTo(null)); // pass or fail?

then the assert should fail because "null" was not the referent, as r 
has been cleared - which are two distinct cases according to the initial 
java doc. The initial doc would be clearer if it stated words to the 
effect of:

"returns {@code true} if this reference object refers to {@code null} 
(either because it was constructed that way, or it has been cleared)."

or else the @return doc needs to account for the null case more 
explicitly. Also why the "if and only if" in the @return doc versus a 
simple "if"? What is being emphasized by using "if and only if"?

Cheers,
David
-----


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