commonMain.kotlin.coroutines.intrinsics.Intrinsics.kt Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of kotlin-stdlib Show documentation
Show all versions of kotlin-stdlib Show documentation
Kotlin Standard Library for JVM
/*
* Copyright 2010-2020 JetBrains s.r.o. and Kotlin Programming Language contributors.
* Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
*/
@file:kotlin.jvm.JvmName("IntrinsicsKt")
@file:kotlin.jvm.JvmMultifileClass
package kotlin.coroutines.intrinsics
import kotlin.contracts.*
import kotlin.coroutines.*
import kotlin.internal.InlineOnly
/**
* Obtains the current continuation instance inside suspend functions and either suspends
* currently running coroutine or returns result immediately without suspension.
*
* If the [block] returns the special [COROUTINE_SUSPENDED] 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
* resumed by invoking [Continuation.resumeWith] 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.
*
* Invocation of [Continuation.resumeWith] resumes coroutine directly in the invoker's thread without going through the
* [ContinuationInterceptor] that might be present in the coroutine's [CoroutineContext].
* It is the invoker's responsibility to ensure that a proper invocation context is established.
* [Continuation.intercepted] can be used to acquire the intercepted continuation.
*
* 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.3")
@InlineOnly
@Suppress("WRONG_INVOCATION_KIND", "UNUSED_PARAMETER", "RedundantSuspendModifier")
public suspend inline fun suspendCoroutineUninterceptedOrReturn(crossinline block: (Continuation) -> Any?): T {
contract { callsInPlace(block, InvocationKind.EXACTLY_ONCE) }
throw NotImplementedError("Implementation of suspendCoroutineUninterceptedOrReturn is intrinsic")
}
/**
* This value is used as a return value of [suspendCoroutineUninterceptedOrReturn] `block` argument to state that
* the execution was suspended and will not return any result immediately.
*
* **Note: this value should not be used in general code.** Using it outside of the context of
* `suspendCoroutineUninterceptedOrReturn` function return value (including, but not limited to,
* storing this value in other properties, returning it from other functions, etc)
* can lead to unspecified behavior of the code.
*/
// It is implemented as property with getter to avoid ProGuard problem with multifile IntrinsicsKt class
@SinceKotlin("1.3")
public val COROUTINE_SUSPENDED: Any get() = CoroutineSingletons.COROUTINE_SUSPENDED
// Using enum here ensures two important properties:
// 1. It makes SafeContinuation serializable with all kinds of serialization frameworks (since all of them natively support enums)
// 2. It improves debugging experience, since you clearly see toString() value of those objects and what package they come from
@SinceKotlin("1.3")
@PublishedApi // This class is Published API via serialized representation of SafeContinuation, don't rename/move
internal enum class CoroutineSingletons { COROUTINE_SUSPENDED, UNDECIDED, RESUMED }