RFR: 8188066: (ref) Examine the reachability of JNI WeakGlobalRef and interaction with phantom refs

[David Holmes]

Looks good.

Thanks Kim!

David
-----

On 14/03/2019 9:02 am, Kim Barrett wrote:
>> On Mar 13, 2019, at 4:29 PM, Kim Barrett <kim.barrett at oracle.com> wrote:
>>
>>> On Mar 13, 2019, at 4:07 PM, Kim Barrett <kim.barrett at oracle.com> wrote:
>>>
>>> Please review this change to the JNI specification.  The specified
>>> behavior of Weak Global References, and in particular their
>>> relationship to Java PhantomReference, is being updated to account
>>> for a change to PhantomReference by JDK-8071507.
>>>
>>> CR:
>>> https://bugs.openjdk.java.net/browse/JDK-8188066
>>>
>>> CSR:
>>> https://bugs.openjdk.java.net/browse/JDK-8220617
>>>
>>> Changes:
>>> http://cr.openjdk.java.net/~kbarrett/8188066/jni_specdiff_rev1.html
>>> specdiff for the changes.  In addition to updating the section
>>> describing Weak Global References, the description of NewGlobalRef
>>> is updated, as well as the copyright footer.
>>>
>>> http://cr.openjdk.java.net/~kbarrett/8188066/weak_global_refs_rev1.md
>>> Copies of the before and after text for the JNI Weak Global
>>> References section; easier to read than diffs or specdiff.
>>
>> I botched the upload of the changes to cr.openjdk.java.net.  The corrected URLS are:
>>
>> http://cr.openjdk.java.net/~kbarrett/8188066/jni_specdiff_rev1/diff.html
>> http://cr.openjdk.java.net/~kbarrett/8188066/weak_global_refs_rev1.html
> 
> Stefan Karlsson suggested (offline) a couple of wording changes in the
> description of Weak Global References.
> 
> (1) Replace "destroyed" with "deleted" in two places, to align with the
> names of DeleteGlobalRef and the like.
> 
> (2) Reword the second sentence of the fourth paragraph, as there is some
> potential for ambiguity around "If the references are the same".
> 
> Here's the diff between rev1 and those changes. I'll post an updated
> specdiff later, once the dust settles.
> 
> diff -r 76b82c006509 -r 6a2181c4fee2 closed/src/java.se/share/specs/jni/functions.md
> --- a/closed/src/java.se/share/specs/jni/functions.md	Wed Mar 13 15:40:33 2019 -0400
> +++ b/closed/src/java.se/share/specs/jni/functions.md	Wed Mar 13 17:06:23 2019 -0400
> @@ -1177,9 +1177,9 @@
>   to `NULL` without notice.
>   
>   `IsSameObject` can be used to compare a weak global reference to a non-`NULL`
> -local or global reference.  If the references are the same, the weak global
> -reference's underlying object will not be freed so long as the other reference
> -has not been destroyed.
> +local or global reference.  If the objects are the same, the weak global
> +reference won't become functionally equivalent to `NULL` so long as the other
> +reference has not been deleted.
>   
>   `IsSameObject` can also be used to compare a weak global reference to `NULL`
>   to determine whether the underlying object has been freed.
> @@ -1193,7 +1193,7 @@
>   `NewGlobalRef`.  These functions will return `NULL` if the object has been
>   freed.  Otherwise, the new reference will prevent the underlying object from
>   being freed.  The new reference, if non-`NULL`, can then be used to access the
> -underlying object, and destroyed when such access is no longer needed.
> +underlying object, and deleted when such access is no longer needed.
>   
>   -------------------------------------------------------------------------------
>   
>