From c1f504eaef4a18a5f74ab4d1edaceccfd8c1176c Mon Sep 17 00:00:00 2001 From: "andrei.ezerskii" Date: Mon, 23 Sep 2024 18:55:49 +0200 Subject: [PATCH 1/8] 1. apply migration script --- docs/cfg/buildprofiles.xml | 15 +- docs/kc.tree | 44 ++--- docs/project.ihp | 14 -- docs/topics/cancellation-and-timeouts.md | 42 ++--- docs/topics/channels.md | 42 ++--- docs/topics/composing-suspending-functions.md | 28 +-- .../coroutine-context-and-dispatchers.md | 52 +++--- docs/topics/coroutines-and-channels.md | 48 ++--- docs/topics/coroutines-basics.md | 24 +-- docs/topics/debug-coroutines-with-idea.md | 2 +- docs/topics/debug-flow-with-idea.md | 2 +- docs/topics/exception-handling.md | 44 ++--- docs/topics/flow.md | 166 +++++++++--------- docs/topics/select-expression.md | 22 +-- .../shared-mutable-state-and-concurrency.md | 24 +-- docs/writerside.cfg | 14 ++ 16 files changed, 288 insertions(+), 295 deletions(-) delete mode 100644 docs/project.ihp create mode 100644 docs/writerside.cfg diff --git a/docs/cfg/buildprofiles.xml b/docs/cfg/buildprofiles.xml index d4a99434cd..c58779f1f8 100644 --- a/docs/cfg/buildprofiles.xml +++ b/docs/cfg/buildprofiles.xml @@ -1,10 +1,9 @@ - - - true - https://github.com/Kotlin/kotlinx.coroutines/edit/master/docs/ - true - - - + + true + https://github.com/Kotlin/kotlinx.coroutines/edit/master/docs/ + true + + + \ No newline at end of file diff --git a/docs/kc.tree b/docs/kc.tree index 9fa1e11307..0ee8a4ce10 100644 --- a/docs/kc.tree +++ b/docs/kc.tree @@ -1,25 +1,19 @@ - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + diff --git a/docs/project.ihp b/docs/project.ihp deleted file mode 100644 index d8da718e83..0000000000 --- a/docs/project.ihp +++ /dev/null @@ -1,14 +0,0 @@ - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/topics/cancellation-and-timeouts.md b/docs/topics/cancellation-and-timeouts.md index c574e12624..1887a1ea12 100644 --- a/docs/topics/cancellation-and-timeouts.md +++ b/docs/topics/cancellation-and-timeouts.md @@ -32,9 +32,9 @@ fun main() = runBlocking { ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3"} -> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-01.kt). +> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-cancel-01.kt). > -{type="note"} +{style="note"} It produces the following output: @@ -86,9 +86,9 @@ fun main() = runBlocking { ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3"} -> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-02.kt). +> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-cancel-02.kt). > -{type="note"} +{style="note"} Run it to see that it continues to print "I'm sleeping" even after cancellation until the job completes by itself after five iterations. @@ -131,9 +131,9 @@ fun main() = runBlocking { ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3"} -> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-03.kt). +> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-cancel-03.kt). > -{type="note"} +{style="note"} While catching `Exception` is an anti-pattern, this issue may surface in more subtle ways, like when using the [`runCatching`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/run-catching.html) function, @@ -173,9 +173,9 @@ fun main() = runBlocking { ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3"} -> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-04.kt). +> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-cancel-04.kt). > -{type="note"} +{style="note"} As you can see, now this loop is cancelled. [isActive] is an extension property available inside the coroutine via the [CoroutineScope] object. @@ -218,9 +218,9 @@ fun main() = runBlocking { ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3"} -> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-05.kt). +> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-cancel-05.kt). > -{type="note"} +{style="note"} Both [join][Job.join] and [cancelAndJoin] wait for all finalization actions to complete, so the example above produces the following output: @@ -273,9 +273,9 @@ fun main() = runBlocking { ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3"} -> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-06.kt). +> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-cancel-06.kt). > -{type="note"} +{style="note"} @@ -428,7 +428,7 @@ of your machine. You may need to tweak the timeout in this example to actually s > since it always happens from the same thread, the one used by `runBlocking`. > More on that will be explained in the chapter on coroutine context. > -{type="note"} +{style="note"} To work around this problem you can store a reference to the resource in a variable instead of returning it from the `withTimeout` block. @@ -468,9 +468,9 @@ fun main() { ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3"} -> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-10.kt). +> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-cancel-10.kt). > -{type="note"} +{style="note"} This example always prints zero. Resources do not leak. diff --git a/docs/topics/channels.md b/docs/topics/channels.md index 402fb5a170..6b447713df 100644 --- a/docs/topics/channels.md +++ b/docs/topics/channels.md @@ -31,9 +31,9 @@ fun main() = runBlocking { ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3"} -> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-channel-01.kt). +> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-channel-01.kt). > -{type="note"} +{style="note"} The output of this code is: @@ -77,9 +77,9 @@ fun main() = runBlocking { ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3"} -> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-channel-02.kt). +> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-channel-02.kt). > -{type="note"} +{style="note"} diff --git a/docs/topics/debug-coroutines-with-idea.md b/docs/topics/debug-coroutines-with-idea.md index b31aa79f51..a3e4b28aae 100644 --- a/docs/topics/debug-coroutines-with-idea.md +++ b/docs/topics/debug-coroutines-with-idea.md @@ -113,4 +113,4 @@ You can disable this behavior with the `-Xdebug` compiler option. > __Never use this flag in production__: `-Xdebug` can [cause memory leaks](https://youtrack.jetbrains.com/issue/KT-48678/Coroutine-debugger-disable-was-optimised-out-compiler-feature#focus=Comments-27-6015585.0-0). > -{type="warning"} \ No newline at end of file +{style="warning"} \ No newline at end of file diff --git a/docs/topics/debug-flow-with-idea.md b/docs/topics/debug-flow-with-idea.md index 0aa78b1780..53521fbf39 100644 --- a/docs/topics/debug-flow-with-idea.md +++ b/docs/topics/debug-flow-with-idea.md @@ -114,7 +114,7 @@ You can disable this behavior with the `-Xdebug` compiler option. > __Never use this flag in production__: `-Xdebug` can [cause memory leaks](https://youtrack.jetbrains.com/issue/KT-48678/Coroutine-debugger-disable-was-optimised-out-compiler-feature#focus=Comments-27-6015585.0-0). > -{type="warning"} +{style="warning"} ## Add a concurrently running coroutine diff --git a/docs/topics/exception-handling.md b/docs/topics/exception-handling.md index f79740c95f..507d773509 100644 --- a/docs/topics/exception-handling.md +++ b/docs/topics/exception-handling.md @@ -23,7 +23,7 @@ It can be demonstrated by a simple example that creates root coroutines using th > whole application is one of the rare legitimate uses for `GlobalScope`, so you must explicitly opt-in into > using `GlobalScope` with `@OptIn(DelicateCoroutinesApi::class)`. > -{type="note"} +{style="note"} ```kotlin import kotlinx.coroutines.* @@ -52,9 +52,9 @@ fun main() = runBlocking { ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3"} -> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-exceptions-01.kt). +> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-exceptions-01.kt). > -{type="note"} +{style="note"} The output of this code is (with [debug](https://github.com/Kotlin/kotlinx.coroutines/blob/master/docs/coroutine-context-and-dispatchers.md#debugging-coroutines-and-threads)): @@ -89,7 +89,7 @@ so its `CoroutineExceptionHandler` has no effect either. > Coroutines running in supervision scope do not propagate exceptions to their parent and are > excluded from this rule. A further [Supervision](#supervision) section of this document gives more details. > -{type="note"} +{style="note"} ```kotlin import kotlinx.coroutines.* @@ -112,9 +112,9 @@ fun main() = runBlocking { ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3"} -> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-exceptions-02.kt). +> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-exceptions-02.kt). > -{type="note"} +{style="note"} The output of this code is: @@ -157,9 +157,9 @@ fun main() = runBlocking { ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3"} -> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-exceptions-03.kt). +> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-exceptions-03.kt). > -{type="note"} +{style="note"} The output of this code is: @@ -181,7 +181,7 @@ This behaviour cannot be overridden and is used to provide stable coroutines hie > is launched in the scope of the main [runBlocking], since the main coroutine is going to be always cancelled > when its child completes with exception despite the installed handler. > -{type="note"} +{style="note"} The original exception is handled by the parent only when all its children terminate, which is demonstrated by the following example. @@ -219,9 +219,9 @@ fun main() = runBlocking { ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3"} -> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-exceptions-04.kt). +> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-exceptions-04.kt). > -{type="note"} +{style="note"} The output of this code is: @@ -272,9 +272,9 @@ fun main() = runBlocking { ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3"} -> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-exceptions-05.kt). +> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-exceptions-05.kt). > -{type="note"} +{style="note"} The output of this code is: @@ -287,7 +287,7 @@ CoroutineExceptionHandler got java.io.IOException with suppressed [java.lang.Ari > Note that this mechanism currently only works on Java version 1.7+. > The JS and Native restrictions are temporary and will be lifted in the future. > -{type="note"} +{style="note"} Cancellation exceptions are transparent and are unwrapped by default: @@ -322,9 +322,9 @@ fun main() = runBlocking { ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3"} -> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-exceptions-06.kt). +> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-exceptions-06.kt). > -{type="note"} +{style="note"} The output of this code is: @@ -388,9 +388,9 @@ fun main() = runBlocking { ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3"} -> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-supervision-01.kt). +> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-supervision-01.kt). > -{type="note"} +{style="note"} The output of this code is: @@ -438,9 +438,9 @@ fun main() = runBlocking { ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3"} -> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-supervision-02.kt). +> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-supervision-02.kt). > -{type="note"} +{style="note"} The output of this code is: @@ -484,9 +484,9 @@ fun main() = runBlocking { ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3"} -> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-supervision-03.kt). +> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-supervision-03.kt). > -{type="note"} +{style="note"} The output of this code is: diff --git a/docs/topics/flow.md b/docs/topics/flow.md index c436c2cfc9..08fe164a33 100644 --- a/docs/topics/flow.md +++ b/docs/topics/flow.md @@ -20,9 +20,9 @@ fun main() { ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3"} -> You can get the full code from [here](../../kotlinx-coroutines-core/jvm/test/guide/example-flow-01.kt). +> You can get the full code from [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-flow-01.kt). > -{type="note"} +{style="note"} This code outputs: @@ -53,9 +53,9 @@ fun main() { ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3"} -> You can get the full code from [here](../../kotlinx-coroutines-core/jvm/test/guide/example-flow-02.kt). +> You can get the full code from [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-flow-02.kt). > -{type="note"} +{style="note"} This code outputs the same numbers, but it waits 100ms before printing each one. @@ -87,9 +87,9 @@ fun main() = runBlocking { ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3"} -> You can get the full code from [here](../../kotlinx-coroutines-core/jvm/test/guide/example-flow-03.kt). +> You can get the full code from [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-flow-03.kt). > -{type="note"} +{style="note"} This code prints the numbers after waiting for a second. @@ -131,9 +131,9 @@ fun main() = runBlocking { ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3"} -> You can get the full code from [here](../../kotlinx-coroutines-core/jvm/test/guide/example-flow-04.kt). +> You can get the full code from [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-flow-04.kt). > -{type="note"} +{style="note"} This code waits 100ms before printing each number without blocking the main thread. This is verified by printing "I'm not blocked" every 100ms from a separate coroutine that is running in the main thread: @@ -160,7 +160,7 @@ Notice the following differences in the code with the [Flow] from the earlier ex > We can replace [delay] with `Thread.sleep` in the body of `simple`'s `flow { ... }` and see that the main > thread is blocked in this case. > -{type="note"} +{style="note"} ## Flows are cold @@ -192,9 +192,9 @@ fun main() = runBlocking { ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3"} -> You can get the full code from [here](../../kotlinx-coroutines-core/jvm/test/guide/example-flow-05.kt). +> You can get the full code from [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-flow-05.kt). > -{type="note"} +{style="note"} Which prints: @@ -248,9 +248,9 @@ fun main() = runBlocking { ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3"} -> You can get the full code from [here](../../kotlinx-coroutines-core/jvm/test/guide/example-flow-06.kt). +> You can get the full code from [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-flow-06.kt). > -{type="note"} +{style="note"} Notice how only two numbers get emitted by the flow in the `simple` function, producing the following output: @@ -289,9 +289,9 @@ fun main() = runBlocking { ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3"} -> You can get the full code from [here](../../kotlinx-coroutines-core/jvm/test/guide/example-flow-07.kt). +> You can get the full code from [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-flow-07.kt). > -{type="note"} +{style="note"} +https://github.com/Kotlin/kotlinx.coroutines/edit/master/docs/topics/ [//]: # (title: Cancellation and timeouts) diff --git a/docs/topics/channels.md b/docs/topics/channels.md index 79b72869d4..8c7d593d45 100644 --- a/docs/topics/channels.md +++ b/docs/topics/channels.md @@ -1,4 +1,5 @@ +https://github.com/Kotlin/kotlinx.coroutines/edit/master/docs/topics/ [//]: # (title: Channels) diff --git a/docs/topics/composing-suspending-functions.md b/docs/topics/composing-suspending-functions.md index 3218b2a20d..69a01c52e4 100644 --- a/docs/topics/composing-suspending-functions.md +++ b/docs/topics/composing-suspending-functions.md @@ -1,4 +1,5 @@ +https://github.com/Kotlin/kotlinx.coroutines/edit/master/docs/topics/ [//]: # (title: Composing suspending functions) diff --git a/docs/topics/coroutine-context-and-dispatchers.md b/docs/topics/coroutine-context-and-dispatchers.md index 460ad436d0..3e42edb38c 100644 --- a/docs/topics/coroutine-context-and-dispatchers.md +++ b/docs/topics/coroutine-context-and-dispatchers.md @@ -1,4 +1,5 @@ +https://github.com/Kotlin/kotlinx.coroutines/edit/master/docs/topics/ [//]: # (title: Coroutine context and dispatchers) diff --git a/docs/topics/coroutines-and-channels.md b/docs/topics/coroutines-and-channels.md index d448ef946e..45081dc8bc 100644 --- a/docs/topics/coroutines-and-channels.md +++ b/docs/topics/coroutines-and-channels.md @@ -1,3 +1,5 @@ +https://github.com/Kotlin/kotlinx.coroutines/edit/master/docs/topics/ + [//]: # (title: Coroutines and channels − tutorial) In this tutorial, you'll learn how to use coroutines in IntelliJ IDEA to perform network requests without blocking the diff --git a/docs/topics/coroutines-basics.md b/docs/topics/coroutines-basics.md index bdfed48fd4..72af2c06ba 100644 --- a/docs/topics/coroutines-basics.md +++ b/docs/topics/coroutines-basics.md @@ -1,4 +1,5 @@ +https://github.com/Kotlin/kotlinx.coroutines/edit/master/docs/topics/ [//]: # (title: Coroutines basics) diff --git a/docs/topics/coroutines-guide.md b/docs/topics/coroutines-guide.md index fd95c38dee..a77acf43f8 100644 --- a/docs/topics/coroutines-guide.md +++ b/docs/topics/coroutines-guide.md @@ -1,3 +1,6 @@ +https://github.com/Kotlin/kotlinx.coroutines/edit/master/docs/topics/ + + [//]: # (title: Coroutines guide) Kotlin provides only minimal low-level APIs in its standard library to enable other diff --git a/docs/topics/debug-coroutines-with-idea.md b/docs/topics/debug-coroutines-with-idea.md index a3e4b28aae..9ac49fddbb 100644 --- a/docs/topics/debug-coroutines-with-idea.md +++ b/docs/topics/debug-coroutines-with-idea.md @@ -1,3 +1,6 @@ +https://github.com/Kotlin/kotlinx.coroutines/edit/master/docs/topics/ + + [//]: # (title: Debug coroutines using IntelliJ IDEA – tutorial) This tutorial demonstrates how to create Kotlin coroutines and debug them using IntelliJ IDEA. diff --git a/docs/topics/debug-flow-with-idea.md b/docs/topics/debug-flow-with-idea.md index 53521fbf39..4e2541bc89 100644 --- a/docs/topics/debug-flow-with-idea.md +++ b/docs/topics/debug-flow-with-idea.md @@ -1,3 +1,6 @@ +https://github.com/Kotlin/kotlinx.coroutines/edit/master/docs/topics/ + + [//]: # (title: Debug Kotlin Flow using IntelliJ IDEA – tutorial) This tutorial demonstrates how to create Kotlin Flow and debug it using IntelliJ IDEA. diff --git a/docs/topics/exception-handling.md b/docs/topics/exception-handling.md index 507d773509..0d369aa710 100644 --- a/docs/topics/exception-handling.md +++ b/docs/topics/exception-handling.md @@ -1,4 +1,5 @@ +https://github.com/Kotlin/kotlinx.coroutines/edit/master/docs/topics/ [//]: # (title: Coroutine exceptions handling) diff --git a/docs/topics/flow.md b/docs/topics/flow.md index 08fe164a33..a3cb1176c5 100644 --- a/docs/topics/flow.md +++ b/docs/topics/flow.md @@ -1,4 +1,5 @@ +https://github.com/Kotlin/kotlinx.coroutines/edit/master/docs/topics/ [//]: # (title: Asynchronous Flow) diff --git a/docs/topics/select-expression.md b/docs/topics/select-expression.md index acbbc691d5..77da920247 100644 --- a/docs/topics/select-expression.md +++ b/docs/topics/select-expression.md @@ -1,4 +1,5 @@ +https://github.com/Kotlin/kotlinx.coroutines/edit/master/docs/topics/ [//]: # (title: Select expression \(experimental\)) diff --git a/docs/topics/shared-mutable-state-and-concurrency.md b/docs/topics/shared-mutable-state-and-concurrency.md index 13fd9b9d3d..1baf07d066 100644 --- a/docs/topics/shared-mutable-state-and-concurrency.md +++ b/docs/topics/shared-mutable-state-and-concurrency.md @@ -1,4 +1,5 @@ +https://github.com/Kotlin/kotlinx.coroutines/edit/master/docs/topics/ [//]: # (title: Shared mutable state and concurrency) From 028b091058aeddeccdbc16cead1f835cd747da7b Mon Sep 17 00:00:00 2001 From: "andrei.ezerskii" Date: Tue, 24 Sep 2024 16:17:47 +0200 Subject: [PATCH 4/8] update toc --- docs/writerside.cfg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writerside.cfg b/docs/writerside.cfg index dc6433aeb6..3a035ffd10 100644 --- a/docs/writerside.cfg +++ b/docs/writerside.cfg @@ -7,7 +7,7 @@ - + From 9f5383b83566284b6c74816ed9c33d37ad58559d Mon Sep 17 00:00:00 2001 From: "andrei.ezerskii" Date: Tue, 24 Sep 2024 16:26:28 +0200 Subject: [PATCH 5/8] remove propbundle cache redundant link from the writerside.cfg --- docs/writerside.cfg | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/writerside.cfg b/docs/writerside.cfg index 3a035ffd10..7efe584730 100644 --- a/docs/writerside.cfg +++ b/docs/writerside.cfg @@ -8,7 +8,7 @@ - - - - + + + + From a2013979c7dcc72b0f6f4f5ec9d7982556094b04 Mon Sep 17 00:00:00 2001 From: "andrei.ezerskii" Date: Tue, 24 Sep 2024 16:26:28 +0200 Subject: [PATCH 6/8] second level header - remove code --- docs/topics/cancellation-and-timeouts.md | 2 +- kotlinx-coroutines-test/MIGRATION.md | 20 ++++++++++---------- kotlinx-coroutines-test/README.md | 4 ++-- 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/topics/cancellation-and-timeouts.md b/docs/topics/cancellation-and-timeouts.md index 45bc87f01b..f19da89ffa 100644 --- a/docs/topics/cancellation-and-timeouts.md +++ b/docs/topics/cancellation-and-timeouts.md @@ -189,7 +189,7 @@ main: I'm tired of waiting! main: Now I can quit. --> -## Closing resources with `finally` +## Closing resources with finally Cancellable suspending functions throw [CancellationException] on cancellation, which can be handled in the usual way. For example, the `try {...} finally {...}` expression and Kotlin's `use` function execute their diff --git a/kotlinx-coroutines-test/MIGRATION.md b/kotlinx-coroutines-test/MIGRATION.md index 10c197f49e..11c829bfaa 100644 --- a/kotlinx-coroutines-test/MIGRATION.md +++ b/kotlinx-coroutines-test/MIGRATION.md @@ -4,7 +4,7 @@ In version 1.6.0, the API of the test module changed significantly. This is a guide for gradually adapting the existing test code to the new API. This guide is written step-by-step; the idea is to separate the migration into several sets of small changes. -## Remove custom `UncaughtExceptionCaptor`, `DelayController`, and `TestCoroutineScope` implementations +## Remove custom UncaughtExceptionCaptor, DelayController, and TestCoroutineScope implementations We couldn't find any code that defined new implementations of these interfaces, so they are deprecated. It's likely that you don't need to do anything for this section. @@ -61,7 +61,7 @@ So, there could be two reasons for defining a custom implementation: * Using without `runBlockingTest`. In this case, you don't even need to implement `TestCoroutineScope`: nothing else accepts a `TestCoroutineScope` specifically as an argument. -## Remove usages of `TestCoroutineExceptionHandler` and `TestCoroutineScope.uncaughtExceptions` +## Remove usages of TestCoroutineExceptionHandler and TestCoroutineScope.uncaughtExceptions It is already illegal to use a `TestCoroutineScope` without performing `cleanupTestCoroutines`, so the valid uses of `TestCoroutineExceptionHandler` include: @@ -93,13 +93,13 @@ fun testFoo() = runTest { } ``` -## Auto-replace `TestCoroutineScope` constructor function with `createTestCoroutineScope` +## Auto-replace TestCoroutineScope constructor function with createTestCoroutineScope This should not break anything, as `TestCoroutineScope` is now defined in terms of `createTestCoroutineScope`. If it does break something, it means that you already supplied a `TestCoroutineScheduler` to some scope; in this case, also pass this scheduler as the argument to the dispatcher. -## Replace usages of `pauseDispatcher` and `resumeDispatcher` with a `StandardTestDispatcher` +## Replace usages of pauseDispatcher and resumeDispatcher with a StandardTestDispatcher * In places where `pauseDispatcher` in its block form is called, replace it with a call to `withContext(StandardTestDispatcher(testScheduler))` @@ -120,7 +120,7 @@ also pass this scheduler as the argument to the dispatcher. `StandardTestDispatcher` (where dispatches are needed) and `UnconfinedTestDispatcher` (where it isn't important where execution happens). -## Replace `advanceTimeBy(n)` with `advanceTimeBy(n); runCurrent()` +## Replace advanceTimeBy(n) with advanceTimeBy(n); runCurrent() For `TestCoroutineScope` and `DelayController`, the `advanceTimeBy` method is deprecated. It is not deprecated for `TestCoroutineScheduler` and `TestScope`, but has a different meaning: it does not run the @@ -131,7 +131,7 @@ There is an automatic replacement for this deprecation, which produces correct b Alternatively, you can wait until replacing `TestCoroutineScope` with `TestScope`: it's possible that you will not encounter this edge case. -## Replace `runBlockingTest` with `runTest(UnconfinedTestDispatcher())` +## Replace runBlockingTest with runTest(UnconfinedTestDispatcher()) This is a major change, affecting many things, and can be done in parallel with replacing `TestCoroutineScope` with `TestScope`. @@ -329,7 +329,7 @@ There is a `runTestWithLegacyScope` method that allows migrating from `runBlocki from `TestCoroutineScope` to `TestScope`, if exactly the `TestCoroutineScope` needs to be passed somewhere else and `TestScope` will not suffice. -## Replace `TestCoroutineScope.cleanupTestCoroutines` with `runTest` +## Replace TestCoroutineScope.cleanupTestCoroutines with runTest Likely can be done together with the next step. @@ -363,7 +363,7 @@ fun runTestAndCleanup(body: TestScope.() -> Unit) = runTest { } ``` -## Replace `runBlockingTest` with `runBlockingTestOnTestScope`, `createTestCoroutineScope` with `TestScope` +## Replace runBlockingTest with runBlockingTestOnTestScope, createTestCoroutineScope with TestScope Also, replace `runTestWithLegacyScope` with just `runTest`. All of this can be done in parallel with replacing `runBlockingTest` with `runTest`. @@ -379,13 +379,13 @@ handle cancelled tasks differently: if there are *cancelled* jobs pending at the Of all the methods supported by `TestCoroutineScope`, only `cleanupTestCoroutines` is not provided on `TestScope`, and its usages should have been removed during the previous step. -## Replace `runBlocking` with `runTest` +## Replace runBlocking with runTest Now that `runTest` works properly with asynchronous completions, `runBlocking` is only occasionally useful. As is, most uses of `runBlocking` in tests come from the need to interact with dispatchers that execute on other threads, like `Dispatchers.IO` or `Dispatchers.Default`. -## Replace `TestCoroutineDispatcher` with `UnconfinedTestDispatcher` and `StandardTestDispatcher` +## Replace TestCoroutineDispatcher with UnconfinedTestDispatcher and StandardTestDispatcher `TestCoroutineDispatcher` is a dispatcher with two modes: * ("unpaused") Almost (but not quite) unconfined, with the ability to eagerly enter `launch` and `async` blocks. diff --git a/kotlinx-coroutines-test/README.md b/kotlinx-coroutines-test/README.md index e8eaf3d17b..59b88a1ea9 100644 --- a/kotlinx-coroutines-test/README.md +++ b/kotlinx-coroutines-test/README.md @@ -159,7 +159,7 @@ suspend fun foo() { } ``` -## `launch` and `async` +## launch and async The coroutine dispatcher used for tests is single-threaded, meaning that the child coroutines of the [runTest] block will run on the thread that started the test, and will never run in parallel. @@ -323,7 +323,7 @@ fun testExampleBackgroundJob() = runTest { } ``` -## Eagerly entering `launch` and `async` blocks +## Eagerly entering launch and async blocks Some tests only test functionality and don't particularly care about the precise order in which coroutines are dispatched. From 383f8ae1868f5c26bc1cb5bf379c4bd8fc37c0ee Mon Sep 17 00:00:00 2001 From: "andrei.ezerskii" Date: Tue, 24 Sep 2024 17:50:37 +0200 Subject: [PATCH 7/8] third level header - remove code --- kotlinx-coroutines-test/MIGRATION.md | 12 ++++++------ kotlinx-coroutines-test/README.md | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/kotlinx-coroutines-test/MIGRATION.md b/kotlinx-coroutines-test/MIGRATION.md index 11c829bfaa..9c33a9eece 100644 --- a/kotlinx-coroutines-test/MIGRATION.md +++ b/kotlinx-coroutines-test/MIGRATION.md @@ -9,7 +9,7 @@ This guide is written step-by-step; the idea is to separate the migration into s We couldn't find any code that defined new implementations of these interfaces, so they are deprecated. It's likely that you don't need to do anything for this section. -### `UncaughtExceptionCaptor` +### UncaughtExceptionCaptor If the code base has an `UncaughtExceptionCaptor`, its special behavior as opposed to just `CoroutineExceptionHandler` was that, at the end of `runBlockingTest` or `cleanupTestCoroutines` (or both), its `cleanupTestCoroutines` procedure @@ -35,7 +35,7 @@ fun testFoo() = runTest { } ``` -### `DelayController` +### DelayController We don't provide a way to define custom dispatching strategies that support virtual time. That said, we significantly enhanced this mechanism: @@ -48,7 +48,7 @@ That said, we significantly enhanced this mechanism: If you have a use case for `DelayController` that's not covered by what we provide, please tell us about it in the issue tracker. -### `TestCoroutineScope` +### TestCoroutineScope This scope couldn't be meaningfully used in tandem with `runBlockingTest`: according to the definition of `TestCoroutineScope.runBlockingTest`, only the scope's `coroutineContext` is used. @@ -142,7 +142,7 @@ Significant differences of `runTest` from `runBlockingTest` are each given a sec No action on your part is required, other than replacing `runBlocking` with `runTest` as well. -### It uses `StandardTestDispatcher` by default, not `TestCoroutineDispatcher`. +### It uses StandardTestDispatcher by default, not TestCoroutineDispatcher. By now, calls to `pauseDispatcher` and `resumeDispatcher` should be purged from the code base, so only the unpaused variant of `TestCoroutineDispatcher` should be used. @@ -304,7 +304,7 @@ fun testFoo() = runTest { } ``` -### Only a single call to `runTest` is permitted per test. +### Only a single call to runTest is permitted per test. In order to work on JS, only a single call to `runTest` must happen during one test, and its result must be returned immediately: @@ -323,7 +323,7 @@ When used only on the JVM, `runTest` will work when called repeatedly, but this Please only call `runTest` once per test, and if for some reason you can't, please tell us about in on the issue tracker. -### It uses `TestScope`, not `TestCoroutineScope`, by default. +### It uses TestScope, not TestCoroutineScope, by default. There is a `runTestWithLegacyScope` method that allows migrating from `runBlockingTest` to `runTest` before migrating from `TestCoroutineScope` to `TestScope`, if exactly the `TestCoroutineScope` needs to be passed somewhere else and diff --git a/kotlinx-coroutines-test/README.md b/kotlinx-coroutines-test/README.md index 59b88a1ea9..488599a931 100644 --- a/kotlinx-coroutines-test/README.md +++ b/kotlinx-coroutines-test/README.md @@ -374,7 +374,7 @@ fun testEagerlyEnteringSomeChildCoroutines() = runTest(UnconfinedTestDispatcher( } ``` -### Using `withTimeout` inside `runTest` +### Using withTimeout inside runTest Timeouts are also susceptible to time control, so the code below will immediately finish. From 73fe7837dce23772ac1314aa05c8a8df2faceb87 Mon Sep 17 00:00:00 2001 From: "andrei.ezerskii" Date: Tue, 24 Sep 2024 17:52:28 +0200 Subject: [PATCH 8/8] fourth level header - remove code --- kotlinx-coroutines-test/MIGRATION.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/kotlinx-coroutines-test/MIGRATION.md b/kotlinx-coroutines-test/MIGRATION.md index 9c33a9eece..0e9e6092be 100644 --- a/kotlinx-coroutines-test/MIGRATION.md +++ b/kotlinx-coroutines-test/MIGRATION.md @@ -151,7 +151,7 @@ code until the first suspension is executed without dispatching. There are two common ways in which this property is useful. -#### `TestCoroutineDispatcher` for the top-level coroutine +#### TestCoroutineDispatcher for the top-level coroutine Some tests that rely on `launch` and `async` blocks being entered immediately have a form similar to this: ```kotlin @@ -177,7 +177,7 @@ blocks. Note though that *this only works at the top level*: if a child coroutine also called `launch` or `async`, we don't provide any guarantees about their dispatching order. -#### `TestCoroutineDispatcher` for testing intermediate emissions +#### TestCoroutineDispatcher for testing intermediate emissions Some code tests `StateFlow` or channels in a manner similar to this: