AbstractCoroutine.start is introduced.

Author: elizarov

common/kotlinx-coroutines-core-common/src/main/kotlin/kotlinx/coroutines/experimental/CommonCoroutineStart.kt

@@ -16,14 +16,16 @@
 
 package kotlinx.coroutines.experimental
 
-import kotlin.coroutines.experimental.Continuation
+import kotlin.coroutines.experimental.*
 
 public expect enum class CoroutineStart {
     DEFAULT,
     LAZY,
     ATOMIC,
     UNDISPATCHED;
+    @Deprecated(message = "Use AbstractCoroutine.start") // todo: make it internal & rename
     public operator fun <T> invoke(block: suspend () -> T, completion: Continuation<T>)
+    @Deprecated(message = "Use AbstractCoroutine.start") // todo: make it internal & rename
     public operator fun <R, T> invoke(block: suspend R.() -> T, receiver: R, completion: Continuation<T>)
     public val isLazy: Boolean
 }

core/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/AbstractCoroutine.kt

@@ -16,6 +16,8 @@
 
 package kotlinx.coroutines.experimental
 
+import kotlinx.coroutines.experimental.CoroutineStart.*
+import kotlinx.coroutines.experimental.intrinsics.*
 import kotlin.coroutines.experimental.*
 
 /**
@@ -46,7 +48,7 @@ public abstract class AbstractCoroutine<in T>(
      * Invocation of this function may cause this coroutine to become cancelled if parent is already cancelled,
      * in which case it synchronously invokes all the corresponding handlers.
      */
-    public fun initParentJob() {
+    internal fun initParentJob() {
         initParentJobInternal(parentContext[Job])
     }
 
@@ -120,5 +122,43 @@ public abstract class AbstractCoroutine<in T>(
         val coroutineName = context.coroutineName ?: return super.nameString()
         return "\"$coroutineName\":${super.nameString()}"
     }
+
+    /**
+     * Starts the corresponding block as a coroutine with this coroutine start strategy.
+     *
+     * First, this function initializes parent job from the `parentContext` of this coroutine that was passed to it
+     * during construction. Second, it starts the coroutine based on [start] parameter:
+     *
+     * * [DEFAULT] uses [startCoroutineCancellable].
+     * * [ATOMIC] uses [startCoroutine].
+     * * [UNDISPATCHED] uses [startCoroutineUndispatched].
+     * * [LAZY] does nothing.
+     *
+     * This function shall be invoked at most once.
+     */
+    public fun start(start: CoroutineStart, block: suspend () -> T) {
+        initParentJob()
+        @Suppress("DEPRECATION")
+        start(block, this)
+    }
+
+    /**
+     * Starts the corresponding block with receiver as a coroutine with this coroutine start strategy.
+     *
+     * First, this function initializes parent job from the `parentContext` of this coroutine that was passed to it
+     * during construction. Second, it starts the coroutine based on [start] parameter:
+     * 
+     * * [DEFAULT] uses [startCoroutineCancellable].
+     * * [ATOMIC] uses [startCoroutine].
+     * * [UNDISPATCHED] uses [startCoroutineUndispatched].
+     * * [LAZY] does nothing.
+     *
+     * This function shall be invoked at most once.
+     */
+    public fun <R> start(start: CoroutineStart, receiver: R, block: suspend R.() -> T) {
+        initParentJob()
+        @Suppress("DEPRECATION")
+        start(block, receiver, this)
+    }
 }
 

core/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Builders.kt

@@ -16,10 +16,9 @@
 
 package kotlinx.coroutines.experimental
 
-import java.util.concurrent.locks.LockSupport
+import java.util.concurrent.locks.*
 import kotlin.coroutines.experimental.*
-import kotlin.coroutines.experimental.intrinsics.startCoroutineUninterceptedOrReturn
-import kotlin.coroutines.experimental.intrinsics.suspendCoroutineOrReturn
+import kotlin.coroutines.experimental.intrinsics.*
 
 // --------------- basic coroutine builders ---------------
 
