Provide HandlerContext.immediate extension to immediately execute tasks which are invoked from the right context

Fixes #381

Author: qwwdfsad

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

@@ -10,8 +10,10 @@ public final class kotlinx/coroutines/experimental/android/HandlerContext : kotl
 	public fun delay (JLjava/util/concurrent/TimeUnit;Lkotlin/coroutines/experimental/Continuation;)Ljava/lang/Object;
 	public fun dispatch (Lkotlin/coroutines/experimental/CoroutineContext;Ljava/lang/Runnable;)V
 	public fun equals (Ljava/lang/Object;)Z
+	public final fun getImmediate ()Lkotlinx/coroutines/experimental/android/HandlerContext;
 	public fun hashCode ()I
 	public fun invokeOnTimeout (JLjava/util/concurrent/TimeUnit;Ljava/lang/Runnable;)Lkotlinx/coroutines/experimental/DisposableHandle;
+	public fun isDispatchNeeded (Lkotlin/coroutines/experimental/CoroutineContext;)Z
 	public fun scheduleResumeAfterDelay (JLjava/util/concurrent/TimeUnit;Lkotlinx/coroutines/experimental/CancellableContinuation;)V
 	public fun toString ()Ljava/lang/String;
 }

ui/kotlinx-coroutines-android/src/main/kotlin/kotlinx/coroutines/experimental/android/HandlerContext.kt

@@ -16,12 +16,11 @@
 
 package kotlinx.coroutines.experimental.android
 
-import android.os.Handler
-import android.os.Looper
-import android.view.Choreographer
+import android.os.*
+import android.view.*
 import kotlinx.coroutines.experimental.*
-import java.util.concurrent.TimeUnit
-import kotlin.coroutines.experimental.CoroutineContext
+import java.util.concurrent.*
+import kotlin.coroutines.experimental.*
 
 /**
  * Dispatches execution onto Android main UI thread and provides native [delay][Delay.delay] support.
@@ -37,16 +36,41 @@ private const val MAX_DELAY = Long.MAX_VALUE / 2 // cannot delay for too long on
 
 /**
  * Implements [CoroutineDispatcher] on top of an arbitrary Android [Handler].
- * @param handler a handler.
- * @param name an optional name for debugging.
  */
-public class HandlerContext(
+public class HandlerContext private constructor(
     private val handler: Handler,
-    private val name: String? = null
+    private val name: String?,
+    private val invokeImmediately: Boolean
 ) : CoroutineDispatcher(), Delay {
+    /**
+     * Creates [CoroutineDispatcher] for the given Android [handler].
+     *
+     * @param handler a handler.
+     * @param name an optional name for debugging.
+     */
+    public constructor(
+        handler: Handler,
+        name: String? = null
+    ) : this(handler, name, false)
+
+    @Volatile
+    private var _immediate: HandlerContext? = if (invokeImmediately) this else null
+
+    /**
+     * Returns dispatcher that executes coroutines immediately when it is already in the right handler context
+     * (current looper is the same as [handler] looper). See [isDispatchNeeded] documentation on
+     * why this should not be done by default.
+     */
+    public val immediate: HandlerContext = _immediate ?:
+        HandlerContext(handler, name, true).also { _immediate = it }
+
     @Volatile
     private var _choreographer: Choreographer? = null
 
+    override fun isDispatchNeeded(context: CoroutineContext): Boolean {
+        return !invokeImmediately || Looper.myLooper() != handler.looper
+    }
+
     override fun dispatch(context: CoroutineContext, block: Runnable) {
         handler.post(block)
     }