8188055: (ref) Add Reference::refersTo predicate

Reviewed-by: mchung, pliden, rriggs, dholmes, ihse, smarks, alanb

src/java.base/share/classes/java/lang/ref/PhantomReference.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2020, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -60,6 +60,14 @@ public class PhantomReference<T> extends Reference<T> {
         return null;
     }
 
+    /* Override the implementation of Reference.refersTo.
+     * Phantom references are weaker than finalization, so the referent
+     * access needs to be handled differently for garbage collectors that
+     * do reference processing concurrently.
+     */
+    @Override
+    native final boolean refersTo0(Object o);
+
     /**
      * Creates a new phantom reference that refers to the given object and
      * is registered with the given queue.

src/java.base/share/classes/java/lang/ref/Reference.java

@@ -325,14 +325,40 @@ public abstract class Reference<T> {
      * been cleared, either by the program or by the garbage collector, then
      * this method returns {@code null}.
      *
+     * @apiNote
+     * This method returns a strong reference to the referent. This may cause
+     * the garbage collector to treat it as strongly reachable until some later
+     * collection cycle.  The {@link #refersTo(Object) refersTo} method can be
+     * used to avoid such strengthening when testing whether some object is
+     * the referent of a reference object; that is, use {@code ref.refersTo(obj)}
+     * rather than {@code ref.get() == obj}.
+     *
      * @return   The object to which this reference refers, or
      *           {@code null} if this reference object has been cleared
+     * @see refersTo
      */
     @IntrinsicCandidate
     public T get() {
         return this.referent;
     }
 
+    /**
+     * Tests if the referent of this reference object is {@code obj}.
+     * Using a {@code null} {@code obj} returns {@code true} if the
+     * reference object has been cleared.
+     *
+     * @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
+     */
+    public final boolean refersTo(T obj) {
+        return refersTo0(obj);
+    }
+
+    /* Implementation of refersTo(), overridden for phantom references.
+     */
+    native boolean refersTo0(Object o);
+
     /**
      * Clears this reference object.  Invoking this method will not cause this
      * object to be enqueued.

src/java.base/share/native/libjava/PhantomReference.c

@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) 2020, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+#include "jvm.h"
+#include "java_lang_ref_PhantomReference.h"
+
+JNIEXPORT jboolean JNICALL
+Java_java_lang_ref_PhantomReference_refersTo0(JNIEnv *env, jobject ref, jobject o)
+{
+    return JVM_PhantomReferenceRefersTo(env, ref, o);
+}

src/java.base/share/native/libjava/Reference.c

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2016, 2020, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -43,3 +43,9 @@ Java_java_lang_ref_Reference_waitForReferencePendingList(JNIEnv *env, jclass ign
 {
     JVM_WaitForReferencePendingList(env);
 }
+
+JNIEXPORT jboolean JNICALL
+Java_java_lang_ref_Reference_refersTo0(JNIEnv *env, jobject ref, jobject o)
+{
+    return JVM_ReferenceRefersTo(env, ref, o);
+}