Move all coroutine-related declarations from built-ins to stdlib

Also move internal declarations from runtime.jvm module into new package kotlin.coroutines.jvm.internal in stdlib The necessity of these declarations being in built-ins is controversial, but also it will complicate the migration of current coroutine runtime to a separate jar if we ever need this
2017-01-26 12:24:02 +03:00
parent b61c152b4e
commit 0e132b9857
32 changed files with 212 additions and 150 deletions
@@ -0,0 +1,41 @@
+/*
+ * Copyright 2010-2017 JetBrains s.r.o.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package kotlin.coroutines
+
+/**
+ * Marks coroutine context element that intercepts coroutine continuations.
+ * The coroutines framework uses [ContinuationInterceptor.Key] to retrieve the interceptor and
+ * intercepts all coroutine continuations with [interceptContinuation] invocations.
+ */
+@SinceKotlin("1.1")
+public interface ContinuationInterceptor : CoroutineContext.Element {
+    /**
+     * The key that defines *the* context interceptor.
+     */
+    companion object Key : CoroutineContext.Key<ContinuationInterceptor>
+
+    /**
+     * Returns continuation that wraps the original [continuation], thus intercepting all resumptions.
+     * This function is invoked by coroutines framework when needed and the resulting continuations are
+     * cached internally per each instance of the original [continuation].
+     *
+     * By convention, implementations that install themselves as *the* interceptor in the context with
+     * the [Key] shall also scan the context for other element that implement [ContinuationInterceptor] interface
+     * and use their [interceptContinuation] functions, too.
+     */
+    public fun <T> interceptContinuation(continuation: Continuation<T>): Continuation<T>
+}
@@ -0,0 +1,63 @@
+/*
+ * Copyright 2010-2017 JetBrains s.r.o.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package kotlin.coroutines
+
+/**
+ * Persistent context for the coroutine. It is an indexed set of [Element] instances.
+ * An indexed set is a mix between a set and a map.
+ * Every element in this set has a unique [Key].
+ */
+@SinceKotlin("1.1")
+public interface CoroutineContext {
+    /**
+     * Returns the element with the given [key] from this context or `null`.
+     */
+    public operator fun <E : Element> get(key: Key<E>): E?
+
+    /**
+     * Accumulates entries of this context starting with [initial] value and applying [operation]
+     * from left to right to current accumulator value and each element of this context.
+     */
+    public fun <R> fold(initial: R, operation: (R, Element) -> R): R
+
+    /**
+     * Returns a context containing elements from this context and elements from  other [context].
+     * The elements from this context with the same key as in the other one are dropped.
+     */
+    public operator fun plus(context: CoroutineContext): CoroutineContext
+
+    /**
+     * Returns a context containing elements from this context, but without an element with
+     * the specified [key].
+     */
+    public fun minusKey(key: Key<*>): CoroutineContext
+
+    /**
+     * An element of the [CoroutineContext]. An element of the coroutine context is a singleton context by itself.
+     */
+    public interface Element : CoroutineContext {
+        /**
+         * A key of this coroutine context element.
+         */
+        public val key: Key<*>
+    }
+
+    /**
+     * Key for the elements of [CoroutineContext]. [E] is a type of element with this key.
+     */
+    public interface Key<E : Element>
+}
@@ -0,0 +1,49 @@
+/*
+ * Copyright 2010-2016 JetBrains s.r.o.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package kotlin.coroutines
+
+/**
+ * Interface representing a continuation after a suspension point that returns value of type `T`.
+ */
+@SinceKotlin("1.1")
+public interface Continuation<in T> {
+    /**
+     * Context of the coroutine that corresponds to this continuation.
+     */
+    public val context: CoroutineContext
+
+    /**
+     * Resumes the execution of the corresponding coroutine passing [value] as the return value of the last suspension point.
+     */
+    public fun resume(value: T)
+
+    /**
+     * Resumes the execution of the corresponding coroutine so that the [exception] is re-thrown right after the
+     * last suspension point.
+     */
+    public fun resumeWithException(exception: Throwable)
+}
+
+/**
+ * Classes and interfaces marked with this annotation are restricted when used as receivers for extension
+ * `suspend` functions. These `suspend` extensions can only invoke other member or extension `suspend` functions on this particular
+ * receiver only and are restricted from calling arbitrary suspension functions.
+ */
+@SinceKotlin("1.1")
+@Target(AnnotationTarget.CLASS)
+@Retention(AnnotationRetention.BINARY)
+public annotation class RestrictsSuspension
@@ -4,7 +4,8 @@ package kotlin.coroutines

 import java.lang.IllegalStateException
 import java.util.concurrent.atomic.AtomicReferenceFieldUpdater
