Merge branch 'master' into develop

Author: qwwdfsad

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,29 @@
+---
+name: Bug report
+about: Our code behaves incorrectly?
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+<!--
+**Double-check**
+
+* Is this *really* a bug?
+  - If the behavior is documented, but you disagree with it, please do file an issue, but as a "Design consideration," not a "Bug report."
+  - If you don't understand why something behaves the way it does, consider asking on [StackOverflow](https://stackoverflow.com/) or the [Kotlin Slack](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up). The community is active and will likely clarify everything better than we could!
+* Is the problem not in some third-party library, not in [Kotlin](kotl.in/issue), or your own code—is it in the `kotlinx.coroutines` library itself?
+  - Example: you write for Android, and your code works properly on most devices, but for a couple of them, it fails. Then please direct this to Google and/or the manufacturer of your device.
+* Maybe you're using some ancient version, and the problem doesn't happen with the latest releases of the compiler and the library?
+-->
+
+**Describe the bug**
+
+What happened? What should have happened instead?
+
+**Provide a Reproducer**
+
+* If possible, please provide a small self-contained project (or even just a single file) where the issue reproduces.
+* If you can't pinpoint the issue, please provide at least *some* project where this reproduces, for example, your production one. If you are not ready to show the project publicly, we are open to discussing the details privately.
+* If you really can't provide any code, please do still open an issue. This may prompt other people to chime in with their reproducers.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Kotlinlang Slack
+    url: https://surveys.jetbrains.com/s3/kotlin-slack-sign-up
+    about: Please ask and answer usage-related questions here.

.github/ISSUE_TEMPLATE/design_considerations.md

