Move threading concerns to API surface

The scanning implementation is making decisions on threading that aren't optimal:

1) It scans for view roots from the calling thread
2) But then it always performs the scanning of each hierarchy from the main thread (but only if they're Android views). There's one post to the main thread per Android root view and each gets 5 seconds for the traversal, so if the main thread is blocked and we have N windows we could wait N * 5 seconds.

This change moves these decisions around threading behavior to the callers, with a default provided configuration that matches the previous behavior, except there is a single post and the root scanning is done as part of it.

Author: pyricau

radiography/api/radiography.api

@@ -12,7 +12,20 @@ public final class radiography/Radiography {
 	public static final fun scan (Lradiography/ScanScope;)Ljava/lang/String;
 	public static final fun scan (Lradiography/ScanScope;Ljava/util/List;)Ljava/lang/String;
 	public static final fun scan (Lradiography/ScanScope;Ljava/util/List;Lradiography/ViewFilter;)Ljava/lang/String;
-	public static synthetic fun scan$default (Lradiography/ScanScope;Ljava/util/List;Lradiography/ViewFilter;ILjava/lang/Object;)Ljava/lang/String;
+	public static final fun scan (Lradiography/ScanScope;Ljava/util/List;Lradiography/ViewFilter;Lradiography/ScanExecutor;)Ljava/lang/String;
+	public static synthetic fun scan$default (Lradiography/ScanScope;Ljava/util/List;Lradiography/ViewFilter;Lradiography/ScanExecutor;ILjava/lang/Object;)Ljava/lang/String;
+}
+
+public abstract interface class radiography/ScanExecutor {
+	public abstract fun execute (Ljava/util/concurrent/Callable;)Ljava/lang/String;
+}
+
+public final class radiography/ScanExecutors {
+	public static final field INSTANCE Lradiography/ScanExecutors;
+	public static final field PassthroughExecutor Lradiography/ScanExecutor;
+	public static final fun HandlerPostingExecutor (Landroid/os/Handler;JLjava/util/concurrent/TimeUnit;)Lradiography/ScanExecutor;
+	public static final fun LooperEnforcingExecutor (Landroid/os/Looper;)Lradiography/ScanExecutor;
+	public static final fun NeverThrowingExecutor (Lradiography/ScanExecutor;)Lradiography/ScanExecutor;
 }
 
 public abstract interface class radiography/ScanScope {

radiography/src/main/java/radiography/Radiography.kt

@@ -1,16 +1,16 @@
 package radiography
 
-import android.os.Handler
-import android.os.Looper
 import android.view.View
 import android.view.WindowManager
 import androidx.annotation.VisibleForTesting
 import radiography.Radiography.scan
+import radiography.ScanExecutors.HandlerPostingExecutor
+import radiography.ScanExecutors.NeverThrowingExecutor
+import radiography.ScanExecutors.mainHandler
 import radiography.ScanScopes.AllWindowsScope
 import radiography.ScannableView.AndroidView
 import radiography.ViewStateRenderers.DefaultsNoPii
 import radiography.internal.renderTreeString
-import java.util.concurrent.CountDownLatch
 import java.util.concurrent.TimeUnit.SECONDS
 
 /**
@@ -42,37 +42,24 @@ public object Radiography {
   public fun scan(
     scanScope: ScanScope = AllWindowsScope,
     viewStateRenderers: List<ViewStateRenderer> = DefaultsNoPii,
-    viewFilter: ViewFilter = ViewFilters.NoFilter
-  ): String = buildString {
-    val roots = try {
-      scanScope.findRoots()
-    } catch (e: Throwable) {
-      append("Exception when finding scan roots: ${e.message}")
-      return@buildString
-    }
-
-    roots.forEach { scanRoot ->
-      // The entire view tree is single threaded, and that's typically the main thread, but
-      // it doesn't have to be, and we don't know where the passed in view is coming from.
-      val viewLooper = (scanRoot as? AndroidView)?.view?.handler?.looper
-        ?: Looper.getMainLooper()!!
-
-      if (viewLooper.thread == Thread.currentThread()) {
-        scanFromLooperThread(scanRoot, viewStateRenderers, viewFilter)
-      } else {
-        val latch = CountDownLatch(1)
-        Handler(viewLooper).post {
-          scanFromLooperThread(scanRoot, viewStateRenderers, viewFilter)
-          latch.countDown()
-        }
-        if (!latch.await(5, SECONDS)) {
-          return "Could not retrieve view hierarchy from main thread after 5 seconds wait"
-        }
+    viewFilter: ViewFilter = ViewFilters.NoFilter,
+    scanExecutor: ScanExecutor = NeverThrowingExecutor(
+      HandlerPostingExecutor(
+        mainHandler,
+        5,
+        SECONDS
+      )
+    )
+  ): String = scanExecutor.execute {
+    buildString {
+      val roots = scanScope.findRoots()
+      roots.forEach { scanRoot ->
+        scanRoot(scanRoot, viewStateRenderers, viewFilter)
       }
     }
   }
 
-  private fun StringBuilder.scanFromLooperThread(
+  private fun StringBuilder.scanRoot(
     rootView: ScannableView,
     viewStateRenderers: List<ViewStateRenderer>,
     viewFilter: ViewFilter

radiography/src/main/java/radiography/ScanExecutor.kt

@@ -0,0 +1,19 @@
+package radiography
+
+import java.util.concurrent.Callable
+
+/**
+ * Ensures that scanning happens on the right thread (by e.g. posting work, throwing, or simply
+ * not checking, depending on implementation)
+ *
+ * Some commons executors are:
+ *  - [ScanExecutors.NeverThrowingExecutor]
+ *  - [ScanExecutors.PassthroughExecutor]
+ *  - [ScanExecutors.HandlerPostingExecutor]
+ *  - [ScanExecutors.LooperEnforcingExecutor]
+ */
+public fun interface ScanExecutor {
+
+  /** Returns the result of executing [callable] */
+  public fun execute(callable: Callable<String>): String
+}

radiography/src/main/java/radiography/ScanExecutors.kt

@@ -0,0 +1,82 @@
+package radiography
+
+import android.os.Handler
+import android.os.Looper
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+
+public object ScanExecutors {
+
+  internal val mainHandler by lazy {
+    Handler(Looper.getMainLooper())
+  }
+
+  /**
+   * Runs the scanning tasks synchronously without any thread check, posting or exception catching.
+   */
+  @JvmField
+  public val PassthroughExecutor: ScanExecutor = ScanExecutor { callable ->
+    callable.call()
+  }
+
+  /**
+   * Executes the scanning tasks on the provided [delegate] ScanExecutor but catches any
+   * exception and returns an error string instead.
+   */
+  @JvmStatic
+  public fun NeverThrowingExecutor(delegate: ScanExecutor): ScanExecutor = ScanExecutor { callable ->
+    try {
+      delegate.execute(callable)
+    } catch (throwable: Throwable) {
+      "Exception when scanning: ${throwable.message}"
+    }
+  }
+
+  /**
+   * Runs the scanning tasks and blocks the current thread until completion. If the current thread
+   * is the same as the [handler] thread, then the runnable runs immediately without being enqueued.
+   * Otherwise, posts the runnable to [handler] and waits for it to complete before returning,
+   * throwing if timeout occurs or if the work could not be scheduled, and rethrowing any main
+   * thread exception to the calling thread.
+   */
+  @JvmStatic
+  public fun HandlerPostingExecutor(
+    handler: Handler,
+    timeout: Long,
+    timeoutUnit: TimeUnit
+  ): ScanExecutor = ScanExecutor { callable ->
+    if (handler.looper === Looper.myLooper()) {
+      callable.call()
+    } else {
+      var result: Result<String>? = null
+      val latch = CountDownLatch(1)
+      val posted = handler.post {
+        result = try {
+          Result.success(callable.call())
+        } catch (throwable: Throwable) {
+          Result.failure(throwable)
+        }
+        latch.countDown()
+      }
+      check(posted) {
+        "Callback not posted, probably because the looper processing the message queue is exiting."
+      }
+      check(latch.await(timeout, timeoutUnit)) {
+        "Could not scan hierarchy from main thread, timed out"
+      }
+      result!!.getOrThrow()
+    }
+  }
+
+  /**
+   * Runs the scanning tasks synchronously, throwing if the current thread is not the same as the
+   * thread of the provided [Looper]. Does not catch any exception.
+   */
+  @JvmStatic
+  public fun LooperEnforcingExecutor(looper: Looper): ScanExecutor = ScanExecutor { callable ->
+    check(looper === Looper.myLooper()) {
+      "Should be called from ${looper.thread.name}, not ${Thread.currentThread().name}"
+    }
+    callable.call()
+  }
+}