@@ -62,8 +61,7 @@ public actual fun launch(
     val coroutine = if (start.isLazy)
         LazyStandaloneCoroutine(newContext, block) else
         StandaloneCoroutine(newContext, active = true)
-    coroutine.initParentJob()
-    start(block, coroutine, coroutine)
+    coroutine.start(start, coroutine, block)
     return coroutine
 }
 
@@ -127,6 +125,7 @@ public actual suspend fun <T> withContext(
         delegate = cont,
         resumeMode = if (start == CoroutineStart.ATOMIC) MODE_ATOMIC_DEFAULT else MODE_CANCELLABLE)
     completion.initParentJobInternal(newContext[Job]) // attach to job
+    @Suppress("DEPRECATION")
     start(block, completion)
     completion.getResult()
 }
@@ -169,8 +168,7 @@ public fun <T> runBlocking(context: CoroutineContext = EmptyCoroutineContext, bl
     val eventLoop = if (context[ContinuationInterceptor] == null) BlockingEventLoop(currentThread) else null
     val newContext = newCoroutineContext(context + (eventLoop ?: EmptyCoroutineContext))
     val coroutine = BlockingCoroutine<T>(newContext, currentThread, privateEventLoop = eventLoop != null)
-    coroutine.initParentJob()
-    block.startCoroutine(coroutine, coroutine)
+    coroutine.start(CoroutineStart.DEFAULT, coroutine, block)
     return coroutine.joinBlocking()
 }
 

core/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/CoroutineStart.kt

@@ -17,9 +17,8 @@
 package kotlinx.coroutines.experimental
 
 import kotlinx.coroutines.experimental.CoroutineStart.*
-import kotlinx.coroutines.experimental.intrinsics.startCoroutineUndispatched
-import kotlin.coroutines.experimental.Continuation
-import kotlin.coroutines.experimental.startCoroutine
+import kotlinx.coroutines.experimental.intrinsics.*
+import kotlin.coroutines.experimental.*
 
 /**
  * Defines start option for coroutines builders.
@@ -91,7 +90,10 @@ public actual enum class CoroutineStart {
      * * [ATOMIC] uses [startCoroutine].
      * * [UNDISPATCHED] uses [startCoroutineUndispatched].
      * * [LAZY] does nothing.
+     *
+     * @suppress **Deprecated**: Use [AbstractCoroutine.start]
      */