@@ -0,0 +1,45 @@
+---
+name: Design considerations
+about: We didn't think things through?
+title: ''
+labels: design
+assignees: ''
+
+---
+
+<!--
+This is a place for issue reports that are not exactly bugs (wrong unintentional behavior) but for our library behaving suboptimally (though this could have been intentional).
+
+**Double-check**
+
+* If the behavior is strange, surprising, and undocumented, it could be a good idea to file a "Bug report" instead.
+* Is this still relevant with the latest version of the library? We could have changed this already.
+* Maybe there are good reasons for the existing behavior. Please try searching for existing discussions of the problem.
+* Are you using the right abstraction? Consider asking on [StackOverflow](https://stackoverflow.com/) or the [Kotlin Slack](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up). Maybe your need is better solved by some other abstraction entirely.
+
+-->
+
+**What do we have now?**
+
+Preferably with specific code examples.
+
+**What should be instead?**
+
+Preferably with specific code examples.
+
+**Why?**
+
+The upsides of your proposal.
+* Who would benefit from this and how?
+  - Would it be possible to cover new use cases?
+  - Would some code become clearer?
+  - Would the library become conceptually simpler?
+  - etc.
+
+**Why not?**
+
+The downsides of your proposal that you already see.
+* Is this a breaking change?
+* Are there use cases that are better solved by what we have now?
+* Does some code become less clear after this change?
+* etc.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,33 @@
+---
+name: Feature request
+about: We're missing something?
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+<!--
+**Double-check**
+
+* Maybe this feature is already here?
+  - Did you check the latest version of the library?
+  - Maybe it's in a form you didn't expect? Consider asking on [StackOverflow](https://stackoverflow.com/) or the [Kotlin Slack](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up). The community will likely come up with some code that solves your need, and faster than it would take us to answer the issue!
+* Do you actually *need* this feature? Maybe restructuring your code would neatly eliminate the problem the feature would be solving.
+* Is the coroutines library the best place for this feature? Maybe it would be better suited for some third-party library?
+-->
+
+**Use case**
+
+Explain what *specifically* you are trying to do and why.
+- Example: "I have a `SharedFlow<Double>` that represents readings from an external device. The readings arrive in a set interval of 100 milliseconds. However, I also need to be able to calibrate the state of the external device by setting the readings from inside the program. When I set the state, the `SharedFlow<Double>` must immediately emit the value that was set and ignore any values coming from the device in the following 10 milliseconds since they are considered outdated, as the device is only guaranteed to recalibrate to the updated value after that period."
+- Non-example: "I have a `SharedFlow<T>` that has several sources of its values, and these sources need to have priorities attached to them so that one source always takes precedence over the other in a close race."
+- Non-example: "RxJava has feature X, so the coroutines library should also."
+
+**The Shape of the API**
+
+What could the desired API look like? What would some sample code using the new feature look like? If you don't have a clear idea, pseudocode or just explaining the API shape is also perfectly fine.
+
+**Prior Art**
+
+(Optional) Maybe you have seen something like the feature you need, but in other libraries, or there is something very similar but not quite sufficient in `kotlinx.coroutines`? Maybe there's already a way to do it, but it's too cumbersome and unclear?

CHANGES.md

@@ -223,7 +223,7 @@ Note that this is a full changelog relative to 1.4.3 version. Changelog relative
 * `Flow.runningFold` operator (#2641).
 * `CoroutinesTimeout` rule for JUnit5 (#2197).
 * Internals of `Job` and `AbstractCoroutine` was reworked, resulting in smaller code size, less memory footprint, and better performance (#2513, #2512).
-* `CancellationException` from Kotlin standard library is used for cancellation on Koltin/JS and Kotlin/Native (#2638).
+* `CancellationException` from Kotlin standard library is used for cancellation on Kotlin/JS and Kotlin/Native (#2638).
 * Introduced new `DelicateCoroutinesApi` annotation that warns users about potential target API pitfalls and suggests studying API's documentation first. The only delicate API right now is `GlobalScope` (#2637).
 * Fixed bug introduced in `1.4.3` when `kotlinx-coroutines-core.jar` triggered IDEA debugger failure (#2619).
 * Fixed memory leak of `ChildHandlerNode` with reusable continuations (#2564).
@@ -264,7 +264,7 @@ Note that this is a full changelog relative to 1.4.3 version. Changelog relative
 * `Flow.runningFold` operator (#2641).
 * `CoroutinesTimeout` rule for JUnit5 (#2197).
 * Internals of `Job` and `AbstractCoroutine` was reworked, resulting in smaller code size, less memory footprint, and better performance (#2513, #2512).
-* `CancellationException` from Kotlin standard library is used for cancellation on Koltin/JS and Kotlin/Native (#2638).
+* `CancellationException` from Kotlin standard library is used for cancellation on Kotlin/JS and Kotlin/Native (#2638).
 * Introduced new `DelicateCoroutineApi` annotation that warns users about potential target API pitfalls and suggests studying API's documentation first. The only delicate API right now is `GlobalScope` (#2637).
 * Fixed bug introduced in `1.4.3` when `kotlinx-coroutines-core.jar` triggered IDEA debugger failure (#2619).
 * Fixed memory leak of `ChildHandlerNode` with reusable continuations (#2564).

CONTRIBUTING.md

@@ -7,21 +7,8 @@ fixes/changes/improvements via pull requests.
 
 Both bug reports and feature requests are welcome.
 Submit issues [here](https://github.com/Kotlin/kotlinx.coroutines/issues).
-
-* Search for existing issues to avoid reporting duplicates.
-* When submitting a bug report:
-  * Test it against the most recently released version. It might have been already fixed.
-  * By default, we assume that your problem reproduces in Kotlin/JVM. Please, mention if the problem is
-    specific to Kotlin/JS or Kotlin/Native. 
-  * Include the code that reproduces the problem. Provide the complete reproducer code, yet minimize it as much as possible.
-  * However, don't put off reporting any weird or rarely appearing issues just because you cannot consistently 
-    reproduce them.
-  * If the bug is in behavior, then explain what behavior you've expected and what you've got.  
-* When submitting a feature request:
-  * Explain why you need the feature — what's your use-case, what's your domain.
-  * Explaining the problem you face is more important than suggesting a solution. 
-    Report your problem even if you don't have any proposed solution.
-  * If there is an alternative way to do what you need, then show the code of the alternative.
+Questions about usage and general inquiries are better suited for [StackOverflow](https://stackoverflow.com)
+or the `#coroutines` channel in [KotlinLang Slack](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up).
 
 ## Submitting PRs
 
@@ -30,21 +17,23 @@ However, please keep in mind that maintainers will have to support the resulting
 so do familiarize yourself with the following guidelines. 
 
 * All development (both new features and bug fixes) is performed in the `develop` branch.
-  * The `master` branch always contains sources of the most recently released version.
-  * Base PRs against the `develop` branch.
+  * The `master` branch contains the sources of the most recently released version.
+  * Base your PRs against the `develop` branch.
   * The `develop` branch is pushed to the `master` branch during release.
   * Documentation in markdown files can be updated directly in the `master` branch, 
     unless the documentation is in the source code, and the patch changes line numbers.
 * If you fix documentation:
   * After fixing/changing code examples in the [`docs`](docs) folder or updating any references in the markdown files
     run the [Knit tool](#running-the-knit-tool) and commit the resulting changes as well. 
-    It will not pass the tests otherwise.
+    The tests will not pass otherwise.
   * If you plan extensive rewrites/additions to the docs, then please [contact the maintainers](#contacting-maintainers)
-    to coordinate the work in advance.    
+    to coordinate the work in advance.
 * If you make any code changes:
   * Follow the [Kotlin Coding Conventions](https://kotlinlang.org/docs/reference/coding-conventions.html). 
     Use 4 spaces for indentation.
-  * [Build the project](#building) to make sure it all works and passes the tests.
+    Do not add extra newlines in function bodies: if you feel that blocks of code should be logically separated,
+    then separate them with a comment instead.
+  * [Build the project](#building) to make sure everything works and passes the tests.
 * If you fix a bug:
   * Write the test that reproduces the bug.
   * Fixes without tests are accepted only in exceptional circumstances if it can be shown that writing the 
@@ -53,37 +42,37 @@ so do familiarize yourself with the following guidelines.
     name test functions as `testXxx`. Don't use backticks in test names.
 * If you introduce any new public APIs:
   * Comment on the existing issue if you want to work on it or create one beforehand. 
-    Ensure that the issue not only describes a problem, but also describes a solution that had received a positive feedback. Propose a solution if there isn't any.
-    PRs with new API, but without a corresponding issue with a positive feedback about the proposed implementation are unlikely to
-    be approved or reviewed.
+    Ensure that not only the issue describes a problem, but also that the proposed solution has received positive
+    feedback. Propose a solution if there isn't any.
+    PRs that add new API without a corresponding issue with positive feedback about the proposed implementation are
+    unlikely to be approved or reviewed.
   * All new APIs must come with documentation and tests.
-  * All new APIs are initially released with `@ExperimentalCoroutineApi` annotation and are graduated later.
+  * All new APIs are initially released with the `@ExperimentalCoroutineApi` annotation and graduate later.
   * [Update the public API dumps](#updating-the-public-api-dump) and commit the resulting changes as well. 
     It will not pass the tests otherwise.
-  * If you plan large API additions, then please start by submitting an issue with the proposed API design  
+  * If you plan large API additions, then please start by submitting an issue with the proposed API design
     to gather community feedback.
-  * [Contact the maintainers](#contacting-maintainers) to coordinate any big piece of work in advance.
-* Steps for contributing new integration modules are explained [here](integration/README.md#Contributing).
+  * [Contact the maintainers](#contacting-maintainers) to coordinate any extensive work in advance.
 
 ## Building
 
 This library is built with Gradle. 
 
 * Run `./gradlew build` to build. It also runs all the tests.
-* Run `./gradlew <module>:test` to test the module you are looking at to speed 
+* Run `./gradlew <module>:check` to test the module you are looking at to speed 
   things up during development.
-* Run `./gradlew jvmTest` to perform only fast JVM tests of the core multiplatform module.
+* Run `./gradlew <module>:jvmTest` to perform only the fast JVM tests of a multiplatform module.
 
 You can import this project into IDEA, but you have to delegate build actions
-to Gradle (in Preferences -> Build, Execution, Deployment -> Build Tools -> Gradle -> Runner)
+to Gradle (in Preferences -> Build, Execution, Deployment -> Build Tools -> Gradle -> Build and run).
 
 ### Environment requirements
 
 * JDK >= 11 referred to by the `JAVA_HOME` environment variable.
 * JDK 1.8 referred to by the `JDK_18` environment variable. Only used by nightly stress-tests. 
-  It is OK to have `JDK_18` to a non 1.8 JDK (e.g. `JAVA_HOME`) for external contributions.
+  It is OK to have `JDK_18` point to a non-1.8 JDK (e.g. `JAVA_HOME`) for external contributions.
 
-For external contributions you can for example add this to your shell startup scripts (e.g. `~/.zshrc`):
+For external contributions you can, for example, add this to your shell startup scripts (e.g. `~/.zshrc`):
 ```shell
 # This assumes JAVA_HOME is set already to a JDK >= 11 version
 export JDK_18="$JAVA_HOME"
@@ -92,18 +81,18 @@ export JDK_18="$JAVA_HOME"
 ### Running the Knit tool
 
 * Use [Knit](https://github.com/Kotlin/kotlinx-knit/blob/main/README.md) for updates to documentation:
-  * Run `./gradlew knit` to update example files, links, tables of content.
-  * Commit updated documents and examples together with other changes.
+  * Run `./gradlew knit` to update the example files, links, tables of content.
+  * Commit the updated documents and examples together with other changes.
 
 ### Updating the public API dump
 
-* Use [Binary Compatibility Validator](https://github.com/Kotlin/binary-compatibility-validator/blob/master/README.md) for updates to public API:
+* Use the [Binary Compatibility Validator](https://github.com/Kotlin/binary-compatibility-validator/blob/master/README.md) for updates to public API:
   * Run `./gradlew apiDump` to update API index files. 
-  * Commit updated API indexes together with other changes.
+  * Commit the updated API indexes together with other changes.
 
 ## Releases
 
-* Full release procedure checklist is [here](RELEASE.md).
+* The full release procedure checklist is [here](RELEASE.md).
 
 ## Contacting maintainers
 

docs/cfg/buildprofiles.xml

@@ -3,7 +3,7 @@
 <buildprofiles>
     <variables>
         <enable-browser-edits>true</enable-browser-edits>
-        <browser-edits-url>https://github.com/Kotlin/kotlinx.coroutines/edit/master/</browser-edits-url>
+        <browser-edits-url>https://github.com/Kotlin/kotlinx.coroutines/edit/master/docs/</browser-edits-url>
         <allow-indexable-eaps>true</allow-indexable-eaps>
     </variables>
     <build-profile product="kc"/>

docs/images/variable-optimised-out.png

@@ -379,10 +379,11 @@ The timeout event in [withTimeout] is asynchronous with respect to the code runn
 even right before the return from inside of the timeout block. Keep this in mind if you open or acquire some
 resource inside the block that needs closing or release outside of the block. 
 
-For example, here we imitate a closeable resource with the `Resource` class, that simply keeps track of how many times 
-it was created by incrementing the `acquired` counter and decrementing this counter from its `close` function.
-Let us run a lot of coroutines with the small timeout try acquire this resource from inside
-of the `withTimeout` block after a bit of delay and release it from outside.
+For example, here we imitate a closeable resource with the `Resource` class that simply keeps track of how many times 
+it was created by incrementing the `acquired` counter and decrementing the counter in its `close` function.
+Now let us let us create a lot of coroutines, each of which creates a `Resource` at the end of the `withTimeout` block
+and releases the resource outside the block. We add a small delay so that it is more likely that the timeout occurs
+right when the `withTimeout` block is already finished, which will cause a resource leak.
 
 ```kotlin
 import kotlinx.coroutines.*
@@ -420,16 +421,16 @@ fun main() {
 
 <!--- CLEAR -->
 
-If you run the above code you'll see that it does not always print zero, though it may depend on the timings 
-of your machine you may need to tweak timeouts in this example to actually see non-zero values. 
+If you run the above code, you'll see that it does not always print zero, though it may depend on the timings 
+of your machine. You may need to tweak the timeout in this example to actually see non-zero values. 
 
-> Note that incrementing and decrementing `acquired` counter here from 100K coroutines is completely safe,
-> since it always happens from the same main thread. More on that will be explained in the chapter
-> on coroutine context.
+> Note that incrementing and decrementing `acquired` counter here from 100K coroutines is completely thread-safe,
+> 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"}
 
-To work around this problem you can store a reference to the resource in the variable as opposed to returning it 
+To work around this problem you can store a reference to the resource in a variable instead of returning it 
 from the `withTimeout` block. 
 
 ```kotlin