From 709a28060f6bb01c21e66d0c3fa990cc90c2a9e1 Mon Sep 17 00:00:00 2001 From: Ilya Gorbunov Date: Sun, 21 Oct 2018 22:31:07 +0300 Subject: [PATCH] Unify coroutine intrinsic docs --- .../src/kotlin/CoroutinesIntrinsicsH.kt | 25 +++++++++++++++++-- .../coroutines/intrinsics/IntrinsicsJs.kt | 20 +++++++++++++-- 2 files changed, 41 insertions(+), 4 deletions(-) diff --git a/libraries/stdlib/coroutines/common/src/kotlin/CoroutinesIntrinsicsH.kt b/libraries/stdlib/coroutines/common/src/kotlin/CoroutinesIntrinsicsH.kt index e7c4117822e..c52d96923f7 100644 --- a/libraries/stdlib/coroutines/common/src/kotlin/CoroutinesIntrinsicsH.kt +++ b/libraries/stdlib/coroutines/common/src/kotlin/CoroutinesIntrinsicsH.kt @@ -6,12 +6,19 @@ package kotlin.coroutines.intrinsics import kotlin.coroutines.Continuation +import kotlin.coroutines.ContinuationInterceptor +import kotlin.coroutines.CoroutineContext /** * Starts unintercepted coroutine without receiver and with result type [T] and executes it until its first suspension. * Returns the result of the coroutine or throws its exception if it does not suspend or [COROUTINE_SUSPENDED] if it suspends. * In the later case, the [completion] continuation is invoked when coroutine completes with result or exception. - * This function is designed to be used from inside of [suspendCoroutineOrReturn] to resume the execution of suspended + * + * The coroutine is started directly in the invoker's thread without going through the [ContinuationInterceptor] that might + * be present in the completion's [CoroutineContext]. It is invoker's responsibility to ensure that the proper invocation + * context is established. + * + * This function is designed to be used from inside of [suspendCoroutineUninterceptedOrReturn] to resume the execution of suspended * coroutine using a reference to the suspending function. */ @SinceKotlin("1.3") @@ -23,7 +30,12 @@ public expect inline fun (suspend () -> T).startCoroutineUninterceptedOrRetu * Starts unintercepted coroutine with receiver type [R] and result type [T] and executes it until its first suspension. * Returns the result of the coroutine or throws its exception if it does not suspend or [COROUTINE_SUSPENDED] if it suspends. * In the later case, the [completion] continuation is invoked when coroutine completes with result or exception. - * This function is designed to be used from inside of [suspendCoroutineOrReturn] to resume the execution of suspended + * + * The coroutine is started directly in the invoker's thread without going through the [ContinuationInterceptor] that might + * be present in the completion's [CoroutineContext]. It is invoker's responsibility to ensure that the proper invocation + * context is established. + * + * This function is designed to be used from inside of [suspendCoroutineUninterceptedOrReturn] to resume the execution of suspended * coroutine using a reference to the suspending function. */ @SinceKotlin("1.3") @@ -43,5 +55,14 @@ public expect fun (suspend R.() -> T).createCoroutineUnintercepted( completion: Continuation ): Continuation +/** + * Intercepts this continuation with [ContinuationInterceptor]. + * + * This function shall be used on the immediate result of [createCoroutineUnintercepted] or [suspendCoroutineUninterceptedOrReturn], + * in which case it checks for [ContinuationInterceptor] in the continuation's [context][Continuation.context], + * invokes [ContinuationInterceptor.interceptContinuation], caches and returns result. + * + * If this function is invoked on other [Continuation] instances it returns `this` continuation unchanged. + */ @SinceKotlin("1.3") public expect fun Continuation.intercepted(): Continuation diff --git a/libraries/stdlib/coroutines/js/src/kotlin/coroutines/intrinsics/IntrinsicsJs.kt b/libraries/stdlib/coroutines/js/src/kotlin/coroutines/intrinsics/IntrinsicsJs.kt index 02054e9ef10..0c503d4b368 100644 --- a/libraries/stdlib/coroutines/js/src/kotlin/coroutines/intrinsics/IntrinsicsJs.kt +++ b/libraries/stdlib/coroutines/js/src/kotlin/coroutines/intrinsics/IntrinsicsJs.kt @@ -54,10 +54,15 @@ public actual inline fun (suspend R.() -> T).startCoroutineUninterceptedO * The [completion] continuation is invoked when coroutine completes with result or exception. * * This function returns unintercepted continuation. - * Invocation of `resume(Unit)` starts coroutine directly in the invoker's thread without going through the + * Invocation of `resume(Unit)` starts coroutine immediately in the invoker's call stack without going through the * [ContinuationInterceptor] that might be present in the completion's [CoroutineContext]. * It is invoker's responsibility to ensure that the proper invocation context is established. + * Note that [completion] of this function may get invoked in an arbitrary context. + * * [Continuation.intercepted] can be used to acquire the intercepted continuation. + * Invocation of `resume(Unit)` on intercepted continuation guarantees that execution of + * both the coroutine and [completion] happens in the invocation context established by + * [ContinuationInterceptor]. * * Repeated invocation of any resume function on the resulting continuation corrupts the * state machine of the coroutine and may result in arbitrary behaviour or exception. @@ -84,10 +89,15 @@ public actual fun (suspend () -> T).createCoroutineUnintercepted( * The [completion] continuation is invoked when coroutine completes with result or exception. * * This function returns unintercepted continuation. - * Invocation of `resume(Unit)` starts coroutine directly in the invoker's thread without going through the + * Invocation of `resume(Unit)` starts coroutine immediately in the invoker's call stack without going through the * [ContinuationInterceptor] that might be present in the completion's [CoroutineContext]. * It is invoker's responsibility to ensure that the proper invocation context is established. + * Note that [completion] of this function may get invoked in an arbitrary context. + * * [Continuation.intercepted] can be used to acquire the intercepted continuation. + * Invocation of `resume(Unit)` on intercepted continuation guarantees that execution of + * both the coroutine and [completion] happens in the invocation context established by + * [ContinuationInterceptor]. * * Repeated invocation of any resume function on the resulting continuation corrupts the * state machine of the coroutine and may result in arbitrary behaviour or exception. @@ -109,6 +119,12 @@ public actual fun (suspend R.() -> T).createCoroutineUnintercepted( /** * Intercepts this continuation with [ContinuationInterceptor]. + * + * This function shall be used on the immediate result of [createCoroutineUnintercepted] or [suspendCoroutineUninterceptedOrReturn], + * in which case it checks for [ContinuationInterceptor] in the continuation's [context][Continuation.context], + * invokes [ContinuationInterceptor.interceptContinuation], caches and returns result. + * + * If this function is invoked on other [Continuation] instances it returns `this` continuation unchanged. */ @SinceKotlin("1.3") public actual fun Continuation.intercepted(): Continuation =