+    @Deprecated(message = "Use AbstractCoroutine.start") // todo: make it internal & rename
     public actual operator fun <T> invoke(block: suspend () -> T, completion: Continuation<T>) =
         when (this) {
             CoroutineStart.DEFAULT -> block.startCoroutineCancellable(completion)
@@ -107,7 +109,10 @@ public actual enum class CoroutineStart {
      * * [ATOMIC] uses [startCoroutine].
      * * [UNDISPATCHED] uses [startCoroutineUndispatched].
      * * [LAZY] does nothing.
+     *
+     * @suppress **Deprecated**: Use [AbstractCoroutine.start]
      */
+    @Deprecated(message = "Use AbstractCoroutine.start") // todo: make it internal & rename
     public actual operator fun <R, T> invoke(block: suspend R.() -> T, receiver: R, completion: Continuation<T>) =
         when (this) {
             CoroutineStart.DEFAULT -> block.startCoroutineCancellable(receiver, completion)

core/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Deferred.kt

@@ -17,8 +17,7 @@
 package kotlinx.coroutines.experimental
 
 import kotlinx.coroutines.experimental.selects.*
-import kotlin.coroutines.experimental.ContinuationInterceptor
-import kotlin.coroutines.experimental.CoroutineContext
+import kotlin.coroutines.experimental.*
 
 /**
  * Deferred value is a non-blocking cancellable future.
@@ -167,8 +166,7 @@ public actual fun <T> async(
     val coroutine = if (start.isLazy)
         LazyDeferredCoroutine(newContext, block) else
         DeferredCoroutine<T>(newContext, active = true)
-    coroutine.initParentJob()
-    start(block, coroutine, coroutine)
+    coroutine.start(start, coroutine, block)
     return coroutine
 }
 

core/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Scheduled.kt

@@ -16,13 +16,11 @@
 
 package kotlinx.coroutines.experimental
 
-import kotlinx.coroutines.experimental.selects.SelectBuilder
-import kotlinx.coroutines.experimental.selects.select
-import java.util.concurrent.TimeUnit
-import kotlin.coroutines.experimental.Continuation
-import kotlin.coroutines.experimental.intrinsics.COROUTINE_SUSPENDED
-import kotlin.coroutines.experimental.intrinsics.startCoroutineUninterceptedOrReturn
-import kotlin.coroutines.experimental.intrinsics.suspendCoroutineOrReturn
+import kotlinx.coroutines.experimental.intrinsics.*
+import kotlinx.coroutines.experimental.selects.*
+import java.util.concurrent.*
+import kotlin.coroutines.experimental.*
+import kotlin.coroutines.experimental.intrinsics.*
 
 /**
  * Runs a given suspending [block] of code inside a coroutine with a specified timeout and throws
@@ -78,21 +76,9 @@ private fun <U, T: U> setupTimeout(
     val cont = coroutine.cont
     val context = cont.context
     coroutine.disposeOnCompletion(context.delay.invokeOnTimeout(coroutine.time, coroutine.unit, coroutine))
-    coroutine.initParentJob()
     // restart block using new coroutine with new job,
     // however start it as undispatched coroutine, because we are already in the proper context
-    val result = try {
-        block.startCoroutineUninterceptedOrReturn(receiver = coroutine, completion = coroutine)
-    } catch (e: Throwable) {
-        CompletedExceptionally(e)
-    }
-    return when {
-        result == COROUTINE_SUSPENDED -> COROUTINE_SUSPENDED
-        coroutine.makeCompletingOnce(result, MODE_IGNORE) -> {
-            if (result is CompletedExceptionally) throw result.exception else result
-        }
-        else -> COROUTINE_SUSPENDED
-    }
+    return coroutine.startUndispatchedOrReturn(coroutine, block)
 }
 
 /**

core/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/channels/Actor.kt

@@ -17,10 +17,8 @@
 package kotlinx.coroutines.experimental.channels
 
 import kotlinx.coroutines.experimental.*
-import kotlinx.coroutines.experimental.selects.SelectClause2
-import kotlinx.coroutines.experimental.selects.SelectInstance
-import kotlin.coroutines.experimental.ContinuationInterceptor
-import kotlin.coroutines.experimental.CoroutineContext
+import kotlinx.coroutines.experimental.selects.*
+import kotlin.coroutines.experimental.*
 
 /**
  * Scope for [actor] coroutine builder.
@@ -94,8 +92,7 @@ public fun <E> actor(
     val coroutine = if (start.isLazy)
         LazyActorCoroutine(newContext, channel, block) else
         ActorCoroutine(newContext, channel, active = true)
-    coroutine.initParentJob()
-    start(block, coroutine, coroutine)
+    coroutine.start(start, coroutine, block)
     return coroutine
 }
 

core/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/channels/Produce.kt

@@ -17,9 +17,7 @@
 package kotlinx.coroutines.experimental.channels
 
 import kotlinx.coroutines.experimental.*
-import kotlin.coroutines.experimental.ContinuationInterceptor
-import kotlin.coroutines.experimental.CoroutineContext
-import kotlin.coroutines.experimental.startCoroutine
+import kotlin.coroutines.experimental.*
 
 /**
  * Scope for [produce] coroutine builder.
@@ -83,8 +81,7 @@ public fun <E> produce(
     val channel = Channel<E>(capacity)
     val newContext = newCoroutineContext(context, parent)
     val coroutine = ProducerCoroutine(newContext, channel)
-    coroutine.initParentJob()
-    block.startCoroutine(coroutine, coroutine)
+    coroutine.start(CoroutineStart.DEFAULT, coroutine, block)
     return coroutine
 }
 

core/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/intrinsics/Undispatched.kt

@@ -16,12 +16,9 @@
 
 package kotlinx.coroutines.experimental.intrinsics
 
-import kotlinx.coroutines.experimental.resumeCancellable
-import kotlin.coroutines.experimental.Continuation
-import kotlin.coroutines.experimental.createCoroutine
-import kotlin.coroutines.experimental.intrinsics.COROUTINE_SUSPENDED
-import kotlin.coroutines.experimental.intrinsics.startCoroutineUninterceptedOrReturn
-import kotlin.coroutines.experimental.suspendCoroutine
+import kotlinx.coroutines.experimental.*
+import kotlin.coroutines.experimental.*
+import kotlin.coroutines.experimental.intrinsics.*
 
 /**
  * Use this function to restart coroutine directly from inside of [suspendCoroutine].
@@ -56,3 +53,48 @@ internal fun <R, T> (suspend (R) -> T).startCoroutineUndispatched(receiver: R, c
     if (value !== COROUTINE_SUSPENDED)
         completion.resume(value as T)
 }
+
+/**
+ * Starts the corresponding block as a coroutine with this coroutine start strategy.
+ *
+ * First, this function initializes parent job from the `parentContext` of this coroutine that was passed to it
+ * during construction. Second, it starts the coroutine using [startCoroutineUninterceptedOrReturn].
+ *
+ * This function shall be invoked at most once.
+ *
+ * @suppress **This is unstable API and it is subject to change.**
+ */
+public fun <T> AbstractCoroutine<T>.startUndispatchedOrReturn(block: suspend () -> T): Any? {
+    initParentJob()
+    return undispatchedResult { block.startCoroutineUninterceptedOrReturn(this) }
+}
+
+/**
+ * Starts the corresponding block with receiver as a coroutine with this coroutine start strategy.
+ *
+ * First, this function initializes parent job from the `parentContext` of this coroutine that was passed to it
+ * during construction. Second, it starts the coroutine using [startCoroutineUninterceptedOrReturn].
+ *
+ * This function shall be invoked at most once.
+ * 
+ * @suppress **This is unstable API and it is subject to change.**
+ */
+public fun <T, R> AbstractCoroutine<T>.startUndispatchedOrReturn(receiver: R, block: suspend R.() -> T): Any? {
+    initParentJob()
+    return undispatchedResult { block.startCoroutineUninterceptedOrReturn(receiver, this) }
+}
+
+private inline fun <T> AbstractCoroutine<T>.undispatchedResult(startBlock: () -> Any?): Any? {
+    val result = try {
+        startBlock()
+    } catch (e: Throwable) {
+        CompletedExceptionally(e)
+    }
+    return when {
+        result == COROUTINE_SUSPENDED -> COROUTINE_SUSPENDED
+        makeCompletingOnce(result, MODE_IGNORE) -> {
+            if (result is CompletedExceptionally) throw result.exception else result
+        }
+        else -> COROUTINE_SUSPENDED
+    }
+}

core/kotlinx-coroutines-io/src/main/kotlin/kotlinx/coroutines/experimental/io/ReaderJob.kt

@@ -1,10 +1,7 @@
 package kotlinx.coroutines.experimental.io
 
-import kotlinx.coroutines.experimental.CoroutineScope
-import kotlinx.coroutines.experimental.Job
-import kotlinx.coroutines.experimental.newCoroutineContext
-import kotlin.coroutines.experimental.CoroutineContext
-import kotlin.coroutines.experimental.startCoroutine
+import kotlinx.coroutines.experimental.*
+import kotlin.coroutines.experimental.*
 
 /**
  * A coroutine job that is reading from a byte channel
@@ -26,8 +23,7 @@ fun reader(coroutineContext: CoroutineContext,
            block: suspend ReaderScope.() -> Unit): ReaderJob {
     val newContext = newCoroutineContext(coroutineContext, parent)
     val coroutine = ReaderCoroutine(newContext, channel)
-    coroutine.initParentJob()
-    block.startCoroutine(coroutine, coroutine)
+    coroutine.start(CoroutineStart.DEFAULT, coroutine, block)
     return coroutine
 }