Merge with parent project

.gitignore

@@ -1,8 +1,13 @@
-.idea
+**/.idea/*
+!/.idea/icon.png
+!/.idea/vcs.xml
+!/.idea/copyright
+!/.idea/codeStyleSettings.xml
+!/.idea/codeStyles
 *.iml
 .gradle
 .gradletasknamecache
 build
 out
 target
-local.properties
+local.properties

CHANGES.md

@@ -1,5 +1,119 @@
 # Change log for kotlinx.coroutines
 
+## Version 1.4.0
+
+### Improvements
+
+* `StateFlow`, `SharedFlow` and corresponding operators are promoted to stable API (#2316).
+* `Flow.debounce` operator with timeout selector based on each individual element is added (#1216, thanks to @mkano9!). 
+* `CoroutineContext.job` extension property is introduced (#2159).
+* `Flow.combine operator` is reworked:
+    * Complete fairness is maintained for single-threaded dispatchers.
+    * Its performance is improved, depending on the use-case, by at least 50% (#2296).
+    * Quadratic complexity depending on the number of upstream flows is eliminated (#2296).
+    * `crossinline` and `inline`-heavy internals are removed, fixing sporadic SIGSEGV on Mediatek Android devices (#1683, #1743).
+* `Flow.zip` operator performance is improved by 40%.
+* Various API has been promoted to stable or its deprecation level has been raised (#2316).
+
+### Bug fixes
+
+* Suspendable `stateIn` operator propagates exception to the caller when upstream fails to produce initial value (#2329).
+* Fix `SharedFlow` with replay for subscribers working at different speed (#2325).
+* Do not fail debug agent installation when security manager does not provide access to system properties (#2311).
+* Cancelled lazy coroutines are properly cleaned up from debug agent output (#2294).
+* `BlockHound` false-positives are correctly filtered out (#2302, #2190, #2303).
+* Potential crash during a race between cancellation and upstream in `Observable.asFlow` is fixed (#2104, #2299, thanks to @LouisCAD and @drinkthestars).
+
+## Version 1.4.0-M1
+
+### Breaking changes
+
+* The concept of atomic cancellation in channels is removed. All operations in channels
+    and corresponding `Flow` operators are cancellable in non-atomic way (#1813).
+* If `CoroutineDispatcher` throws `RejectedExecutionException`, cancel current `Job` and schedule its execution to `Dispatchers.IO` (#2003).
+* `CancellableContinuation.invokeOnCancellation` is invoked if the continuation was cancelled while its resume has been dispatched (#1915).
+* `Flow.singleOrNull` operator is aligned with standard library and does not longer throw `IllegalStateException` on multiple values (#2289). 
+
+### New experimental features
+
+* `SharedFlow` primitive for managing hot sources of events with support of various subscription mechanisms, replay logs and buffering (#2034).
+* `Flow.shareIn` and `Flow.stateIn` operators to transform cold instances of flow to hot `SharedFlow` and `StateFlow` respectively (#2047).
+
+### Other
+
+* Support leak-free closeable resources transfer via `onUndeliveredElement` in channels (#1936).
+* Changed ABI in reactive integrations for Java interoperability (#2182).
+* Fixed ProGuard rules for `kotlinx-coroutines-core` (#2046, #2266).
+* Lint settings were added to `Flow` to avoid accidental capturing of outer `CoroutineScope` for cancellation check (#2038). 
+
+### External contributions
+
+* Allow nullable types in `Flow.firstOrNull` and `Flow.singleOrNull` by @ansman (#2229).
+* Add `Publisher.awaitSingleOrDefault|Null|Else` extensions by @sdeleuze (#1993).
+* `awaitCancellation` top-level function by @LouisCAD (#2213).
+* Significant part of our Gradle build scripts were migrated to `.kts` by @turansky. 
+
+Thank you for your contributions and participation in the Kotlin community!
+
+## Version 1.3.9
+
+* Support of `CoroutineContext` in `Flow.asPublisher` and similar reactive builders (#2155).
+* Kotlin updated to 1.4.0.
+* Transition to new HMPP publication scheme for multiplatform usages:
+    * Artifacts `kotlinx-coroutines-core-common` and `kotlinx-coroutines-core-native` are removed.
+    * For multiplatform usages, it's enough to [depend directly](README.md#multiplatform) on `kotlinx-coroutines-core` in `commonMain` source-set.
+    * The same artifact coordinates can be used to depend on platform-specific artifact in platform-specific source-set.
+
+## Version 1.3.8
+
+### New experimental features
+
+* Added `Flow.transformWhile operator` (#2065).
+* Replaced `scanReduce` with `runningReduce` to be consistent with the Kotlin standard library (#2139).
+
+### Bug fixes and improvements
+
+* Improve user experience for the upcoming coroutines debugger (#2093, #2118, #2131).
+* Debugger no longer retains strong references to the running coroutines (#2129).
+* Fixed race in `Flow.asPublisher` (#2109).
+* Fixed `ensureActive` to work in the empty context case to fix `IllegalStateException` when using flow from `suspend fun main` (#2044).
+* Fixed a problem with `AbortFlowException` in the `Flow.first` operator to avoid erroneous `NoSuchElementException` (#2051).
+* Fixed JVM dependency on Android annotations (#2075).
+* Removed keep rules mentioning `kotlinx.coroutines.android` from core module (#2061 by @mkj-gram).
+* Corrected some docs and examples (#2062, #2071, #2076, #2107, #2098, #2127, #2078, #2135).                                                                          
+* Improved the docs and guide on flow cancellation (#2043).
+* Updated Gradle version to `6.3` (it only affects multiplatform artifacts in this release).
+
+## Version 1.3.7
+
+* Fixed problem that triggered Android Lint failure (#2004).
+* New `Flow.cancellable()` operator for cooperative cancellation (#2026).
+* Emissions from `flow` builder now check cancellation status and are properly cancellable (#2026).
+* New `currentCoroutineContext` function to use unambiguously in the contexts with `CoroutineScope` in receiver position (#2026). 
+* `EXACTLY_ONCE` contract support in coroutine builders.
+* Various documentation improvements.
+
+## Version 1.3.6
+
+### Flow
+
+* `StateFlow`, new primitive for state handling (#1973, #1816, #395). The `StateFlow` is designed to eventually replace `ConflatedBroadcastChannel` for state publication scenarios. Please, try it and share your feedback. Note, that Flow-based primitives to publish events will be added later. For events you should continue to either use `BroadcastChannel(1)`, if you put events into the `StateFlow`, protect them from double-processing with flags.
+* `Flow.onEmpty` operator is introduced (#1890).
+* Behavioural change in `Flow.onCompletion`, it is aligned with `invokeOnCompletion` now and passes `CancellationException` to its cause parameter (#1693).
+* A lot of Flow operators have left its experimental status and are promoted to stable API.
+
+### Other
+
+* `runInterruptible` primitive to tie cancellation with thread interruption for blocking calls. Contributed by @jxdabc (#1947).
+* Integration module with RxJava3 is introduced. Contributed by @ZacSweers (#1883)
+* Integration with [BlockHound](https://github.com/reactor/BlockHound) in `kotlinx-coroutines-debug` module (#1821, #1060).
+* Memory leak in ArrayBroadcastChannel is fixed (#1885).
+* Behavioural change in `suspendCancellableCoroutine`, cancellation is established before invoking passed block argument (#1671).
+* Debug agent internals are moved into `kotlinx-coroutines-core` for better integration with IDEA. It should not affect library users and all the redundant code should be properly eliminated with R8.
+* ClassCastException with reusable continuations bug is fixed (#1966).
+* More precise scheduler detection for `Executor.asCoroutineDispatcher` (#1992).
+* Kotlin updated to 1.3.71.
+
 ## Version 1.3.5
 
 * `firstOrNull` operator. Contributed by @bradynpoulsen.

CONTRIBUTING.md

@@ -0,0 +1,113 @@
+# Contributing Guidelines
+
+There are two main ways to contribute to the project — submitting issues and submitting 
+fixes/changes/improvements via pull requests.
+
+## Submitting issues
+
+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.
+
+## Submitting PRs
+
+We love PRs. Submit PRs [here](https://github.com/Kotlin/kotlinx.coroutines/pulls).
+However, please keep in mind that maintainers will have to support the resulting code of the project,
+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 `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.
+  * If you plan extensive rewrites/additions to the docs, then please [contact the maintainers](#contacting-maintainers)
+    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.
+* 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 
+    corresponding test is too hard or otherwise impractical.
+  * Follow the style of writing tests that is used in this project: 
+    name test functions as `testXxx`. Don't use backticks in test names.
+* If you introduce any new public APIs:
+  * All new APIs must come with documentation and tests.
+  * All new APIs are initially released with `@ExperimentalCoroutineApi` annotation and are graduated 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  
+    to gather community feedback.
+  * [Contact the maintainers](#contacting-maintainers) to coordinate any big piece of work in advance.
+* Comment on the existing issue if you want to work on it. 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.
+* Steps for contributing new integration modules are explained [here](integration/README.md#Contributing).
+
+## 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 
+  things up during development.
+* Run `./gradlew jvmTest` to perform only fast JVM tests of the core 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)
+
+### Environment requirements
+
+* JDK >= 11 referred to by the `JAVA_HOME` environment variable.
+* JDK 1.6 referred to by the `JDK_16` environment variable. 
+  It is OK to have `JDK_16` pointing to a non 1.6 JDK (e.g. `JAVA_HOME`) for external contributions.
+* 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.
+
+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_16="$JAVA_HOME"
+export JDK_18="$JAVA_HOME"
+```
+
+### Running the Knit tool
+
+* Use [Knit](https://github.com/Kotlin/kotlinx-knit/blob/master/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.
+
+### 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:
+  * Run `./gradlew apiDump` to update API index files. 
+  * Commit updated API indexes together with other changes.
+
+## Releases
+
+* Full release procedure checklist is [here](RELEASE.md).
+
+## Contacting maintainers
+
+* If something cannot be done, not convenient, or does not work &mdash; submit an [issue](#submitting-issues).
+* "How to do something" questions &mdash; [StackOverflow](https://stackoverflow.com).
+* Discussions and general inquiries &mdash; use `#coroutines` channel in [KotlinLang Slack](https://kotl.in/slack).