-import kotlin.coroutines.intrinsics.*
+import kotlin.coroutines.intrinsics.SUSPENDED_MARKER
+import kotlin.coroutines.intrinsics.suspendCoroutineOrReturn

 /**
 * Creates coroutine with receiver type [R] and result type [T].
@@ -17,7 +18,7 @@ import kotlin.coroutines.intrinsics.*
 public fun <R, T> (suspend R.() -> T).createCoroutine(
        receiver: R,
        completion: Continuation<T>
-): Continuation<Unit> = ((this as kotlin.jvm.internal.CoroutineImpl).create(receiver, completion) as kotlin.jvm.internal.CoroutineImpl).facade
+): Continuation<Unit> = ((this as kotlin.coroutines.jvm.internal.CoroutineImpl).create(receiver, completion) as kotlin.coroutines.jvm.internal.CoroutineImpl).facade

 /**
 * Starts coroutine with receiver type [R] and result type [T].
@@ -43,7 +44,7 @@ public fun <R, T> (suspend R.() -> T).startCoroutine(
@Suppress("UNCHECKED_CAST")
 public fun <T> (suspend () -> T).createCoroutine(
        completion: Continuation<T>
-): Continuation<Unit> = ((this as kotlin.jvm.internal.CoroutineImpl).create(completion) as kotlin.jvm.internal.CoroutineImpl).facade
+): Continuation<Unit> = ((this as kotlin.coroutines.jvm.internal.CoroutineImpl).create(completion) as kotlin.coroutines.jvm.internal.CoroutineImpl).facade

 /**
 * Starts coroutine without receiver and with result type [T].
@@ -0,0 +1,79 @@
+/*
+ * Copyright 2010-2017 JetBrains s.r.o.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+@file:JvmVersion
+package kotlin.coroutines.jvm.internal
+
+import java.lang.IllegalStateException
+import kotlin.coroutines.Continuation
+import kotlin.coroutines.ContinuationInterceptor
+import kotlin.coroutines.CoroutineContext
+import kotlin.coroutines.intrinsics.SUSPENDED_MARKER
+import kotlin.jvm.internal.Lambda
+
+abstract class CoroutineImpl(
+        arity: Int,
+        @JvmField
+        protected var completion: Continuation<Any?>?
+) : Lambda(arity), Continuation<Any?> {
+
+    // label == -1 when coroutine cannot be started (it is just a factory object) or has already finished execution
+    // label == 0 in initial part of the coroutine
+    @JvmField
+    protected var label: Int = if (completion != null) 0 else -1
+
+    private val _context: CoroutineContext? = completion?.context
+
+    override val context: CoroutineContext
+        get() = _context!!
+
+    private var _facade: Continuation<Any?>? = null
+
+    val facade: Continuation<Any?> get() {
+        if (_facade == null) _facade = _context!![ContinuationInterceptor]?.interceptContinuation(this) ?: this
+        return _facade!!
+    }
+
+    override fun resume(value: Any?) {
+        try {
+            val result = doResume(value, null)
+            if (result != SUSPENDED_MARKER)
+                completion!!.resume(result)
+        } catch (e: Throwable) {
+            completion!!.resumeWithException(e)
+        }
+    }
+
+    override fun resumeWithException(exception: Throwable) {
+        try {
+            val result = doResume(null, exception)
+            if (result != SUSPENDED_MARKER)
+                completion!!.resume(result)
+        } catch (e: Throwable) {
+            completion!!.resumeWithException(e)
+        }
+    }
+
+    protected abstract fun doResume(data: Any?, exception: Throwable?): Any?
+
+    open fun create(completion: Continuation<*>): Continuation<Unit> {
+        throw IllegalStateException("create(Continuation) has not been overridden")
+    }
+
+    open fun create(value: Any?, completion: Continuation<*>): Continuation<Unit> {
+        throw IllegalStateException("create(Any?;Continuation) has not been overridden")
+    }
+}
@@ -0,0 +1,24 @@
+/*
+ * Copyright 2010-2017 JetBrains s.r.o.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+@file:JvmVersion
+@file:JvmName("CoroutineIntrinsics")
+package kotlin.coroutines.jvm.internal
+
+import kotlin.coroutines.Continuation
+
+fun <T> normalizeContinuation(continuation: Continuation<T>): Continuation<T> =
+        (continuation as? kotlin.coroutines.jvm.internal.CoroutineImpl)?.facade ?: continuation
@@ -0,0 +1,49 @@
+/*
+ * Copyright 2010-2017 JetBrains s.r.o.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+@file:kotlin.jvm.JvmName("IntrinsicsKt")
+
+package kotlin.coroutines.intrinsics
+
+import kotlin.coroutines.Continuation
+
+/**
+ * Obtains the current continuation instance inside suspend functions and either suspend
+ * currently running coroutine or return result immediately without suspension.
+ *
+ * If the [block] returns the special [SUSPENDED_MARKER] value, it means that suspend function did suspend the execution and will
+ * not return any result immediately. In this case, the [Continuation] provided to the [block] shall be invoked at some moment in the
+ * future when the result becomes available to resume the computation.
+ *
+ * Otherwise, the return value of the [block] must have a type assignable to [T] and represents the result of this suspend function.
+ * It means that the execution was not suspended and the [Continuation] provided to the [block] shall not be invoked.
+ * As the result type of the [block] is declared as `Any?` and cannot be correctly type-checked,
+ * its proper return type remains on the conscience of the suspend function's author.
+ *
+ * Note that it is not recommended to call either [Continuation.resume] nor [Continuation.resumeWithException] functions synchronously
+ * in the same stackframe where suspension function is run. Use [suspendCoroutine] as a safer way to obtain current
+ * continuation instance.
+ */
+@SinceKotlin("1.1")
+public inline suspend fun <T> suspendCoroutineOrReturn(crossinline block: (Continuation<T>) -> Any?): T = null!!
+
+/**
+ * This value is used as a return value of [suspendCoroutineOrReturn] `block` argument to state that
+ * the execution was suspended and will not return any result immediately.
+ */
+@SinceKotlin("1.1")
+public val SUSPENDED_MARKER: Any = Any()
+