AbsractCoroutine documentation & some more common (shared) code;

instrincs package is made public.

Author: elizarov

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

@@ -23,10 +23,18 @@ import kotlin.coroutines.experimental.*
 /**
  * Abstract base class for implementation of coroutines in coroutine builders.
  *
- *  * Coroutines implement completion [Continuation], [Job], and [CoroutineScope] interfaces.
- *  * Coroutine stores the result of continuation in the state of the job.
- *  * Coroutine waits for children coroutines to finish before completing.
- *  * Coroutines are cancelled through an intermediate _cancelling_ state.
+ * This class implements completion [Continuation], [Job], and [CoroutineScope] interfaces.
+ * It stores the result of continuation in the state of the job.
+ * This coroutine waits for children coroutines to finish before completing and
+ * is cancelled through an intermediate _cancelling_ state.
+ *
+ * The following methods are available for override:
+ *
+ * * [onStart] is invoked when coroutine is create in not active state and is [started][Job.start].
+ * * [onCancellation] is invoked as soon as coroutine is [cancelled][cancel] (becomes _cancelling_)
+ *   or when it completes for any reason.
+ * * [onCompleted] is invoked when coroutine completes with a value.
+ * * [onCompletedExceptionally] in invoked when coroutines completes with exception.
  *
  * @param parentContext context of the parent coroutine.
  * @param active when `true` (by default) coroutine is created in _active_ state, when `false` in _new_ state.
@@ -47,6 +55,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.
+     * @suppress **This is unstable API and it is subject to change.**
      */
     internal fun initParentJob() {
         initParentJobInternal(parentContext[Job])
@@ -124,7 +133,8 @@ public abstract class AbstractCoroutine<in T>(
     }
 
     /**
-     * Starts the corresponding block as a coroutine with this coroutine start strategy.
+     * Starts this coroutine with the given code [block] and [start] strategy.
+     * This function shall be invoked at most once on this coroutine.
      *
      * 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:
@@ -133,8 +143,6 @@ public abstract class AbstractCoroutine<in T>(
      * * [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()
@@ -143,7 +151,8 @@ public abstract class AbstractCoroutine<in T>(
     }
 
     /**
-     * Starts the corresponding block with receiver as a coroutine with this coroutine start strategy.
+     * Starts this coroutine with the given code [block] and [start] strategy.
+     * This function shall be invoked at most once on this coroutine.
      *
      * 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:
@@ -152,8 +161,6 @@ public abstract class AbstractCoroutine<in T>(
      * * [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()

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

@@ -22,16 +22,15 @@ import kotlin.coroutines.experimental.*
 
 /**
  * Defines start option for coroutines builders.
- * It is used in `start` parameter of [launch], [async], and [actor][kotlinx.coroutines.experimental.channels.actor]
- * coroutine builder functions.
+ * It is used in `start` parameter of [launch], [async], and other coroutine builder functions.
  *
  * The summary of coroutine start options is:
  * * [DEFAULT] -- immediately schedules coroutine for execution according to its context;
  * * [LAZY] -- starts coroutine lazily, only when it is needed;
- * * [ATOMIC] -- atomically (non-cancellably) schedules coroutine for execution according to its context;
+ * * [ATOMIC] -- atomically (in a non-cancellable way) schedules coroutine for execution according to its context;
  * * [UNDISPATCHED] -- immediately executes coroutine until its first suspension point _in the current thread_.
  */
-public actual enum class CoroutineStart {
+public enum class CoroutineStart {
     /**
      * Default -- immediately schedules coroutine for execution according to its context.
      *
@@ -53,16 +52,16 @@ public actual enum class CoroutineStart {
     /**
      * Starts coroutine lazily, only when it is needed.
      *
-     * See the documentation for the corresponding coroutine builders for details:
-     * [launch], [async], and [actor][kotlinx.coroutines.experimental.channels.actor].
+     * See the documentation for the corresponding coroutine builders for details
+     * (like [launch] and [async]).
      *
      * If coroutine [Job] is cancelled before it even had a chance to start executing, then it will not start its
      * execution at all, but complete with an exception.
      */
     LAZY,
 
     /**
-     * Atomically (non-cancellably) schedules coroutine for execution according to its context.
+     * Atomically (in non-cancellable way) schedules coroutine for execution according to its context.
      * This is similar to [DEFAULT], but the coroutine cannot be cancelled before it starts executing.
      *
      * Cancellability of coroutine at suspension points depends on the particular implementation details of
@@ -94,7 +93,7 @@ public actual enum class CoroutineStart {
      * @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>) =
+    public operator fun <T> invoke(block: suspend () -> T, completion: Continuation<T>) =
         when (this) {
             CoroutineStart.DEFAULT -> block.startCoroutineCancellable(completion)
             CoroutineStart.ATOMIC -> block.startCoroutine(completion)
@@ -113,7 +112,7 @@ public actual enum class CoroutineStart {
      * @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>) =
+    public operator fun <R, T> invoke(block: suspend R.() -> T, receiver: R, completion: Continuation<T>) =
         when (this) {
             CoroutineStart.DEFAULT -> block.startCoroutineCancellable(receiver, completion)
             CoroutineStart.ATOMIC -> block.startCoroutine(receiver, completion)
@@ -124,5 +123,5 @@ public actual enum class CoroutineStart {
     /**
      * Returns `true` when [LAZY].
      */
-    public actual val isLazy: Boolean get() = this === LAZY
+    public val isLazy: Boolean get() = this === LAZY
 }

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

@@ -14,22 +14,22 @@
  * limitations under the License.
  */
 
-package kotlinx.coroutines.experimental
+package kotlinx.coroutines.experimental.intrinsics
 
-import kotlin.coroutines.experimental.Continuation
-import kotlin.coroutines.experimental.intrinsics.createCoroutineUnchecked
+import kotlinx.coroutines.experimental.*
+import kotlin.coroutines.experimental.*
+import kotlin.coroutines.experimental.intrinsics.*
 
 /**
  * Use this function to start coroutine in a cancellable way, so that it can be cancelled
  * while waiting to be dispatched.
  */
-internal fun <T> (suspend () -> T).startCoroutineCancellable(completion: Continuation<T>) =
+public fun <T> (suspend () -> T).startCoroutineCancellable(completion: Continuation<T>) =
     createCoroutineUnchecked(completion).resumeCancellable(Unit)
 
 /**
  * Use this function to start coroutine in a cancellable way, so that it can be cancelled
  * while waiting to be dispatched.
  */
-internal fun <R, T> (suspend (R) -> T).startCoroutineCancellable(receiver: R, completion: Continuation<T>) =
+public fun <R, T> (suspend (R) -> T).startCoroutineCancellable(receiver: R, completion: Continuation<T>) =
     createCoroutineUnchecked(receiver, completion).resumeCancellable(Unit)
-

core/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Cancellable.kt renamed to common/kotlinx-coroutines-core-common/src/main/kotlin/kotlinx/coroutines/experimental/intrinsics/Cancellable.kt

@@ -21,12 +21,10 @@ import kotlin.coroutines.experimental.*
 import kotlin.coroutines.experimental.intrinsics.*
 
 /**
- * Use this function to restart coroutine directly from inside of [suspendCoroutine].
- *
- * @suppress **This is unstable API and it is subject to change.**
+ * Use this function to restart coroutine directly from inside of [suspendCoroutine] in the same context.
  */
 @Suppress("PLATFORM_CLASS_MAPPED_TO_KOTLIN", "UNCHECKED_CAST")
-internal fun <T> (suspend () -> T).startCoroutineUndispatched(completion: Continuation<T>) {
+public fun <T> (suspend () -> T).startCoroutineUndispatched(completion: Continuation<T>) {
     val value = try {
         startCoroutineUninterceptedOrReturn(completion)
     } catch (e: Throwable) {
@@ -38,12 +36,10 @@ internal fun <T> (suspend () -> T).startCoroutineUndispatched(completion: Contin
 }
 
 /**
- * Use this function to restart coroutine directly from inside of [suspendCoroutine].
- *
- * @suppress **This is unstable API and it is subject to change.**
+ * Use this function to restart coroutine directly from inside of [suspendCoroutine] in the same context.
  */
 @Suppress("PLATFORM_CLASS_MAPPED_TO_KOTLIN", "UNCHECKED_CAST")
-internal fun <R, T> (suspend (R) -> T).startCoroutineUndispatched(receiver: R, completion: Continuation<T>) {
+public fun <R, T> (suspend (R) -> T).startCoroutineUndispatched(receiver: R, completion: Continuation<T>) {
     val value = try {
         startCoroutineUninterceptedOrReturn(receiver, completion)
     } catch (e: Throwable) {
@@ -55,29 +51,25 @@ internal fun <R, T> (suspend (R) -> T).startCoroutineUndispatched(receiver: R, c
 }
 
 /**
- * Starts the corresponding block as a coroutine with this coroutine start strategy.
+ * Starts this coroutine with the given code [block] in the same context and returns result when it
+ * completes without suspnesion.
+ * This function shall be invoked at most once on this coroutine.
  *
  * 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.
+ * Starts this coroutine with the given code [block] in the same context and returns result when it
+ * completes without suspnesion.
+ * This function shall be invoked at most once on this coroutine.
  *
  * 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()

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

@@ -83,6 +83,10 @@ Channels -- non-blocking primitives for communicating a stream of elements betwe
 
 Select expression to perform multiple suspending operations simultaneously until one of them succeeds.
 
+# Package kotlinx.coroutines.experimental.intrinsics
+
+Low-level primitives for finer-grained control of coroutines.
+
 <!--- MODULE kotlinx-coroutines-core -->
 <!--- INDEX kotlinx.coroutines.experimental -->
 [launch]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/launch.html

core/kotlinx-coroutines-core/README.md

@@ -16,6 +16,7 @@
 
 package kotlinx.coroutines.experimental
 
+import kotlinx.coroutines.experimental.intrinsics.*
 import java.util.concurrent.locks.*
 import kotlin.coroutines.experimental.*
 import kotlin.coroutines.experimental.intrinsics.*

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

@@ -16,6 +16,7 @@
 
 package kotlinx.coroutines.experimental
 
+import kotlinx.coroutines.experimental.intrinsics.*
 import kotlinx.coroutines.experimental.selects.*
 import kotlin.coroutines.experimental.*
 

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

@@ -16,21 +16,13 @@
 
 package kotlinx.coroutines.experimental
 
-import kotlinx.atomicfu.atomic
-import kotlinx.atomicfu.loop
-import kotlinx.coroutines.experimental.internal.LockFreeLinkedListHead
-import kotlinx.coroutines.experimental.internal.LockFreeLinkedListNode
-import kotlinx.coroutines.experimental.internal.OpDescriptor
-import kotlinx.coroutines.experimental.internal.unwrap
-import kotlinx.coroutines.experimental.intrinsics.startCoroutineUndispatched
-import kotlinx.coroutines.experimental.selects.SelectClause0
-import kotlinx.coroutines.experimental.selects.SelectInstance
-import kotlinx.coroutines.experimental.selects.select
-import java.util.concurrent.Future
-import kotlin.coroutines.experimental.Continuation
-import kotlin.coroutines.experimental.CoroutineContext
-import kotlin.coroutines.experimental.buildSequence
-import kotlin.coroutines.experimental.intrinsics.suspendCoroutineOrReturn
+import kotlinx.atomicfu.*
+import kotlinx.coroutines.experimental.internal.*
+import kotlinx.coroutines.experimental.intrinsics.*
+import kotlinx.coroutines.experimental.selects.*
+import java.util.concurrent.*
+import kotlin.coroutines.experimental.*
+import kotlin.coroutines.experimental.intrinsics.*
 
 // --------------- core job interfaces ---------------
 

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

@@ -17,6 +17,7 @@
 package kotlinx.coroutines.experimental.channels
 
 import kotlinx.coroutines.experimental.*
+import kotlinx.coroutines.experimental.intrinsics.*
 import kotlinx.coroutines.experimental.selects.*
 import kotlin.coroutines.experimental.*