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

[Kim Barrett]

> 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.
 
 -------------------------------------------------------------------------------