BlockingChecker: Updated docs and renamed to checkRunBlocking function

Author: elizarov

binary-compatibility-validator/reference-public-api/kotlinx-coroutines-android.txt

@@ -23,6 +23,6 @@ public final class kotlinx/coroutines/experimental/android/HandlerContextKt {
 
 public final class kotlinx/coroutines/experimental/android/MainLooperChecker : kotlinx/coroutines/experimental/BlockingChecker {
 	public fun <init> ()V
-	public fun runBlockingAllowed ()Z
+	public fun checkRunBlocking ()V
 }
 

binary-compatibility-validator/reference-public-api/kotlinx-coroutines-core.txt

@@ -23,7 +23,7 @@ public final class kotlinx/coroutines/experimental/AwaitKt {
 }
 
 public abstract interface class kotlinx/coroutines/experimental/BlockingChecker {
-	public abstract fun runBlockingAllowed ()Z
+	public abstract fun checkRunBlocking ()V
 }
 
 public final class kotlinx/coroutines/experimental/BuildersKt {

binary-compatibility-validator/reference-public-api/kotlinx-coroutines-javafx.txt

@@ -1,6 +1,6 @@
 public final class kotlinx/coroutines/experimental/javafx/ApplicationThreadChecker : kotlinx/coroutines/experimental/BlockingChecker {
 	public fun <init> ()V
-	public fun runBlockingAllowed ()Z
+	public fun checkRunBlocking ()V
 }
 
 public final class kotlinx/coroutines/experimental/javafx/JavaFx : kotlinx/coroutines/experimental/CoroutineDispatcher, kotlinx/coroutines/experimental/Delay {

binary-compatibility-validator/reference-public-api/kotlinx-coroutines-swing.txt

@@ -1,6 +1,6 @@
 public final class kotlinx/coroutines/experimental/swing/EventDispatchThreadChecker : kotlinx/coroutines/experimental/BlockingChecker {
 	public fun <init> ()V
-	public fun runBlockingAllowed ()Z
+	public fun checkRunBlocking ()V
 }
 
 public final class kotlinx/coroutines/experimental/swing/Swing : kotlinx/coroutines/experimental/CoroutineDispatcher, kotlinx/coroutines/experimental/Delay {

core/kotlinx-coroutines-core/src/Builders.kt

@@ -37,12 +37,8 @@ import kotlin.coroutines.experimental.*
  */
 @Throws(InterruptedException::class)
 public fun <T> runBlocking(context: CoroutineContext = EmptyCoroutineContext, block: suspend CoroutineScope.() -> T): T {
+    blockingChecker?.checkRunBlocking()
     val currentThread = Thread.currentThread()
-
-    if (blockingChecker?.runBlockingAllowed() == false) {
-        throw IllegalStateException("runBlocking is forbidden in $currentThread")
-    }
-
     val contextInterceptor = context[ContinuationInterceptor]
     val privateEventLoop = contextInterceptor == null // create private event loop if no dispatcher is specified
     val eventLoop = if (privateEventLoop) BlockingEventLoop(currentThread) else contextInterceptor as? EventLoop
@@ -55,32 +51,31 @@ public fun <T> runBlocking(context: CoroutineContext = EmptyCoroutineContext, bl
 }
 
 /**
- * Element of classpath which determines whether invoking [runBlocking] in current thread is allowed.
- * [runBlocking] discovers all checkers via [ServiceLoader]
+ * Extension point which determines whether invoking [runBlocking] in the current thread is allowed.
+ * [runBlocking] discovers all checkers via [ServiceLoader] and invokes [checkRunBlocking] on
+ * each attempt to invoke [runBlocking].
  *
  * Common example is checking whether we're not in UI thread:
+ *
  * ```
- * class UiFilter : BlockingFilter {
- *    fun runBlockingAllowed(): Boolean = !UiFramework.isInUiThread()
+ * class UiChecker : BlockingChecker {
+ *    fun checkRunBlocking() =
+ *        check(!UiFramework.isInUiThread()) { "runBlocking is not allowed in UI thread" }
  * }
  * ```
  */
-interface BlockingChecker {
-
+public interface BlockingChecker {
     /**
-     * @return whether [runBlocking] calls are allowed in current thread
+     * Throws [IllegalStateException] if [runBlocking] calls are not allowed in the current thread.
      */
-    fun runBlockingAllowed(): Boolean
+    fun checkRunBlocking()
 }
 
 // Nullable to enable DCE when no filters are present in classpath
-private val blockingChecker: BlockingChecker? = loadBlockingCheckers()
-
-private fun loadBlockingCheckers(): BlockingChecker? {
+private val blockingChecker: BlockingChecker? = run {
     val filters = ServiceLoader.load(BlockingChecker::class.java).toList().toTypedArray()
-    if (filters.isEmpty()) return null
-    return object : BlockingChecker {
-        override fun runBlockingAllowed(): Boolean = filters.all { it.runBlockingAllowed() }
+    if (filters.isEmpty()) null else object : BlockingChecker {
+        override fun checkRunBlocking() = filters.forEach { it.checkRunBlocking() }
     }
 }
 

ui/kotlinx-coroutines-android/src/HandlerContext.kt

@@ -5,6 +5,7 @@
 package kotlinx.coroutines.experimental.android
 
 import android.os.*
+import android.support.annotation.*
 import android.view.*
 import kotlinx.coroutines.experimental.*
 import java.util.concurrent.*
@@ -89,6 +90,11 @@ public class HandlerContext(
     override fun hashCode(): Int = System.identityHashCode(handler)
 }
 
+/**
+ * @suppress This is an internal impl class.
+ */
+@Keep
 class MainLooperChecker : BlockingChecker {
-    override fun runBlockingAllowed(): Boolean = Looper.myLooper() != Looper.getMainLooper()
+    override fun checkRunBlocking() =
+        check(Looper.myLooper() != Looper.getMainLooper()) { "runBlocking is not allowed in Android main looper thread" }
 }

ui/kotlinx-coroutines-javafx/src/JavaFx.kt

@@ -77,8 +77,12 @@ object JavaFx : CoroutineDispatcher(), Delay {
     override fun toString() = "JavaFx"
 }
 
+/**
+ * @suppress This is an internal impl class.
+ */
 class ApplicationThreadChecker : BlockingChecker {
-    override fun runBlockingAllowed(): Boolean = !Platform.isFxApplicationThread()
+    override fun checkRunBlocking() =
+        check(!Platform.isFxApplicationThread()) { "runBlocking is not allowed in JavaFx application thread" }
 }
 
 internal fun initPlatform() {

ui/kotlinx-coroutines-swing/src/Swing.kt

@@ -44,6 +44,10 @@ object Swing : CoroutineDispatcher(), Delay {
     override fun toString() = "Swing"
 }
 
+/**
+ * @suppress This is an internal impl class.
+ */
 class EventDispatchThreadChecker : BlockingChecker {
-    override fun runBlockingAllowed(): Boolean = !SwingUtilities.isEventDispatchThread()
+    override fun checkRunBlocking() =
+        check(!SwingUtilities.isEventDispatchThread()) { "runBlocking is not allowed in Swing event dispatch thread" }
 }