From 755b92b0e92babc025d993dcdbac0046b602f256 Mon Sep 17 00:00:00 2001 From: Ilmir Usmanov Date: Tue, 17 Aug 2021 13:52:50 +0200 Subject: [PATCH] Document coroutines codegen. Remove mentions of experimental coroutines --- .../codegen/coroutines/coroutines-codegen.md | 27 ++----------------- 1 file changed, 2 insertions(+), 25 deletions(-) diff --git a/compiler/backend/src/org/jetbrains/kotlin/codegen/coroutines/coroutines-codegen.md b/compiler/backend/src/org/jetbrains/kotlin/codegen/coroutines/coroutines-codegen.md index 19a42504fb2..bcac00c6e0c 100644 --- a/compiler/backend/src/org/jetbrains/kotlin/codegen/coroutines/coroutines-codegen.md +++ b/compiler/backend/src/org/jetbrains/kotlin/codegen/coroutines/coroutines-codegen.md @@ -13,9 +13,8 @@ If the name of a section of the document has an "Old JVM:" prefix, it explains o then it is JVM_IR back-end specific. If the prefix is common "JVM," the explanation applies to both the old back-end and the new one. Otherwise, the section explains the general behavior of coroutines and shall apply to all back-ends. -The document sticks to release coroutines since we deprecated experimental coroutines in 1.3, and JVM_IR does not support them. However, -some sections explain differences in code generation between release and experimental coroutines wherever appropriate, since we technically -still support them. Sections, which describe experimental coroutines, have a "1.2" prefix. +The document sticks to release coroutines since we deprecated experimental coroutines in 1.3, and JVM_IR does not support them. Furthermore, +experimental coroutines support was dropped from compiler in 1.6. If the current implementation is not ideal (or has a bug), there is a description of the difference, and the steps to implement the "correct" version. These subsections start with "FIXME." @@ -544,14 +543,6 @@ coroutine builder prints it. By the way, `resumeWithException` works in release part): it wraps the exception into `Result` like in a burrito. It passes it to continuation's `resumeWith`. `resume` also wraps the argument into `Result` and passes it to `resumeWith`. -#### 1.2: Data and Exception -Since 1.3 introduced inline classes and `Result` as one of them, experimental coroutines use a different approach to passing value and -exception to `doResume`, which was the name of `invokeSuspend` in experimental coroutines. -Instead of one parameter with type `returnType | COROUTINE_SUSPENDED | Result$Failure(Throwable)`, experimental -coroutines' suspend lambda's `doResume` accepts two parameters: `data` and `exception`. `data` has type `returnType | COROUTINE_SUSPENDED` -and `exception` has type `Throwable`. `resume` and `resumeWithException` used to be methods of `Continuation` interface and in 1.3 they -were replaced by `resumeWith`. `resume` and `resumeWithException` are now extension functions on `Continuation`, which call `resumeWith`. - ### Variables Spilling All the previous examples did not have local variables, and there is a reason for it. When a coroutine suspends, we should save its local variables. Otherwise, when it resumes, the values of them are lost. So, before the suspension, which can be on each suspend call (more @@ -1306,20 +1297,6 @@ That, by the way, is the reason why `SuspendLambda`'s constructor accepts arity. Of course, all generated suspend lambdas implement `SuspendFunction` through `SuspendLambda` and `RestrcitedSuspendLambda`. Callable references to suspend functions implement the interface directly. -#### 1.2: CoroutineImpl -In experimental coroutines, the diagram is much simpler. -```text -+------------+ -|Continuation| -+------+-----+ - ^ - | -+------+------+ -|CoroutineImpl| -+-------------+ -``` -Every suspending function's continuation or suspend lambda extends `CoroutineImpl`. - ### Suspend Lambda Layout The ideal suspend lambda layout is the following: 1. supertypes: `kotlin/coroutines/jvm/internal/SuspendLambda` and `kotlin/jvm/functions/Function{N}`