bind: replace Java finalizers with PhantomReferences

Android runs a finalizer watchdog that tracks the running time of
finalizers and throws an exception if any runs too long. Our
finalizers do very little work and as such are not affected by the
timeout. However, there has been reports, for example:

https://stackoverflow.com/questions/24021609/how-to-handle-java-util-concurrent-timeoutexception-android-os-binderproxy-fin

that the watchdog does not take into account periods where the device
goes to sleep in the middle of a finalizer run. So if a given app runs
in the background, the Java GC starts a finalizer and the device goes
to sleep before it returns, an exception will crash the app if the sleep
period extends the watchdog timeout.

The problem might be fixed on some newer version of Android, but the
problem is reported for as late as Android 6.

The suggested workaround is to use PhantomReferences and run a
background thread that take dead references off a ReferenceQueue and
perform cleanup.

This CL builds on the previous CL and splits up the Ref class so Refs
only reference counts Java objects, while a new class GoRef tracks Go
references. The Go references are wrapped in PhantomReferences that in
turn appear on a GoRefQueue to be cleaned up by a background (daemon)
Thread.

Change-Id: I04e3296b851999c612d3baf6a593cc044c2c5bdd
Reviewed-on: https://go-review.googlesource.com/106876
Reviewed-by: Hyang-Ah Hana Kim <hyangah@gmail.com>

bind/java/Seq.java

@@ -4,8 +4,15 @@
 
 package go;
 
+import java.lang.ref.PhantomReference;
+import java.lang.ref.Reference;
+import java.lang.ref.ReferenceQueue;
 import java.util.Arrays;
+import java.util.Collection;
+import java.util.Collections;
 import java.util.IdentityHashMap;
+import java.util.HashSet;
+import java.util.Set;
 import java.util.logging.Logger;
 
 import go.Universe;
@@ -21,6 +28,9 @@ public class Seq {
 	// use single Ref for null Object
 	public static final Ref nullRef = new Ref(NULL_REFNUM, null);
 
+	// The singleton GoRefQueue
+	private static final GoRefQueue goRefQueue = new GoRefQueue();
+
 	static {
 		// Look for the shim class auto-generated by gomobile bind.
 		// Its only purpose is to call System.loadLibrary.
@@ -66,7 +76,8 @@ public class Seq {
 		return o.incRefnum();
 	}
 
-	// trackGoRef returns a Ref for a Go refnum.
+	// trackGoRef tracks a Go reference and decrements its refcount
+	// when the given GoObject wrapper is garbage collected.
 	//
 	// TODO(crawshaw): We could cut down allocations for frequently
 	// sent Go objects by maintaining a map to weak references. This
@@ -75,11 +86,11 @@ public class Seq {
 	// of any Java debugging session.
 	//
 	// When we have real code, examine the tradeoffs.
-	public static Ref trackGoRef(int refnum) {
+	public static void trackGoRef(int refnum, GoObject obj) {
 		if (refnum > 0) {
 			throw new RuntimeException("trackGoRef called with Java refnum " + refnum);
 		}
-		return new Ref(refnum, null);
+		goRefQueue.track(refnum, obj);
 	}
 
 	public static Ref getRef(int refnum) {
@@ -89,7 +100,7 @@ public class Seq {
 	// Increment the Go reference count before sending over a refnum.
 	public static native void incGoRef(int refnum);
 
-	// Informs the Go ref tracker that Java is done with this ref.
+	// Informs the Go ref tracker that Java is done with this refnum.
 	static native void destroyRef(int refnum);
 
 	// decRef is called from seq.FinalizeRef
@@ -113,23 +124,14 @@ public class Seq {
 	// in Go.
 	public interface Proxy extends GoObject {}
 
-	// A Ref is an object tagged with an integer for passing back and
-	// forth across the language boundary.
-	//
-	// A Ref may represent either an instance of a Java object,
-	// or an instance of a Go object. The explicit allocation of a Ref
-	// is used to pin Go object instances when they are passed to Java.
-	// The Go Seq library maintains a reference to the instance in a map
-	// keyed by the Ref number. When the JVM calls finalize, we ask Go
-	// to clear the entry in the map.
+	// A Ref represents an instance of a Java object passed back and forth
+	// across the language boundary.
 	public static final class Ref {
-		// refnum < 0: Go object tracked by Java
-		// refnum > 0: Java object tracked by Go
 		public final int refnum;
 
-		private int refcnt;  // for Java obj: track how many times sent to Go.
+		private int refcnt;  // Track how many times sent to Go.
 
-		public final Object obj;  // for Java obj: pointers to the Java obj.
+		public final Object obj;  // The referenced Java obj.
 
 		Ref(int refnum, Object o) {
 			if (refnum < 0) {
@@ -140,15 +142,6 @@ public class Seq {
 			this.obj = o;
 		}
 
-		@Override
-		protected void finalize() throws Throwable {
-			if (refnum < 0) {
-				// Go object: signal Go to decrement the reference count.
-				Seq.destroyRef(refnum);
-			}
-			super.finalize();
-		}
-
 		void inc() {
 			// Count how many times this ref's Java object is passed to Go.
 			if (refcnt == Integer.MAX_VALUE) {
@@ -256,6 +249,53 @@ public class Seq {
 		}
 	}
 
+	// GoRefQueue is a queue of GoRefs that are no longer live. An internal thread
+	// processes the queue and decrement the reference count on the Go side.
+	static class GoRefQueue extends ReferenceQueue<GoObject> {
+		// The set of tracked GoRefs. If we don't hold on to the GoRef instances, the Java GC
+		// will not add them to the queue when their referents are reclaimed.
+		private final Collection<GoRef> refs = Collections.synchronizedCollection(new HashSet<GoRef>());
+
+		void track(int refnum, GoObject obj) {
+			refs.add(new GoRef(refnum, obj, this));
+		}
+
+		GoRefQueue() {
+			Thread daemon = new Thread(new Runnable() {
+				@Override public void run() {
+					while (true) {
+						try {
+							GoRef ref = (GoRef)remove();
+							refs.remove(ref);
+							destroyRef(ref.refnum);
+							ref.clear();
+						} catch (InterruptedException e) {
+							// Ignore
+						}
+					}
+				}
+			});
+			daemon.setDaemon(true);
+			daemon.setName("GoRefQueue Finalizer Thread");
+			daemon.start();
+		}
+	}
+
+	// A GoRef is a PhantomReference to a Java proxy for a Go object.
+	// GoRefs are enqueued to the singleton GoRefQueue when no longer live,
+	// so the corresponding reference count can be decremented.
+	static class GoRef extends PhantomReference<GoObject> {
+		final int refnum;
+
+		GoRef(int refnum, GoObject obj, GoRefQueue q) {
+			super(obj, q);
+			if (refnum > 0) {
+				throw new RuntimeException("GoRef instantiated with a Java refnum " + refnum);
+			}
+			this.refnum = refnum;
+		}
+	}
+
 	// RefMap is a mapping of integers to Ref objects.
 	//
 	// The integers can be sparse. In Go this would be a map[int]*Ref.