Merge tag '1.4.1'
Test: m checkbuild
Change-Id: Id2bfed1f80aa4ba5c38bb512c4df4e937499ebcd
diff --git a/CHANGES.md b/CHANGES.md
index a1e3953..baee6c4 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,75 @@
# Change log for kotlinx.coroutines
+## Version 1.4.1
+
+This is a patch release with an important fix to the `SharedFlow` implementation.
+
+* SharedFlow: Fix scenario with concurrent emitters and cancellation of subscriber (#2359, thanks to @vehovsky for the bug report).
+
+## 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
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..7737062
--- /dev/null
+++ b/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 — submit an [issue](#submitting-issues).
+* "How to do something" questions — [StackOverflow](https://stackoverflow.com).
+* Discussions and general inquiries — use `#coroutines` channel in [KotlinLang Slack](https://kotl.in/slack).
diff --git a/METADATA b/METADATA
index e75b6f1..9859a06 100644
--- a/METADATA
+++ b/METADATA
@@ -5,11 +5,11 @@
type: GIT
value: "https://github.com/Kotlin/kotlinx.coroutines"
}
- version: "1.3.8"
+ version: "1.4.1"
license_type: NOTICE
last_upgrade_date {
year: 2020
- month: 7
- day: 16
+ month: 11
+ day: 25
}
}
diff --git a/README.md b/README.md
index 9f8bae6..7bd8e5a 100644
--- a/README.md
+++ b/README.md
@@ -2,10 +2,12 @@
[](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub)
[](https://www.apache.org/licenses/LICENSE-2.0)
-[ ](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines/1.3.8)
+[ ](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines/1.4.1)
+[](http://kotlinlang.org)
+[](https://kotlinlang.slack.com/messages/coroutines/)
Library support for Kotlin coroutines with [multiplatform](#multiplatform) support.
-This is a companion version for Kotlin `1.3.71` release.
+This is a companion version for Kotlin `1.4.0` release.
```kotlin
suspend fun main() = coroutineScope {
@@ -27,7 +29,7 @@
* [delay] and [yield] top-level suspending functions;
* [Flow] — cold asynchronous stream with [flow][_flow] builder and comprehensive operator set ([filter], [map], etc);
* [Channel], [Mutex], and [Semaphore] communication and synchronization primitives;
- * [coroutineScope], [supervisorScope], [withContext], and [withTimeout] scope builders;
+ * [coroutineScope][_coroutineScope], [supervisorScope][_supervisorScope], [withContext], and [withTimeout] scope builders;
* [MainScope()] for Android and UI applications;
* [SupervisorJob()] and [CoroutineExceptionHandler] for supervision of coroutines hierarchies;
* [select] expression support and more.
@@ -44,7 +46,7 @@
* [DebugProbes] API to probe, keep track of, print and dump active coroutines;
* [CoroutinesTimeout] test rule to automatically dump coroutines on test timeout.
* [reactive](reactive/README.md) — modules that provide builders and iteration support for various reactive streams libraries:
- * Reactive Streams ([Publisher.collect], [Publisher.awaitSingle], [publish], etc),
+ * Reactive Streams ([Publisher.collect], [Publisher.awaitSingle], [kotlinx.coroutines.reactive.publish], etc),
* Flow (JDK 9) (the same interface as for Reactive Streams),
* RxJava 2.x ([rxFlowable], [rxSingle], etc), and
* RxJava 3.x ([rxFlowable], [rxSingle], etc), and
@@ -84,7 +86,7 @@
<dependency>
<groupId>org.jetbrains.kotlinx</groupId>
<artifactId>kotlinx-coroutines-core</artifactId>
- <version>1.3.8</version>
+ <version>1.4.1</version>
</dependency>
```
@@ -92,7 +94,7 @@
```xml
<properties>
- <kotlin.version>1.3.71</kotlin.version>
+ <kotlin.version>1.4.0</kotlin.version>
</properties>
```
@@ -102,7 +104,7 @@
```groovy
dependencies {
- implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.8'
+ implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.1'
}
```
@@ -110,7 +112,7 @@
```groovy
buildscript {
- ext.kotlin_version = '1.3.71'
+ ext.kotlin_version = '1.4.0'
}
```
@@ -128,7 +130,7 @@
```groovy
dependencies {
- implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.8")
+ implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.1")
}
```
@@ -136,7 +138,7 @@
```groovy
plugins {
- kotlin("jvm") version "1.3.71"
+ kotlin("jvm") version "1.4.0"
}
```
@@ -146,9 +148,14 @@
Core modules of `kotlinx.coroutines` are also available for
[Kotlin/JS](#js) and [Kotlin/Native](#native).
-In common code that should get compiled for different platforms, add dependency to
-[`kotlinx-coroutines-core-common`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-common/1.3.8/jar)
-(follow the link to get the dependency declaration snippet).
+In common code that should get compiled for different platforms, you can add dependency to `kotlinx-coroutines-core` right to the `commonMain` source set:
+```groovy
+commonMain {
+ dependencies {
+ implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.1")
+ }
+}
+```
### Android
@@ -156,7 +163,7 @@
module as dependency when using `kotlinx.coroutines` on Android:
```groovy
-implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.3.8'
+implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.4.1'
```
This gives you access to Android [Dispatchers.Main]
@@ -169,10 +176,21 @@
R8 and ProGuard rules are bundled into the [`kotlinx-coroutines-android`](ui/kotlinx-coroutines-android) module.
For more details see ["Optimization" section for Android](ui/kotlinx-coroutines-android/README.md#optimization).
+#### Avoiding including the debug infrastructure in the resulting APK
+
+The `kotlinx-coroutines-core` artifact contains a resource file that is not required for the coroutines to operate
+normally and is only used by the debugger. To exclude it at no loss of functionality, add the following snippet to the
+`android` block in your gradle file for the application subproject:
+```groovy
+packagingOptions {
+ exclude "DebugProbesKt.bin"
+}
+```
+
### JS
[Kotlin/JS](https://kotlinlang.org/docs/reference/js-overview.html) version of `kotlinx.coroutines` is published as
-[`kotlinx-coroutines-core-js`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-js/1.3.8/jar)
+[`kotlinx-coroutines-core-js`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-js/1.4.1/jar)
(follow the link to get the dependency declaration snippet).
You can also use [`kotlinx-coroutines-core`](https://www.npmjs.com/package/kotlinx-coroutines-core) package via NPM.
@@ -180,7 +198,7 @@
### Native
[Kotlin/Native](https://kotlinlang.org/docs/reference/native-overview.html) version of `kotlinx.coroutines` is published as
-[`kotlinx-coroutines-core-native`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-native/1.3.8/jar)
+[`kotlinx-coroutines-core-native`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-native/1.4.1/jar)
(follow the link to get the dependency declaration snippet).
Only single-threaded code (JS-style) on Kotlin/Native is currently supported.
@@ -194,35 +212,9 @@
Since Kotlin/Native does not generally provide binary compatibility between versions,
you should use the same version of Kotlin/Native compiler as was used to build `kotlinx.coroutines`.
-## Building
+## Building and Contributing
-This library is built with Gradle. To build it, use `./gradlew build`.
-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)
-
-### Requirements
-
-* JDK >= 11 referred to by the `JAVA_HOME` environment variable.
-* JDK 1.6 referred to by the `JDK_16` environment variable. It is okay to have `JDK_16` pointing to `JAVA_HOME` for external contributions.
-* JDK 1.8 referred to by the `JDK_18` environment variable. Only used by nightly stress-tests. It is okay to have `JDK_18` pointing to `JAVA_HOME` for external contributions.
-
-## Contributions and releases
-
-All development (both new features and bug fixes) is performed in `develop` branch.
-This way `master` sources always contain sources of the most recently released version.
-Please send PRs with bug fixes to `develop` branch.
-Fixes to documentation in markdown files are an exception to this rule. They are updated directly in `master`.
-
-The `develop` branch is pushed to `master` during release.
-
-* Full release procedure checklist is [here](RELEASE.md).
-* Steps for contributing new integration modules are explained [here](integration/README.md#Contributing).
-* Use [Knit](https://github.com/Kotlin/kotlinx-knit/blob/master/README.md) for updates to documentation:
- * In project root directory run `./gradlew knit`.
- * Commit updated documents and examples together with other changes.
-* Use [Binary Compatibility Validator](https://github.com/Kotlin/binary-compatibility-validator/blob/master/README.md) for updates to public API:
- * In project root directory run `./gradlew apiDump`.
- * Commit updated API index together with other changes.
+See [Contributing Guidelines](CONTRIBUTING.md).
<!--- MODULE kotlinx-coroutines-core -->
<!--- INDEX kotlinx.coroutines -->
@@ -235,8 +227,8 @@
[Dispatchers.Default]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-default.html
[delay]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/delay.html
[yield]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/yield.html
-[coroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/coroutine-scope.html
-[supervisorScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/supervisor-scope.html
+[_coroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/coroutine-scope.html
+[_supervisorScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/supervisor-scope.html
[withContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/with-context.html
[withTimeout]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/with-timeout.html
[MainScope()]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-main-scope.html
@@ -284,7 +276,7 @@
<!--- INDEX kotlinx.coroutines.reactive -->
[Publisher.collect]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive/kotlinx.coroutines.reactive/org.reactivestreams.-publisher/collect.html
[Publisher.awaitSingle]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive/kotlinx.coroutines.reactive/org.reactivestreams.-publisher/await-single.html
-[publish]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive/kotlinx.coroutines.reactive/publish.html
+[kotlinx.coroutines.reactive.publish]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive/kotlinx.coroutines.reactive/publish.html
<!--- MODULE kotlinx-coroutines-rx2 -->
<!--- INDEX kotlinx.coroutines.rx2 -->
[rxFlowable]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-rx2/kotlinx.coroutines.rx2/rx-flowable.html
diff --git a/RELEASE.md b/RELEASE.md
index efb361f..b2a08b6 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -12,11 +12,15 @@
`git merge origin/master`
4. Search & replace `<old-version>` with `<version>` across the project files. Should replace in:
- * [`README.md`](README.md) (native, core, test, debug, modules)
- * [`coroutines-guide.md`](docs/coroutines-guide.md)
- * [`gradle.properties`](gradle.properties)
- * [`ui/kotlinx-coroutines-android/example-app/gradle.properties`](ui/kotlinx-coroutines-android/example-app/gradle.properties)
- * [`ui/kotlinx-coroutines-android/animation-app/gradle.properties`](ui/kotlinx-coroutines-android/animation-app/gradle.properties)
+ * Docs
+ * [`README.md`](README.md) (native, core, test, debug, modules)
+ * [`kotlinx-coroutines-debug/README.md`](kotlinx-coroutines-debug/README.md)
+ * [`kotlinx-coroutines-test/README.md`](kotlinx-coroutines-test/README.md)
+ * [`coroutines-guide-ui.md`](ui/coroutines-guide-ui.md)
+ * Properties
+ * [`gradle.properties`](gradle.properties)
+ * [`ui/kotlinx-coroutines-android/example-app/gradle.properties`](ui/kotlinx-coroutines-android/example-app/gradle.properties)
+ * [`ui/kotlinx-coroutines-android/animation-app/gradle.properties`](ui/kotlinx-coroutines-android/animation-app/gradle.properties)
* Make sure to **exclude** `CHANGES.md` from replacements.
As an alternative approach you can use `./bump-version.sh old_version new_version`
@@ -26,7 +30,7 @@
* Write each change on a single line (don't wrap with CR).
* Study commit message from previous release.
-6. Create branch for this release:
+6. Create the branch for this release:
`git checkout -b version-<version>`
7. Commit updated files to a new version branch:<br>
@@ -64,18 +68,14 @@
5. Announce new release in [Slack](https://kotlinlang.slack.com)
-6. Create a ticket to update coroutines version on [try.kotlinlang.org](try.kotlinlang.org).
- * Use [KT-30870](https://youtrack.jetbrains.com/issue/KT-30870) as a template
- * This step should be skipped for eap versions that are not merged to `master`
-
-7. Switch into `develop` branch:<br>
+6. Switch into `develop` branch:<br>
`git checkout develop`
-8. Fetch the latest `master`:<br>
+7. Fetch the latest `master`:<br>
`git fetch`
-9. Merge release from `master`:<br>
+8. Merge release from `master`:<br>
`git merge origin/master`
-0. Push updates to `develop`:<br>
+9. Push updates to `develop`:<br>
`git push`
diff --git a/benchmarks/build.gradle.kts b/benchmarks/build.gradle.kts
index 7df4510..b60dcbc 100644
--- a/benchmarks/build.gradle.kts
+++ b/benchmarks/build.gradle.kts
@@ -2,6 +2,8 @@
* Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
*/
+@file:Suppress("UnstableApiUsage")
+
import me.champeau.gradle.*
import org.jetbrains.kotlin.gradle.tasks.*
@@ -29,38 +31,12 @@
}
}
-/*
- * Due to a bug in the inliner it sometimes does not remove inlined symbols (that are later renamed) from unused code paths,
- * and it breaks JMH that tries to post-process these symbols and fails because they are renamed.
- */
-val removeRedundantFiles = tasks.register<Delete>("removeRedundantFiles") {
- delete("$buildDir/classes/kotlin/jmh/benchmarks/flow/scrabble/FlowPlaysScrabbleOpt\$play\$buildHistoOnScore\$1\$\$special\$\$inlined\$filter\$1\$1.class")
- delete("$buildDir/classes/kotlin/jmh/benchmarks/flow/scrabble/FlowPlaysScrabbleOpt\$play\$nBlanks\$1\$\$special\$\$inlined\$map\$1\$1.class")
- delete("$buildDir/classes/kotlin/jmh/benchmarks/flow/scrabble/FlowPlaysScrabbleOpt\$play\$score2\$1\$\$special\$\$inlined\$map\$1\$1.class")
- delete("$buildDir/classes/kotlin/jmh/benchmarks/flow/scrabble/FlowPlaysScrabbleOpt\$play\$bonusForDoubleLetter\$1\$\$special\$\$inlined\$map\$1\$1.class")
- delete("$buildDir/classes/kotlin/jmh/benchmarks/flow/scrabble/FlowPlaysScrabbleOpt\$play\$nBlanks\$1\$\$special\$\$inlined\$map\$1\$2\$1.class")
- delete("$buildDir/classes/kotlin/jmh/benchmarks/flow/scrabble/FlowPlaysScrabbleOpt\$play\$bonusForDoubleLetter\$1\$\$special\$\$inlined\$map\$1\$2\$1.class")
- delete("$buildDir/classes/kotlin/jmh/benchmarks/flow/scrabble/FlowPlaysScrabbleOpt\$play\$score2\$1\$\$special\$\$inlined\$map\$1\$2\$1.class")
- delete("$buildDir/classes/kotlin/jmh/benchmarks/flow/scrabble/FlowPlaysScrabbleOptKt\$\$special\$\$inlined\$collect\$1\$1.class")
- delete("$buildDir/classes/kotlin/jmh/benchmarks/flow/scrabble/FlowPlaysScrabbleOptKt\$\$special\$\$inlined\$collect\$2\$1.class")
- delete("$buildDir/classes/kotlin/jmh/benchmarks/flow/scrabble/FlowPlaysScrabbleOpt\$play\$histoOfLetters\$1\$\$special\$\$inlined\$fold\$1\$1.class")
- delete("$buildDir/classes/kotlin/jmh/benchmarks/flow/scrabble/FlowPlaysScrabbleBase\$play\$buildHistoOnScore\$1\$\$special\$\$inlined\$filter\$1\$1.class")
- delete("$buildDir/classes/kotlin/jmh/benchmarks/flow/scrabble/FlowPlaysScrabbleBase\$play\$histoOfLetters\$1\$\$special\$\$inlined\$fold\$1\$1.class")
- delete("$buildDir/classes/kotlin/jmh/benchmarks/flow/scrabble/SaneFlowPlaysScrabble\$play\$buildHistoOnScore\$1\$\$special\$\$inlined\$filter\$1\$1.class")
- // Primes
- delete("$buildDir/classes/kotlin/jmh/benchmarks/flow/misc/Numbers\$\$special\$\$inlined\$filter\$1\$2\$1.class")
- delete("$buildDir/classes/kotlin/jmh/benchmarks/flow/misc/Numbers\$\$special\$\$inlined\$filter\$1\$1.class")
-}
-
-tasks.named("jmhRunBytecodeGenerator") {
- dependsOn(removeRedundantFiles)
-}
// It is better to use the following to run benchmarks, otherwise you may get unexpected errors:
// ./gradlew --no-daemon cleanJmhJar jmh -Pjmh="MyBenchmark"
extensions.configure<JMHPluginExtension>("jmh") {
- jmhVersion = "1.21"
+ jmhVersion = "1.26"
duplicateClassesStrategy = DuplicatesStrategy.INCLUDE
failOnError = true
resultFormat = "CSV"
@@ -71,14 +47,14 @@
}
tasks.named<Jar>("jmhJar") {
- baseName = "benchmarks"
- classifier = null
- version = null
- destinationDir = file("$rootDir")
+ archiveBaseName by "benchmarks"
+ archiveClassifier by null
+ archiveVersion by null
+ destinationDirectory.file("$rootDir")
}
dependencies {
- compile("org.openjdk.jmh:jmh-core:1.21")
+ compile("org.openjdk.jmh:jmh-core:1.26")
compile("io.projectreactor:reactor-core:${version("reactor")}")
compile("io.reactivex.rxjava2:rxjava:2.1.9")
compile("com.github.akarnokd:rxjava2-extensions:0.20.8")
diff --git a/benchmarks/src/jmh/kotlin/benchmarks/ChannelSinkBenchmark.kt b/benchmarks/src/jmh/kotlin/benchmarks/ChannelSinkBenchmark.kt
index 9c7f38a..6c5b623 100644
--- a/benchmarks/src/jmh/kotlin/benchmarks/ChannelSinkBenchmark.kt
+++ b/benchmarks/src/jmh/kotlin/benchmarks/ChannelSinkBenchmark.kt
@@ -50,4 +50,22 @@
for (i in start until (start + count))
send(i)
}
+
+ // Migrated from deprecated operators, are good only for stressing channels
+
+ private fun <E> ReceiveChannel<E>.filter(context: CoroutineContext = Dispatchers.Unconfined, predicate: suspend (E) -> Boolean): ReceiveChannel<E> =
+ GlobalScope.produce(context, onCompletion = { cancel() }) {
+ for (e in this@filter) {
+ if (predicate(e)) send(e)
+ }
+ }
+
+ private suspend inline fun <E, R> ReceiveChannel<E>.fold(initial: R, operation: (acc: R, E) -> R): R {
+ var accumulator = initial
+ consumeEach {
+ accumulator = operation(accumulator, it)
+ }
+ return accumulator
+ }
}
+
diff --git a/benchmarks/src/jmh/kotlin/benchmarks/flow/CombineFlowsBenchmark.kt b/benchmarks/src/jmh/kotlin/benchmarks/flow/CombineFlowsBenchmark.kt
new file mode 100644
index 0000000..4725ced
--- /dev/null
+++ b/benchmarks/src/jmh/kotlin/benchmarks/flow/CombineFlowsBenchmark.kt
@@ -0,0 +1,34 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package benchmarks.flow
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+import org.openjdk.jmh.annotations.*
+import java.util.concurrent.*
+
+@Warmup(iterations = 5, time = 1, timeUnit = TimeUnit.SECONDS)
+@Measurement(iterations = 5, time = 1, timeUnit = TimeUnit.SECONDS)
+@Fork(value = 1)
+@BenchmarkMode(Mode.Throughput)
+@OutputTimeUnit(TimeUnit.MILLISECONDS)
+@State(Scope.Benchmark)
+open class CombineFlowsBenchmark {
+
+ @Param("10", "100", "1000")
+ private var size = 10
+
+ @Benchmark
+ fun combine() = runBlocking {
+ combine((1 until size).map { flowOf(it) }) { a -> a}.collect()
+ }
+
+ @Benchmark
+ fun combineTransform() = runBlocking {
+ val list = (1 until size).map { flowOf(it) }.toList()
+ combineTransform((1 until size).map { flowOf(it) }) { emit(it) }.collect()
+ }
+}
+
diff --git a/benchmarks/src/jmh/kotlin/benchmarks/flow/CombineTwoFlowsBenchmark.kt b/benchmarks/src/jmh/kotlin/benchmarks/flow/CombineTwoFlowsBenchmark.kt
new file mode 100644
index 0000000..f7fbc6c
--- /dev/null
+++ b/benchmarks/src/jmh/kotlin/benchmarks/flow/CombineTwoFlowsBenchmark.kt
@@ -0,0 +1,47 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package benchmarks.flow
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+import kotlinx.coroutines.flow.internal.*
+import org.openjdk.jmh.annotations.*
+import java.util.concurrent.*
+
+@Warmup(iterations = 5, time = 1, timeUnit = TimeUnit.SECONDS)
+@Measurement(iterations = 5, time = 1, timeUnit = TimeUnit.SECONDS)
+@Fork(value = 1)
+@BenchmarkMode(Mode.Throughput)
+@OutputTimeUnit(TimeUnit.MILLISECONDS)
+@State(Scope.Benchmark)
+open class CombineTwoFlowsBenchmark {
+
+ @Param("100", "100000", "1000000")
+ private var size = 100000
+
+ @Benchmark
+ fun combinePlain() = runBlocking {
+ val flow = (1 until size.toLong()).asFlow()
+ flow.combine(flow) { a, b -> a + b }.collect()
+ }
+
+ @Benchmark
+ fun combineTransform() = runBlocking {
+ val flow = (1 until size.toLong()).asFlow()
+ flow.combineTransform(flow) { a, b -> emit(a + b) }.collect()
+ }
+
+ @Benchmark
+ fun combineVararg() = runBlocking {
+ val flow = (1 until size.toLong()).asFlow()
+ combine(listOf(flow, flow)) { arr -> arr[0] + arr[1] }.collect()
+ }
+
+ @Benchmark
+ fun combineTransformVararg() = runBlocking {
+ val flow = (1 until size.toLong()).asFlow()
+ combineTransform(listOf(flow, flow)) { arr -> emit(arr[0] + arr[1]) }.collect()
+ }
+}
diff --git a/benchmarks/src/jmh/kotlin/benchmarks/flow/NumbersBenchmark.kt b/benchmarks/src/jmh/kotlin/benchmarks/flow/NumbersBenchmark.kt
index 4ebb3d0..8453f5c 100644
--- a/benchmarks/src/jmh/kotlin/benchmarks/flow/NumbersBenchmark.kt
+++ b/benchmarks/src/jmh/kotlin/benchmarks/flow/NumbersBenchmark.kt
@@ -77,14 +77,14 @@
@Benchmark
fun zipRx() {
- val numbers = rxNumbers().take(natural.toLong())
+ val numbers = rxNumbers().take(natural)
val first = numbers
.filter { it % 2L != 0L }
.map { it * it }
val second = numbers
.filter { it % 2L == 0L }
.map { it * it }
- first.zipWith(second, BiFunction<Long, Long, Long> { v1, v2 -> v1 + v2 }).filter { it % 3 == 0L }.count()
+ first.zipWith(second, { v1, v2 -> v1 + v2 }).filter { it % 3 == 0L }.count()
.blockingGet()
}
@@ -98,7 +98,7 @@
@Benchmark
fun transformationsRx(): Long {
- return rxNumbers().take(natural.toLong())
+ return rxNumbers().take(natural)
.filter { it % 2L != 0L }
.map { it * it }
.filter { (it + 1) % 3 == 0L }.count()
diff --git a/benchmarks/src/jmh/kotlin/benchmarks/tailcall/SimpleChannel.kt b/benchmarks/src/jmh/kotlin/benchmarks/tailcall/SimpleChannel.kt
index c217fca..d961dab 100644
--- a/benchmarks/src/jmh/kotlin/benchmarks/tailcall/SimpleChannel.kt
+++ b/benchmarks/src/jmh/kotlin/benchmarks/tailcall/SimpleChannel.kt
@@ -70,12 +70,12 @@
}
class CancellableChannel : SimpleChannel() {
- override suspend fun suspendReceive(): Int = suspendAtomicCancellableCoroutine {
+ override suspend fun suspendReceive(): Int = suspendCancellableCoroutine {
consumer = it.intercepted()
COROUTINE_SUSPENDED
}
- override suspend fun suspendSend(element: Int) = suspendAtomicCancellableCoroutine<Unit> {
+ override suspend fun suspendSend(element: Int) = suspendCancellableCoroutine<Unit> {
enqueuedValue = element
producer = it.intercepted()
COROUTINE_SUSPENDED
@@ -84,13 +84,13 @@
class CancellableReusableChannel : SimpleChannel() {
@Suppress("INVISIBLE_MEMBER")
- override suspend fun suspendReceive(): Int = suspendAtomicCancellableCoroutineReusable {
+ override suspend fun suspendReceive(): Int = suspendCancellableCoroutineReusable {
consumer = it.intercepted()
COROUTINE_SUSPENDED
}
@Suppress("INVISIBLE_MEMBER")
- override suspend fun suspendSend(element: Int) = suspendAtomicCancellableCoroutineReusable<Unit> {
+ override suspend fun suspendSend(element: Int) = suspendCancellableCoroutineReusable<Unit> {
enqueuedValue = element
producer = it.intercepted()
COROUTINE_SUSPENDED
diff --git a/build.gradle b/build.gradle
index a758393..79c7f35 100644
--- a/build.gradle
+++ b/build.gradle
@@ -46,13 +46,20 @@
if (using_snapshot_version) {
repositories {
mavenLocal()
- maven { url "https://oss.sonatype.org/content/repositories/snapshots" }
}
}
repositories {
jcenter()
- maven { url "https://kotlin.bintray.com/kotlinx" }
+ maven {
+ url "https://kotlin.bintray.com/kotlinx"
+ credentials {
+ username = project.hasProperty('bintrayUser') ? project.property('bintrayUser') : System.getenv('BINTRAY_USER') ?: ""
+ password = project.hasProperty('bintrayApiKey') ? project.property('bintrayApiKey') : System.getenv('BINTRAY_API_KEY') ?: ""
+ }
+ }
+ // Future replacement for kotlin-dev, with cache redirector
+ maven { url "https://cache-redirector.jetbrains.com/maven.pkg.jetbrains.space/kotlin/p/kotlin/dev" }
maven {
url "https://kotlin.bintray.com/kotlin-dev"
credentials {
@@ -76,12 +83,14 @@
// JMH plugins
classpath "com.github.jengelman.gradle.plugins:shadow:5.1.0"
}
+
+ CacheRedirector.configureBuildScript(buildscript, rootProject)
}
import org.jetbrains.kotlin.gradle.plugin.KotlinPlatformType
-// Hierarchical project structures are not fully supported in 1.3.7x MPP, enable conditionally for 1.4.x
-if (VersionNumber.parse(kotlin_version) > VersionNumber.parse("1.3.79")) {
+// todo:KLUDGE: Hierarchical project structures are not fully supported in IDEA, enable only for a regular built
+if (!Idea.active) {
ext.set("kotlin.mpp.enableGranularSourceSetsMetadata", "true")
}
@@ -139,7 +148,6 @@
// Configure repositories
allprojects {
- String projectName = it.name
repositories {
/*
* google should be first in the repository list because some of the play services
@@ -147,6 +155,8 @@
*/
google()
jcenter()
+ // Future replacement for kotlin-dev, with cache redirector
+ maven { url "https://cache-redirector.jetbrains.com/maven.pkg.jetbrains.space/kotlin/p/kotlin/dev" }
maven {
url "https://kotlin.bintray.com/kotlin-dev"
credentials {
@@ -155,7 +165,14 @@
}
}
maven { url "https://kotlin.bintray.com/kotlin-eap" }
- maven { url "https://kotlin.bintray.com/kotlinx" }
+ maven {
+ url "https://kotlin.bintray.com/kotlinx"
+ credentials {
+ username = project.hasProperty('bintrayUser') ? project.property('bintrayUser') : System.getenv('BINTRAY_USER') ?: ""
+ password = project.hasProperty('bintrayApiKey') ? project.property('bintrayApiKey') : System.getenv('BINTRAY_API_KEY') ?: ""
+ }
+ }
+ mavenLocal()
}
}
@@ -237,7 +254,14 @@
}
// Redefine source sets because we are not using 'kotlin/main/fqn' folder convention
-configure(subprojects.findAll { !sourceless.contains(it.name) && it.name != "benchmarks" && it.name != coreModule }) {
+configure(subprojects.findAll {
+ !sourceless.contains(it.name) &&
+ it.name != "benchmarks" &&
+ it.name != coreModule &&
+ it.name != "example-frontend-js"
+}) {
+ // Pure JS and pure MPP doesn't have this notion and are configured separately
+ // TODO detect it via platformOf and migrate benchmarks to the same scheme
sourceSets {
main.kotlin.srcDirs = ['src']
test.kotlin.srcDirs = ['test']
@@ -273,7 +297,14 @@
// Report Kotlin compiler version when building project
println("Using Kotlin compiler version: $org.jetbrains.kotlin.config.KotlinCompilerVersion.VERSION")
+// --------------- Cache redirector ---------------
+
+allprojects {
+ CacheRedirector.configure(project)
+}
+
// --------------- Configure sub-projects that are published ---------------
+
def publishTasks = getTasksByName("publish", true) + getTasksByName("publishNpm", true)
task deploy(dependsOn: publishTasks)
diff --git a/buildSrc/build.gradle.kts b/buildSrc/build.gradle.kts
index 91b8bda..adcbd90 100644
--- a/buildSrc/build.gradle.kts
+++ b/buildSrc/build.gradle.kts
@@ -1,11 +1,50 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+import java.util.*
+
plugins {
`kotlin-dsl`
}
+val cacheRedirectorEnabled = System.getenv("CACHE_REDIRECTOR")?.toBoolean() == true
+val buildSnapshotTrain = properties["build_snapshot_train"]?.toString()?.toBoolean() == true
+
repositories {
- gradlePluginPortal()
+ if (cacheRedirectorEnabled) {
+ maven("https://cache-redirector.jetbrains.com/plugins.gradle.org/m2")
+ maven("https://cache-redirector.jetbrains.com/dl.bintray.com/kotlin/kotlin-eap")
+ maven("https://cache-redirector.jetbrains.com/dl.bintray.com/kotlin/kotlin-dev")
+ } else {
+ maven("https://plugins.gradle.org/m2")
+ maven("https://dl.bintray.com/kotlin/kotlin-eap")
+ maven("https://dl.bintray.com/kotlin/kotlin-dev")
+ }
+
+ if (buildSnapshotTrain) {
+ mavenLocal()
+ }
}
kotlinDslPluginOptions {
experimentalWarning.set(false)
}
+
+val props = Properties().apply {
+ file("../gradle.properties").inputStream().use { load(it) }
+}
+
+fun version(target: String): String {
+ // Intercept reading from properties file
+ if (target == "kotlin") {
+ val snapshotVersion = properties["kotlin_snapshot_version"]
+ if (snapshotVersion != null) return snapshotVersion.toString()
+ }
+ return props.getProperty("${target}_version")
+}
+
+dependencies {
+ implementation(kotlin("gradle-plugin", version("kotlin")))
+ implementation("org.jetbrains.dokka:dokka-gradle-plugin:${version("dokka")}")
+}
diff --git a/buildSrc/settings.gradle.kts b/buildSrc/settings.gradle.kts
new file mode 100644
index 0000000..a6da8fd
--- /dev/null
+++ b/buildSrc/settings.gradle.kts
@@ -0,0 +1,18 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+pluginManagement {
+ val build_snapshot_train: String? by settings
+ repositories {
+ val cacheRedirectorEnabled = System.getenv("CACHE_REDIRECTOR")?.toBoolean() == true
+ if (cacheRedirectorEnabled) {
+ println("Redirecting repositories for buildSrc buildscript")
+ maven("https://cache-redirector.jetbrains.com/plugins.gradle.org/m2")
+ } else {
+ maven("https://plugins.gradle.org/m2")
+ }
+ if (build_snapshot_train?.toBoolean() == true) {
+ mavenLocal()
+ }
+ }
+}
diff --git a/buildSrc/src/main/kotlin/CacheRedirector.kt b/buildSrc/src/main/kotlin/CacheRedirector.kt
new file mode 100644
index 0000000..7cf01d8
--- /dev/null
+++ b/buildSrc/src/main/kotlin/CacheRedirector.kt
@@ -0,0 +1,152 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+import org.gradle.api.*
+import org.gradle.api.artifacts.dsl.*
+import org.gradle.api.artifacts.repositories.*
+import org.gradle.api.initialization.dsl.*
+import java.net.*
+
+/**
+ * Enabled via environment variable, so that it can be reliably accessed from any piece of the build script,
+ * including buildSrc within TeamCity CI.
+ */
+private val cacheRedirectorEnabled = System.getenv("CACHE_REDIRECTOR")?.toBoolean() == true
+
+/**
+ * The list of repositories supported by cache redirector should be synced with the list at https://cache-redirector.jetbrains.com/redirects_generated.html
+ * To add a repository to the list create an issue in ADM project (example issue https://youtrack.jetbrains.com/issue/IJI-149)
+ */
+private val mirroredUrls = listOf(
+ "https://cdn.azul.com/zulu/bin",
+ "https://clojars.org/repo",
+ "https://dl.bintray.com/d10xa/maven",
+ "https://dl.bintray.com/groovy/maven",
+ "https://dl.bintray.com/jetbrains/maven-patched",
+ "https://dl.bintray.com/jetbrains/scala-plugin-deps",
+ "https://dl.bintray.com/kodein-framework/Kodein-DI",
+ "https://dl.bintray.com/konsoletyper/teavm",
+ "https://dl.bintray.com/kotlin/kotlin-dev",
+ "https://dl.bintray.com/kotlin/kotlin-eap",
+ "https://dl.bintray.com/kotlin/kotlinx.html",
+ "https://dl.bintray.com/kotlin/kotlinx",
+ "https://dl.bintray.com/kotlin/ktor",
+ "https://dl.bintray.com/scalacenter/releases",
+ "https://dl.bintray.com/scalamacros/maven",
+ "https://dl.bintray.com/kotlin/exposed",
+ "https://dl.bintray.com/cy6ergn0m/maven",
+ "https://dl.bintray.com/kotlin/kotlin-js-wrappers",
+ "https://dl.google.com/android/repository",
+ "https://dl.google.com/dl/android/maven2",
+ "https://dl.google.com/dl/android/studio/ide-zips",
+ "https://dl.google.com/go",
+ "https://download.jetbrains.com",
+ "https://jcenter.bintray.com",
+ "https://jetbrains.bintray.com/dekaf",
+ "https://jetbrains.bintray.com/intellij-jbr",
+ "https://jetbrains.bintray.com/intellij-jdk",
+ "https://jetbrains.bintray.com/intellij-plugin-service",
+ "https://jetbrains.bintray.com/intellij-terraform",
+ "https://jetbrains.bintray.com/intellij-third-party-dependencies",
+ "https://jetbrains.bintray.com/jediterm",
+ "https://jetbrains.bintray.com/kotlin-native-dependencies",
+ "https://jetbrains.bintray.com/markdown",
+ "https://jetbrains.bintray.com/teamcity-rest-client",
+ "https://jetbrains.bintray.com/test-discovery",
+ "https://jetbrains.bintray.com/wormhole",
+ "https://jitpack.io",
+ "https://maven.pkg.jetbrains.space/kotlin/p/kotlin/dev",
+ "https://maven.pkg.jetbrains.space/kotlin/p/kotlin/bootstrap",
+ "https://maven.pkg.jetbrains.space/kotlin/p/kotlin/eap",
+ "https://kotlin.bintray.com/dukat",
+ "https://kotlin.bintray.com/kotlin-dependencies",
+ "https://oss.sonatype.org/content/repositories/releases",
+ "https://oss.sonatype.org/content/repositories/snapshots",
+ "https://oss.sonatype.org/content/repositories/staging",
+ "https://packages.confluent.io/maven/",
+ "https://plugins.gradle.org/m2",
+ "https://plugins.jetbrains.com/maven",
+ "https://repo1.maven.org/maven2",
+ "https://repo.grails.org/grails/core",
+ "https://repo.jenkins-ci.org/releases",
+ "https://repo.maven.apache.org/maven2",
+ "https://repo.spring.io/milestone",
+ "https://repo.typesafe.com/typesafe/ivy-releases",
+ "https://services.gradle.org",
+ "https://www.exasol.com/artifactory/exasol-releases",
+ "https://www.myget.org/F/intellij-go-snapshots/maven",
+ "https://www.myget.org/F/rd-model-snapshots/maven",
+ "https://www.myget.org/F/rd-snapshots/maven",
+ "https://www.python.org/ftp",
+ "https://www.jetbrains.com/intellij-repository/nightly",
+ "https://www.jetbrains.com/intellij-repository/releases",
+ "https://www.jetbrains.com/intellij-repository/snapshots"
+)
+
+private val aliases = mapOf(
+ "https://repo.maven.apache.org/maven2" to "https://repo1.maven.org/maven2", // Maven Central
+ "https://kotlin.bintray.com/kotlin-dev" to "https://dl.bintray.com/kotlin/kotlin-dev",
+ "https://kotlin.bintray.com/kotlin-eap" to "https://dl.bintray.com/kotlin/kotlin-eap",
+ "https://kotlin.bintray.com/kotlinx" to "https://dl.bintray.com/kotlin/kotlinx"
+)
+
+private fun URI.toCacheRedirectorUri() = URI("https://cache-redirector.jetbrains.com/$host/$path")
+
+private fun URI.maybeRedirect(): URI? {
+ val url = toString().trimEnd('/')
+ val dealiasedUrl = aliases.getOrDefault(url, url)
+
+ return if (mirroredUrls.any { dealiasedUrl.startsWith(it) }) {
+ URI(dealiasedUrl).toCacheRedirectorUri()
+ } else {
+ null
+ }
+}
+
+private fun URI.isCachedOrLocal() = scheme == "file" ||
+ host == "cache-redirector.jetbrains.com" ||
+ host == "teamcity.jetbrains.com" ||
+ host == "buildserver.labs.intellij.net"
+
+private fun Project.checkRedirectUrl(url: URI, containerName: String): URI {
+ val redirected = url.maybeRedirect()
+ if (redirected == null && !url.isCachedOrLocal()) {
+ val msg = "Repository $url in $containerName should be cached with cache-redirector"
+ val details = "Using non cached repository may lead to download failures in CI builds." +
+ " Check buildSrc/src/main/kotlin/CacheRedirector.kt for details."
+ logger.warn("WARNING - $msg\n$details")
+ }
+ return if (cacheRedirectorEnabled) redirected ?: url else url
+}
+
+private fun Project.checkRedirect(repositories: RepositoryHandler, containerName: String) {
+ if (cacheRedirectorEnabled) {
+ logger.info("Redirecting repositories for $containerName")
+ }
+ for (repository in repositories) {
+ when (repository) {
+ is MavenArtifactRepository -> repository.url = checkRedirectUrl(repository.url, containerName)
+ is IvyArtifactRepository -> repository.url = checkRedirectUrl(repository.url, containerName)
+ }
+ }
+}
+
+// Used from Groovy scripts
+object CacheRedirector {
+ /**
+ * Substitutes repositories in buildScript { } block.
+ */
+ @JvmStatic
+ fun ScriptHandler.configureBuildScript(rootProject: Project) {
+ rootProject.checkRedirect(repositories, "${rootProject.displayName} buildscript")
+ }
+
+ /**
+ * Substitutes repositories in a project.
+ */
+ @JvmStatic
+ fun Project.configure() {
+ checkRedirect(repositories, displayName)
+ }
+}
diff --git a/buildSrc/src/main/kotlin/Dokka.kt b/buildSrc/src/main/kotlin/Dokka.kt
new file mode 100644
index 0000000..dd5f1ea
--- /dev/null
+++ b/buildSrc/src/main/kotlin/Dokka.kt
@@ -0,0 +1,26 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+import org.gradle.api.Project
+import org.gradle.kotlin.dsl.delegateClosureOf
+import org.gradle.kotlin.dsl.withType
+import org.jetbrains.dokka.DokkaConfiguration.ExternalDocumentationLink.Builder
+import org.jetbrains.dokka.gradle.DokkaTask
+import java.io.File
+import java.net.URL
+
+/**
+ * Package-list by external URL for documentation generation.
+ */
+fun Project.externalDocumentationLink(
+ url: String,
+ packageList: File = projectDir.resolve("package.list")
+) {
+ tasks.withType<DokkaTask>().configureEach {
+ externalDocumentationLink(delegateClosureOf<Builder> {
+ this.url = URL(url)
+ packageListUrl = packageList.toPath().toUri().toURL()
+ })
+ }
+}
diff --git a/buildSrc/src/main/kotlin/Idea.kt b/buildSrc/src/main/kotlin/Idea.kt
index 802b387..615b8aa 100644
--- a/buildSrc/src/main/kotlin/Idea.kt
+++ b/buildSrc/src/main/kotlin/Idea.kt
@@ -1,4 +1,5 @@
object Idea {
+ @JvmStatic // for Gradle
val active: Boolean
get() = System.getProperty("idea.active") == "true"
}
diff --git a/buildSrc/src/main/kotlin/MavenCentral.kt b/buildSrc/src/main/kotlin/MavenCentral.kt
index 0d7e18c..3efaf33 100644
--- a/buildSrc/src/main/kotlin/MavenCentral.kt
+++ b/buildSrc/src/main/kotlin/MavenCentral.kt
@@ -5,10 +5,9 @@
@file:Suppress("UnstableApiUsage")
import org.gradle.api.Project
-import org.gradle.api.provider.Property
import org.gradle.api.publish.maven.MavenPom
-// --------------- pom configuration ---------------
+// Pom configuration
fun MavenPom.configureMavenCentralMetadata(project: Project) {
name by project.name
@@ -36,7 +35,3 @@
url by "https://github.com/Kotlin/kotlinx.coroutines"
}
}
-
-private infix fun <T> Property<T>.by(value: T) {
- set(value)
-}
diff --git a/buildSrc/src/main/kotlin/Platform.kt b/buildSrc/src/main/kotlin/Platform.kt
index 4cacd9e..b667a13 100644
--- a/buildSrc/src/main/kotlin/Platform.kt
+++ b/buildSrc/src/main/kotlin/Platform.kt
@@ -1,5 +1,6 @@
import org.gradle.api.Project
+// Use from Groovy for now
fun platformOf(project: Project): String =
when (project.name.substringAfterLast("-")) {
"js" -> "js"
diff --git a/buildSrc/src/main/kotlin/Properties.kt b/buildSrc/src/main/kotlin/Properties.kt
new file mode 100644
index 0000000..a0968ee
--- /dev/null
+++ b/buildSrc/src/main/kotlin/Properties.kt
@@ -0,0 +1,11 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+@file:Suppress("UnstableApiUsage")
+
+import org.gradle.api.provider.*
+
+infix fun <T> Property<T>.by(value: T) {
+ set(value)
+}
diff --git a/buildSrc/src/main/kotlin/RunR8.kt b/buildSrc/src/main/kotlin/RunR8.kt
new file mode 100644
index 0000000..d9eba79
--- /dev/null
+++ b/buildSrc/src/main/kotlin/RunR8.kt
@@ -0,0 +1,52 @@
+import org.gradle.api.tasks.InputFile
+import org.gradle.api.tasks.InputFiles
+import org.gradle.api.tasks.JavaExec
+import org.gradle.api.tasks.OutputDirectory
+import org.gradle.api.tasks.bundling.Zip
+import org.gradle.kotlin.dsl.get
+import org.gradle.kotlin.dsl.named
+import java.io.File
+
+/*
+ * Task used by our ui/android tests to test minification results
+ * and keep track of size of the binary.
+ * TODO move back to kotlinx-coroutines-android when it's migrated to the kts
+ */
+open class RunR8 : JavaExec() {
+
+ @OutputDirectory
+ lateinit var outputDex: File
+
+ @InputFile
+ lateinit var inputConfig: File
+
+ @InputFile
+ val inputConfigCommon: File = File("testdata/r8-test-common.pro")
+
+ @InputFiles
+ val jarFile: File = project.tasks.named<Zip>("jar").get().archivePath
+
+ init {
+ classpath = project.configurations["r8"]
+ main = "com.android.tools.r8.R8"
+ }
+
+ override fun exec() {
+ // Resolve classpath only during execution
+ val arguments = mutableListOf(
+ "--release",
+ "--no-desugaring",
+ "--output", outputDex.absolutePath,
+ "--pg-conf", inputConfig.absolutePath
+ )
+ arguments.addAll(project.configurations["runtimeClasspath"].files.map { it.absolutePath })
+ arguments.add(jarFile.absolutePath)
+
+ args = arguments
+
+ project.delete(outputDex)
+ outputDex.mkdirs()
+
+ super.exec()
+ }
+}
diff --git a/buildSrc/src/main/kotlin/UnpackAar.kt b/buildSrc/src/main/kotlin/UnpackAar.kt
new file mode 100644
index 0000000..c7d0b53
--- /dev/null
+++ b/buildSrc/src/main/kotlin/UnpackAar.kt
@@ -0,0 +1,32 @@
+import org.gradle.api.artifacts.transform.InputArtifact
+import org.gradle.api.artifacts.transform.TransformAction
+import org.gradle.api.artifacts.transform.TransformOutputs
+import org.gradle.api.artifacts.transform.TransformParameters
+import org.gradle.api.file.FileSystemLocation
+import org.gradle.api.provider.Provider
+import java.io.File
+import java.nio.file.Files
+import java.util.zip.ZipEntry
+import java.util.zip.ZipFile
+
+// TODO move back to kotlinx-coroutines-play-services when it's migrated to the kts
+@Suppress("UnstableApiUsage")
+abstract class UnpackAar : TransformAction<TransformParameters.None> {
+ @get:InputArtifact
+ abstract val inputArtifact: Provider<FileSystemLocation>
+
+ override fun transform(outputs: TransformOutputs) {
+ ZipFile(inputArtifact.get().asFile).use { zip ->
+ zip.entries().asSequence()
+ .filter { !it.isDirectory }
+ .filter { it.name.endsWith(".jar") }
+ .forEach { zip.unzip(it, outputs.file(it.name)) }
+ }
+ }
+}
+
+private fun ZipFile.unzip(entry: ZipEntry, output: File) {
+ getInputStream(entry).use {
+ Files.copy(it, output.toPath())
+ }
+}
diff --git a/coroutines-guide.md b/coroutines-guide.md
index 4b3c09c..09cfb93 100644
--- a/coroutines-guide.md
+++ b/coroutines-guide.md
@@ -20,6 +20,7 @@
* <a name='closing-resources-with-finally'></a>[Closing resources with `finally`](docs/cancellation-and-timeouts.md#closing-resources-with-finally)
* <a name='run-non-cancellable-block'></a>[Run non-cancellable block](docs/cancellation-and-timeouts.md#run-non-cancellable-block)
* <a name='timeout'></a>[Timeout](docs/cancellation-and-timeouts.md#timeout)
+ * <a name='asynchronous-timeout-and-resources'></a>[Asynchronous timeout and resources](docs/cancellation-and-timeouts.md#asynchronous-timeout-and-resources)
<!--- TOC_REF docs/composing-suspending-functions.md -->
* <a name='composing-suspending-functions'></a>[Composing Suspending Functions](docs/composing-suspending-functions.md#composing-suspending-functions)
* <a name='sequential-by-default'></a>[Sequential by default](docs/composing-suspending-functions.md#sequential-by-default)
@@ -32,6 +33,8 @@
* <a name='dispatchers-and-threads'></a>[Dispatchers and threads](docs/coroutine-context-and-dispatchers.md#dispatchers-and-threads)
* <a name='unconfined-vs-confined-dispatcher'></a>[Unconfined vs confined dispatcher](docs/coroutine-context-and-dispatchers.md#unconfined-vs-confined-dispatcher)
* <a name='debugging-coroutines-and-threads'></a>[Debugging coroutines and threads](docs/coroutine-context-and-dispatchers.md#debugging-coroutines-and-threads)
+ * <a name='debugging-with-idea'></a>[Debugging with IDEA](docs/coroutine-context-and-dispatchers.md#debugging-with-idea)
+ * <a name='debugging-using-logging'></a>[Debugging using logging](docs/coroutine-context-and-dispatchers.md#debugging-using-logging)
* <a name='jumping-between-threads'></a>[Jumping between threads](docs/coroutine-context-and-dispatchers.md#jumping-between-threads)
* <a name='job-in-the-context'></a>[Job in the context](docs/coroutine-context-and-dispatchers.md#job-in-the-context)
* <a name='children-of-a-coroutine'></a>[Children of a coroutine](docs/coroutine-context-and-dispatchers.md#children-of-a-coroutine)
diff --git a/docs/basics.md b/docs/basics.md
index cb64328..8aca23a 100644
--- a/docs/basics.md
+++ b/docs/basics.md
@@ -235,12 +235,12 @@
### Scope builder
In addition to the coroutine scope provided by different builders, it is possible to declare your own scope using the
-[coroutineScope] builder. It creates a coroutine scope and does not complete until all launched children complete.
+[coroutineScope][_coroutineScope] builder. It creates a coroutine scope and does not complete until all launched children complete.
-[runBlocking] and [coroutineScope] may look similar because they both wait for their body and all its children to complete.
+[runBlocking] and [coroutineScope][_coroutineScope] may look similar because they both wait for their body and all its children to complete.
The main difference is that the [runBlocking] method _blocks_ the current thread for waiting,
-while [coroutineScope] just suspends, releasing the underlying thread for other usages.
-Because of that difference, [runBlocking] is a regular function and [coroutineScope] is a suspending function.
+while [coroutineScope][_coroutineScope] just suspends, releasing the underlying thread for other usages.
+Because of that difference, [runBlocking] is a regular function and [coroutineScope][_coroutineScope] is a suspending function.
It can be demonstrated by the following example:
@@ -281,7 +281,7 @@
-->
Note that right after the "Task from coroutine scope" message (while waiting for nested launch)
- "Task from runBlocking" is executed and printed — even though the [coroutineScope] is not completed yet.
+ "Task from runBlocking" is executed and printed — even though the [coroutineScope][_coroutineScope] is not completed yet.
### Extract function refactoring
@@ -403,7 +403,7 @@
[runBlocking]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/run-blocking.html
[Job]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/index.html
[Job.join]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/join.html
-[coroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/coroutine-scope.html
+[_coroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/coroutine-scope.html
[CoroutineScope()]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope.html
<!--- END -->
diff --git a/docs/cancellation-and-timeouts.md b/docs/cancellation-and-timeouts.md
index d8d5b7b..b296bde 100644
--- a/docs/cancellation-and-timeouts.md
+++ b/docs/cancellation-and-timeouts.md
@@ -11,6 +11,7 @@
* [Closing resources with `finally`](#closing-resources-with-finally)
* [Run non-cancellable block](#run-non-cancellable-block)
* [Timeout](#timeout)
+ * [Asynchronous timeout and resources](#asynchronous-timeout-and-resources)
<!--- END -->
@@ -355,6 +356,114 @@
<!--- TEST -->
+### Asynchronous timeout and resources
+
+<!--
+ NOTE: Don't change this section name. It is being referenced to from within KDoc of withTimeout functions.
+-->
+
+The timeout event in [withTimeout] is asynchronous with respect to the code running in its block and may happen at any time,
+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.
+
+<div class="sample" markdown="1" theme="idea" data-min-compiler-version="1.3">
+
+```kotlin
+import kotlinx.coroutines.*
+
+//sampleStart
+var acquired = 0
+
+class Resource {
+ init { acquired++ } // Acquire the resource
+ fun close() { acquired-- } // Release the resource
+}
+
+fun main() {
+ runBlocking {
+ repeat(100_000) { // Launch 100K coroutines
+ launch {
+ val resource = withTimeout(60) { // Timeout of 60 ms
+ delay(50) // Delay for 50 ms
+ Resource() // Acquire a resource and return it from withTimeout block
+ }
+ resource.close() // Release the resource
+ }
+ }
+ }
+ // Outside of runBlocking all coroutines have completed
+ println(acquired) // Print the number of resources still acquired
+}
+//sampleEnd
+```
+
+</div>
+
+> You can get the full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-cancel-08.kt).
+
+<!--- 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.
+
+> 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 next chapter
+> on coroutine context.
+
+To workaround this problem you can store a reference to the resource in the variable as opposed to returning it
+from the `withTimeout` block.
+
+<div class="sample" markdown="1" theme="idea" data-min-compiler-version="1.3">
+
+```kotlin
+import kotlinx.coroutines.*
+
+var acquired = 0
+
+class Resource {
+ init { acquired++ } // Acquire the resource
+ fun close() { acquired-- } // Release the resource
+}
+
+fun main() {
+//sampleStart
+ runBlocking {
+ repeat(100_000) { // Launch 100K coroutines
+ launch {
+ var resource: Resource? = null // Not acquired yet
+ try {
+ withTimeout(60) { // Timeout of 60 ms
+ delay(50) // Delay for 50 ms
+ resource = Resource() // Store a resource to the variable if acquired
+ }
+ // We can do something else with the resource here
+ } finally {
+ resource?.close() // Release the resource if it was acquired
+ }
+ }
+ }
+ }
+ // Outside of runBlocking all coroutines have completed
+ println(acquired) // Print the number of resources still acquired
+//sampleEnd
+}
+```
+
+</div>
+
+> You can get the full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-cancel-09.kt).
+
+This example always prints zero. Resources do not leak.
+
+<!--- TEST
+0
+-->
+
<!--- MODULE kotlinx-coroutines-core -->
<!--- INDEX kotlinx.coroutines -->
[launch]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/launch.html
diff --git a/docs/composing-suspending-functions.md b/docs/composing-suspending-functions.md
index 013076a..81b6f53 100644
--- a/docs/composing-suspending-functions.md
+++ b/docs/composing-suspending-functions.md
@@ -308,7 +308,7 @@
Let us take the [Concurrent using async](#concurrent-using-async) example and extract a function that
concurrently performs `doSomethingUsefulOne` and `doSomethingUsefulTwo` and returns the sum of their results.
Because the [async] coroutine builder is defined as an extension on [CoroutineScope], we need to have it in the
-scope and that is what the [coroutineScope] function provides:
+scope and that is what the [coroutineScope][_coroutineScope] function provides:
<div class="sample" markdown="1" theme="idea" data-highlight-only>
@@ -431,5 +431,5 @@
[Job.start]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/start.html
[GlobalScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-global-scope/index.html
[CoroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/index.html
-[coroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/coroutine-scope.html
+[_coroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/coroutine-scope.html
<!--- END -->
diff --git a/docs/coroutine-context-and-dispatchers.md b/docs/coroutine-context-and-dispatchers.md
index 4909206..36e049d 100644
--- a/docs/coroutine-context-and-dispatchers.md
+++ b/docs/coroutine-context-and-dispatchers.md
@@ -8,6 +8,8 @@
* [Dispatchers and threads](#dispatchers-and-threads)
* [Unconfined vs confined dispatcher](#unconfined-vs-confined-dispatcher)
* [Debugging coroutines and threads](#debugging-coroutines-and-threads)
+ * [Debugging with IDEA](#debugging-with-idea)
+ * [Debugging using logging](#debugging-using-logging)
* [Jumping between threads](#jumping-between-threads)
* [Job in the context](#job-in-the-context)
* [Children of a coroutine](#children-of-a-coroutine)
@@ -155,8 +157,34 @@
Coroutines can suspend on one thread and resume on another thread.
Even with a single-threaded dispatcher it might be hard to
-figure out what the coroutine was doing, where, and when. The common approach to debugging applications with
-threads is to print the thread name in the log file on each log statement. This feature is universally supported
+figure out what the coroutine was doing, where, and when if you don't have special tooling.
+
+#### Debugging with IDEA
+
+The Coroutine Debugger of the Kotlin plugin simplifies debugging coroutines in IntelliJ IDEA.
+
+> Debugging works for versions 1.3.8 or later of `kotlinx-coroutines-core`.
+
+The **Debug** tool window contains the **Coroutines** tab. In this tab, you can find information about both currently running and suspended coroutines.
+The coroutines are grouped by the dispatcher they are running on.
+
+
+
+With the coroutine debugger, you can:
+* Check the state of each coroutine.
+* See the values of local and captured variables for both running and suspended coroutines.
+* See a full coroutine creation stack, as well as a call stack inside the coroutine. The stack includes all frames with
+variable values, even those that would be lost during standard debugging.
+* Get a full report that contains the state of each coroutine and its stack. To obtain it, right-click inside the **Coroutines** tab, and then click **Get Coroutines Dump**.
+
+To start coroutine debugging, you just need to set breakpoints and run the application in debug mode.
+
+Learn more about coroutines debugging in the [tutorial](https://kotlinlang.org/docs/tutorials/coroutines/debug-coroutines-with-idea.html).
+
+#### Debugging using logging
+
+Another approach to debugging applications with
+threads without Coroutine Debugger is to print the thread name in the log file on each log statement. This feature is universally supported
by logging frameworks. When using coroutines, the thread name alone does not give much of a context, so
`kotlinx.coroutines` includes debugging facilities to make it easier.
@@ -652,7 +680,7 @@
potentially concurrent modifications to the variable in this mutable box.
For advanced usage, for example for integration with logging MDC, transactional contexts or any other libraries
-which internally use thread-locals for passing data, see documentation of the [ThreadContextElement] interface
+which internally use thread-locals for passing data, see the documentation of the [ThreadContextElement] interface
that should be implemented.
<!--- MODULE kotlinx-coroutines-core -->
diff --git a/docs/coroutines-guide.md b/docs/coroutines-guide.md
index e3f18d2..2d15a7b 100644
--- a/docs/coroutines-guide.md
+++ b/docs/coroutines-guide.md
@@ -10,7 +10,7 @@
This is a guide on core features of `kotlinx.coroutines` with a series of examples, divided up into different topics.
-In order to use coroutines as well as follow the examples in this guide, you need to add a dependency on `kotlinx-coroutines-core` module as explained
+In order to use coroutines as well as follow the examples in this guide, you need to add a dependency on the `kotlinx-coroutines-core` module as explained
[in the project README](../README.md#using-in-your-projects).
## Table of contents
diff --git a/docs/exception-handling.md b/docs/exception-handling.md
index 5618caf..a307021 100644
--- a/docs/exception-handling.md
+++ b/docs/exception-handling.md
@@ -19,7 +19,7 @@
## Exception Handling
This section covers exception handling and cancellation on exceptions.
-We already know that cancelled coroutine throws [CancellationException] in suspension points and that it
+We already know that a cancelled coroutine throws [CancellationException] in suspension points and that it
is ignored by the coroutines' machinery. Here we look at what happens if an exception is thrown during cancellation or multiple children of the same
coroutine throw an exception.
@@ -413,9 +413,9 @@
#### Supervision scope
-Instead of [coroutineScope], we can use [supervisorScope] for _scoped_ concurrency. It propagates the cancellation
+Instead of [coroutineScope][_coroutineScope], we can use [supervisorScope][_supervisorScope] for _scoped_ concurrency. It propagates the cancellation
in one direction only and cancels all its children only if it failed itself. It also waits for all children before completion
-just like [coroutineScope] does.
+just like [coroutineScope][_coroutineScope] does.
<div class="sample" markdown="1" theme="idea" data-highlight-only>
@@ -464,7 +464,7 @@
Another crucial difference between regular and supervisor jobs is exception handling.
Every child should handle its exceptions by itself via the exception handling mechanism.
This difference comes from the fact that child's failure does not propagate to the parent.
-It means that coroutines launched directly inside the [supervisorScope] _do_ use the [CoroutineExceptionHandler]
+It means that coroutines launched directly inside the [supervisorScope][_supervisorScope] _do_ use the [CoroutineExceptionHandler]
that is installed in their scope in the same way as root coroutines do
(see the [CoroutineExceptionHandler](#coroutineexceptionhandler) section for details).
@@ -517,8 +517,8 @@
[runBlocking]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/run-blocking.html
[SupervisorJob()]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-supervisor-job.html
[Job()]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job.html
-[coroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/coroutine-scope.html
-[supervisorScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/supervisor-scope.html
+[_coroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/coroutine-scope.html
+[_supervisorScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/supervisor-scope.html
<!--- INDEX kotlinx.coroutines.channels -->
[actor]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/actor.html
[produce]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/produce.html
diff --git a/docs/flow.md b/docs/flow.md
index 143f9e9..4374e7a 100644
--- a/docs/flow.md
+++ b/docs/flow.md
@@ -50,7 +50,7 @@
## Asynchronous Flow
-Suspending functions asynchronously returns a single value, but how can we return
+A suspending function asynchronously returns a single value, but how can we return
multiple asynchronously computed values? This is where Kotlin Flows come in.
### Representing multiple values
@@ -153,7 +153,7 @@
#### Flows
Using the `List<Int>` result type, means we can only return all the values at once. To represent
-the stream of values that are being asynchronously computed, we can use a [`Flow<Int>`][Flow] type just like we would the `Sequence<Int>` type for synchronously computed values:
+the stream of values that are being asynchronously computed, we can use a [`Flow<Int>`][Flow] type just like we would use the `Sequence<Int>` type for synchronously computed values:
<div class="sample" markdown="1" theme="idea" data-min-compiler-version="1.3">
@@ -203,7 +203,7 @@
Notice the following differences in the code with the [Flow] from the earlier examples:
-* A builder function for [Flow] type is called [flow].
+* A builder function for [Flow] type is called [flow][_flow].
* Code inside the `flow { ... }` builder block can suspend.
* The `simple` function is no longer marked with `suspend` modifier.
* Values are _emitted_ from the flow using [emit][FlowCollector.emit] function.
@@ -214,7 +214,7 @@
### Flows are cold
-Flows are _cold_ streams similar to sequences — the code inside a [flow] builder does not
+Flows are _cold_ streams similar to sequences — the code inside a [flow][_flow] builder does not
run until the flow is collected. This becomes clear in the following example:
<div class="sample" markdown="1" theme="idea" data-min-compiler-version="1.3">
@@ -1463,13 +1463,15 @@
A "Caught ..." message is not printed despite there being a `catch` operator:
-<!--- TEST EXCEPTION
+```text
Emitting 1
1
Emitting 2
Exception in thread "main" java.lang.IllegalStateException: Collected 2
at ...
--->
+```
+
+<!--- TEST EXCEPTION -->
#### Catching declaratively
@@ -1510,12 +1512,14 @@
Now we can see that a "Caught ..." message is printed and so we can catch all the exceptions without explicitly
using a `try/catch` block:
-<!--- TEST EXCEPTION
+```text
Emitting 1
1
Emitting 2
Caught java.lang.IllegalStateException: Collected 2
--->
+```
+
+<!--- TEST EXCEPTION -->
### Flow completion
@@ -1781,7 +1785,7 @@
### Flow cancellation checks
-For convenience, the [flow] builder performs additional [ensureActive] checks for cancellation on each emitted value.
+For convenience, the [flow][_flow] builder performs additional [ensureActive] checks for cancellation on each emitted value.
It means that a busy loop emitting from a `flow { ... }` is cancellable:
<div class="sample" markdown="1" theme="idea" data-min-compiler-version="1.3">
@@ -1940,7 +1944,7 @@
[CancellationException]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-cancellation-exception/index.html
<!--- INDEX kotlinx.coroutines.flow -->
[Flow]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html
-[flow]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/flow.html
+[_flow]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/flow.html
[FlowCollector.emit]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow-collector/emit.html
[collect]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/collect.html
[flowOf]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/flow-of.html
diff --git a/docs/images/coroutine-idea-debugging-1.png b/docs/images/coroutine-idea-debugging-1.png
new file mode 100644
index 0000000..0afe992
--- /dev/null
+++ b/docs/images/coroutine-idea-debugging-1.png
Binary files differ
diff --git a/docs/knit.properties b/docs/knit.properties
index ab2508a..2028ecb 100644
--- a/docs/knit.properties
+++ b/docs/knit.properties
@@ -4,19 +4,7 @@
knit.package=kotlinx.coroutines.guide
knit.dir=../kotlinx-coroutines-core/jvm/test/guide/
-knit.pattern=example-[a-zA-Z0-9-]+-##\\.kt
-knit.include=knit.code.include
test.package=kotlinx.coroutines.guide.test
test.dir=../kotlinx-coroutines-core/jvm/test/guide/test/
-test.template=knit.test.template
-# Various test validation modes and their corresponding methods from TestUtil
-test.mode.=verifyLines
-test.mode.STARTS_WITH=verifyLinesStartWith
-test.mode.ARBITRARY_TIME=verifyLinesArbitraryTime
-test.mode.FLEXIBLE_TIME=verifyLinesFlexibleTime
-test.mode.FLEXIBLE_THREAD=verifyLinesFlexibleThread
-test.mode.LINES_START_UNORDERED=verifyLinesStartUnordered
-test.mode.LINES_START=verifyLinesStart
-test.mode.EXCEPTION=verifyExceptions
\ No newline at end of file
diff --git a/docs/knit.test.template b/docs/knit.test.template
index a912555..727493c 100644
--- a/docs/knit.test.template
+++ b/docs/knit.test.template
@@ -5,6 +5,7 @@
// This file was automatically generated from ${file.name} by Knit tool. Do not edit.
package ${test.package}
+import kotlinx.coroutines.knit.*
import org.junit.Test
class ${test.name} {
diff --git a/docs/shared-mutable-state-and-concurrency.md b/docs/shared-mutable-state-and-concurrency.md
index 316d56e..8b83ad0 100644
--- a/docs/shared-mutable-state-and-concurrency.md
+++ b/docs/shared-mutable-state-and-concurrency.md
@@ -24,7 +24,7 @@
### The problem
-Let us launch a hundred coroutines all doing the same action thousand times.
+Let us launch a hundred coroutines all doing the same action a thousand times.
We'll also measure their completion time for further comparisons:
<div class="sample" markdown="1" theme="idea" data-highlight-only>
@@ -102,7 +102,7 @@
### Volatiles are of no help
-There is common misconception that making a variable `volatile` solves concurrency problem. Let us try it:
+There is a common misconception that making a variable `volatile` solves concurrency problem. Let us try it:
<!--- CLEAR -->
@@ -158,7 +158,7 @@
### Thread-safe data structures
The general solution that works both for threads and for coroutines is to use a thread-safe (aka synchronized,
-linearizable, or atomic) data structure that provides all the necessarily synchronization for the corresponding
+linearizable, or atomic) data structure that provides all the necessary synchronization for the corresponding
operations that needs to be performed on a shared state.
In the case of a simple counter we can use `AtomicInteger` class which has atomic `incrementAndGet` operations:
diff --git a/gradle.properties b/gradle.properties
index 6a1ae65..1ffa02d 100644
--- a/gradle.properties
+++ b/gradle.properties
@@ -3,14 +3,14 @@
#
# Kotlin
-version=1.3.8-SNAPSHOT
+version=1.4.1-SNAPSHOT
group=org.jetbrains.kotlinx
-kotlin_version=1.3.71
+kotlin_version=1.4.0
# Dependencies
junit_version=4.12
-atomicfu_version=0.14.2
-knit_version=0.1.3
+atomicfu_version=0.14.4
+knit_version=0.2.2
html_version=0.6.8
lincheck_version=2.7.1
dokka_version=0.9.16-rdev-2-mpp-hacks
@@ -36,19 +36,21 @@
gradle_node_version=1.2.0
node_version=8.9.3
npm_version=5.7.1
-mocha_version=4.1.0
+mocha_version=6.2.2
mocha_headless_chrome_version=1.8.2
-mocha_teamcity_reporter_version=2.2.2
-source_map_support_version=0.5.3
+mocha_teamcity_reporter_version=3.0.0
+source_map_support_version=0.5.16
+jsdom_version=15.2.1
+jsdom_global_version=3.0.2
# Settings
kotlin.incremental.multiplatform=true
kotlin.native.ignoreDisabledTargets=true
-# Site deneration
+# Site generation
jekyll_version=4.0
-# JS IR baceknd sometimes crashes with out-of-memory
+# JS IR backend sometimes crashes with out-of-memory
# TODO: Remove once KT-37187 is fixed
org.gradle.jvmargs=-Xmx2g
@@ -56,7 +58,6 @@
# https://github.com/gradle/gradle/issues/11412
systemProp.org.gradle.internal.publish.checksums.insecure=true
-# This is commented out, and the property is set conditionally in build.gradle, because 1.3.71 doesn't work with it.
-# Once this property is set by default in new versions or 1.3.71 is dropped, either uncomment or remove this line.
+# todo:KLUDGE: This is commented out, and the property is set conditionally in build.gradle, because IDEA doesn't work with it.
#kotlin.mpp.enableGranularSourceSetsMetadata=true
-kotlin.mpp.enableCompatibilityMetadataVariant=true
\ No newline at end of file
+kotlin.mpp.enableCompatibilityMetadataVariant=true
diff --git a/gradle/compile-common.gradle b/gradle/compile-common.gradle
index bee61429..0dc1b5c 100644
--- a/gradle/compile-common.gradle
+++ b/gradle/compile-common.gradle
@@ -3,10 +3,6 @@
*/
kotlin.sourceSets {
- commonMain.dependencies {
- api "org.jetbrains.kotlin:kotlin-stdlib-common:$kotlin_version"
- }
-
commonTest.dependencies {
api "org.jetbrains.kotlin:kotlin-test-common:$kotlin_version"
api "org.jetbrains.kotlin:kotlin-test-annotations-common:$kotlin_version"
diff --git a/gradle/compile-js-multiplatform.gradle b/gradle/compile-js-multiplatform.gradle
index 93d371a..b52cfc5 100644
--- a/gradle/compile-js-multiplatform.gradle
+++ b/gradle/compile-js-multiplatform.gradle
@@ -26,10 +26,6 @@
}
sourceSets {
- jsMain.dependencies {
- api "org.jetbrains.kotlin:kotlin-stdlib-js:$kotlin_version"
- }
-
jsTest.dependencies {
api "org.jetbrains.kotlin:kotlin-test-js:$kotlin_version"
}
diff --git a/gradle/compile-js.gradle b/gradle/compile-js.gradle
index d0697cf..55c81fe 100644
--- a/gradle/compile-js.gradle
+++ b/gradle/compile-js.gradle
@@ -4,25 +4,29 @@
// Platform-specific configuration to compile JS modules
-apply plugin: 'kotlin2js'
+apply plugin: 'org.jetbrains.kotlin.js'
dependencies {
- compile "org.jetbrains.kotlin:kotlin-stdlib-js:$kotlin_version"
- testCompile "org.jetbrains.kotlin:kotlin-test-js:$kotlin_version"
+ testImplementation "org.jetbrains.kotlin:kotlin-test-js:$kotlin_version"
}
-tasks.withType(compileKotlin2Js.getClass()) {
+kotlin {
+ js(LEGACY) {
+ moduleName = project.name - "-js"
+ }
+
+ sourceSets {
+ main.kotlin.srcDirs = ['src']
+ test.kotlin.srcDirs = ['test']
+ main.resources.srcDirs = ['resources']
+ test.resources.srcDirs = ['test-resources']
+ }
+}
+
+tasks.withType(compileKotlinJs.getClass()) {
kotlinOptions {
moduleKind = "umd"
sourceMap = true
metaInfo = true
}
}
-
-compileKotlin2Js {
- kotlinOptions {
- // drop -js suffix from outputFile
- def baseName = project.name - "-js"
- outputFile = new File(outputFile.parent, baseName + ".js")
- }
-}
diff --git a/gradle/compile-jvm-multiplatform.gradle b/gradle/compile-jvm-multiplatform.gradle
index b226c97..e72d305 100644
--- a/gradle/compile-jvm-multiplatform.gradle
+++ b/gradle/compile-jvm-multiplatform.gradle
@@ -5,19 +5,11 @@
sourceCompatibility = 1.6
targetCompatibility = 1.6
-repositories {
- maven { url "https://dl.bintray.com/devexperts/Maven/" }
-}
-
kotlin {
targets {
fromPreset(presets.jvm, 'jvm')
}
sourceSets {
- jvmMain.dependencies {
- api 'org.jetbrains.kotlin:kotlin-stdlib'
- }
-
jvmTest.dependencies {
api "org.jetbrains.kotlin:kotlin-test:$kotlin_version"
// Workaround to make addSuppressed work in tests
diff --git a/gradle/compile-jvm.gradle b/gradle/compile-jvm.gradle
index a811659..caa5c45 100644
--- a/gradle/compile-jvm.gradle
+++ b/gradle/compile-jvm.gradle
@@ -4,13 +4,12 @@
// Platform-specific configuration to compile JVM modules
-apply plugin: 'kotlin'
+apply plugin: 'org.jetbrains.kotlin.jvm'
sourceCompatibility = 1.6
targetCompatibility = 1.6
dependencies {
- compile "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
testCompile "org.jetbrains.kotlin:kotlin-test:$kotlin_version"
// Workaround to make addSuppressed work in tests
testCompile "org.jetbrains.kotlin:kotlin-reflect:$kotlin_version"
@@ -19,10 +18,6 @@
testCompile "junit:junit:$junit_version"
}
-repositories {
- maven { url "https://dl.bintray.com/devexperts/Maven/" }
-}
-
compileKotlin {
kotlinOptions {
freeCompilerArgs += ['-Xexplicit-api=strict']
diff --git a/gradle/compile-native-multiplatform.gradle b/gradle/compile-native-multiplatform.gradle
index 378e4f5..4487446 100644
--- a/gradle/compile-native-multiplatform.gradle
+++ b/gradle/compile-native-multiplatform.gradle
@@ -13,36 +13,24 @@
}
targets {
- if (project.ext.ideaActive) {
- fromPreset(project.ext.ideaPreset, 'native')
- } else {
- addTarget(presets.linuxX64)
- addTarget(presets.iosArm64)
- addTarget(presets.iosArm32)
- addTarget(presets.iosX64)
- addTarget(presets.macosX64)
- addTarget(presets.mingwX64)
- addTarget(presets.tvosArm64)
- addTarget(presets.tvosX64)
- addTarget(presets.watchosArm32)
- addTarget(presets.watchosArm64)
- addTarget(presets.watchosX86)
- }
+ addTarget(presets.linuxX64)
+ addTarget(presets.iosArm64)
+ addTarget(presets.iosArm32)
+ addTarget(presets.iosX64)
+ addTarget(presets.macosX64)
+ addTarget(presets.mingwX64)
+ addTarget(presets.tvosArm64)
+ addTarget(presets.tvosX64)
+ addTarget(presets.watchosArm32)
+ addTarget(presets.watchosArm64)
+ addTarget(presets.watchosX86)
}
sourceSets {
nativeMain { dependsOn commonMain }
- // Empty source set is required in order to have native tests task
- nativeTest {}
+ nativeTest { dependsOn commonTest }
- if (!project.ext.ideaActive) {
- configure(nativeMainSets) {
- dependsOn nativeMain
- }
-
- configure(nativeTestSets) {
- dependsOn nativeTest
- }
- }
+ configure(nativeMainSets) { dependsOn nativeMain }
+ configure(nativeTestSets) { dependsOn nativeTest }
}
}
diff --git a/gradle/targets.gradle b/gradle/targets.gradle
deleted file mode 100644
index 08f3d98..0000000
--- a/gradle/targets.gradle
+++ /dev/null
@@ -1,28 +0,0 @@
-/*
- * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
- */
-
-/*
- * This is a hack to avoid creating unsupported native source sets when importing project into IDEA
- */
-project.ext.ideaActive = System.getProperty('idea.active') == 'true'
-
-kotlin {
- targets {
- def manager = project.ext.hostManager
- def linuxEnabled = manager.isEnabled(presets.linuxX64.konanTarget)
- def macosEnabled = manager.isEnabled(presets.macosX64.konanTarget)
- def winEnabled = manager.isEnabled(presets.mingwX64.konanTarget)
-
- project.ext.isLinuxHost = linuxEnabled
- project.ext.isMacosHost = macosEnabled
- project.ext.isWinHost = winEnabled
-
- if (project.ext.ideaActive) {
- def ideaPreset = presets.linuxX64
- if (macosEnabled) ideaPreset = presets.macosX64
- if (winEnabled) ideaPreset = presets.mingwX64
- project.ext.ideaPreset = ideaPreset
- }
- }
-}
diff --git a/gradle/test-mocha-js.gradle b/gradle/test-mocha-js.gradle
index 6676dc9..7de79b9 100644
--- a/gradle/test-mocha-js.gradle
+++ b/gradle/test-mocha-js.gradle
@@ -86,8 +86,8 @@
task installDependenciesMochaJsdom(type: NpmTask, dependsOn: [npmInstall]) {
args = ['install',
"mocha@$mocha_version",
- 'jsdom@15.2.1',
- 'jsdom-global@3.0.2',
+ "jsdom@$jsdom_version",
+ "jsdom-global@$jsdom_global_version",
"source-map-support@$source_map_support_version",
'--no-save']
if (project.hasProperty("teamcity")) args += ["mocha-teamcity-reporter@$mocha_teamcity_reporter_version"]
diff --git a/integration/kotlinx-coroutines-guava/build.gradle b/integration/kotlinx-coroutines-guava/build.gradle
deleted file mode 100644
index 16bdea5..0000000
--- a/integration/kotlinx-coroutines-guava/build.gradle
+++ /dev/null
@@ -1,16 +0,0 @@
-/*
- * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
- */
-
-ext.guava_version = '28.0-jre'
-
-dependencies {
- compile "com.google.guava:guava:$guava_version"
-}
-
-tasks.withType(dokka.getClass()) {
- externalDocumentationLink {
- url = new URL("https://google.github.io/guava/releases/$guava_version/api/docs/")
- packageListUrl = projectDir.toPath().resolve("package.list").toUri().toURL()
- }
-}
diff --git a/integration/kotlinx-coroutines-guava/build.gradle.kts b/integration/kotlinx-coroutines-guava/build.gradle.kts
new file mode 100644
index 0000000..53e91ad
--- /dev/null
+++ b/integration/kotlinx-coroutines-guava/build.gradle.kts
@@ -0,0 +1,13 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+val guavaVersion = "28.0-jre"
+
+dependencies {
+ compile("com.google.guava:guava:$guavaVersion")
+}
+
+externalDocumentationLink(
+ url = "https://google.github.io/guava/releases/$guavaVersion/api/docs/"
+)
diff --git a/integration/kotlinx-coroutines-play-services/build.gradle b/integration/kotlinx-coroutines-play-services/build.gradle
index eb55486..29ce3d6 100644
--- a/integration/kotlinx-coroutines-play-services/build.gradle
+++ b/integration/kotlinx-coroutines-play-services/build.gradle
@@ -2,12 +2,6 @@
* Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
*/
-import org.gradle.api.artifacts.transform.*
-
-import java.nio.file.Files
-import java.util.zip.ZipEntry
-import java.util.zip.ZipFile
-
ext.tasks_version = '16.0.1'
def artifactType = Attribute.of("artifactType", String)
@@ -49,31 +43,3 @@
packageListUrl = projectDir.toPath().resolve("package.list").toUri().toURL()
}
}
-
-abstract class UnpackAar implements TransformAction<TransformParameters.None> {
- @InputArtifact
- abstract Provider<FileSystemLocation> getInputArtifact()
-
- @Override
- void transform(TransformOutputs outputs) {
- ZipFile zip = new ZipFile(inputArtifact.get().asFile)
- try {
- for (entry in zip.entries()) {
- if (!entry.isDirectory() && entry.name.endsWith(".jar")) {
- unzipEntryTo(zip, entry, outputs.file(entry.name))
- }
- }
- } finally {
- zip.close()
- }
- }
-
- private static void unzipEntryTo(ZipFile zip, ZipEntry entry, File output) {
- InputStream stream = zip.getInputStream(entry)
- try {
- Files.copy(stream, output.toPath())
- } finally {
- stream.close()
- }
- }
-}
diff --git a/integration/kotlinx-coroutines-slf4j/build.gradle b/integration/kotlinx-coroutines-slf4j/build.gradle
deleted file mode 100644
index 05accb7..0000000
--- a/integration/kotlinx-coroutines-slf4j/build.gradle
+++ /dev/null
@@ -1,17 +0,0 @@
-/*
- * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
- */
-
-dependencies {
- compile 'org.slf4j:slf4j-api:1.7.25'
- testCompile 'io.github.microutils:kotlin-logging:1.5.4'
- testRuntime 'ch.qos.logback:logback-classic:1.2.3'
- testRuntime 'ch.qos.logback:logback-core:1.2.3'
-}
-
-tasks.withType(dokka.getClass()) {
- externalDocumentationLink {
- packageListUrl = projectDir.toPath().resolve("package.list").toUri().toURL()
- url = new URL("https://www.slf4j.org/apidocs/")
- }
-}
diff --git a/integration/kotlinx-coroutines-slf4j/build.gradle.kts b/integration/kotlinx-coroutines-slf4j/build.gradle.kts
new file mode 100644
index 0000000..c7d0d82
--- /dev/null
+++ b/integration/kotlinx-coroutines-slf4j/build.gradle.kts
@@ -0,0 +1,14 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+dependencies {
+ compile("org.slf4j:slf4j-api:1.7.25")
+ testCompile("io.github.microutils:kotlin-logging:1.5.4")
+ testRuntime("ch.qos.logback:logback-classic:1.2.3")
+ testRuntime("ch.qos.logback:logback-core:1.2.3")
+}
+
+externalDocumentationLink(
+ url = "https://www.slf4j.org/apidocs/"
+)
diff --git a/js/example-frontend-js/README.md b/js/example-frontend-js/README.md
index 4e534e4..ad61372 100644
--- a/js/example-frontend-js/README.md
+++ b/js/example-frontend-js/README.md
@@ -3,7 +3,7 @@
Build application with
```
-gradlew :example-frontend-js:bundle
+gradlew :example-frontend-js:build
```
The resulting application can be found in `build/dist` subdirectory.
@@ -11,7 +11,7 @@
You can start application with webpack-dev-server using:
```
-gradlew :example-frontend-js:start
+gradlew :example-frontend-js:run
```
Built and deployed application is available at the library documentation site
diff --git a/js/example-frontend-js/build.gradle b/js/example-frontend-js/build.gradle
index 735a70d..7abde63 100644
--- a/js/example-frontend-js/build.gradle
+++ b/js/example-frontend-js/build.gradle
@@ -2,53 +2,32 @@
* Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
*/
-apply plugin: 'kotlin-dce-js'
-apply from: rootProject.file('gradle/node-js.gradle')
-
-// Workaround resolving new Gradle metadata with kotlin2js
-// TODO: Remove once KT-37188 is fixed
-try {
- def jsCompilerType = Class.forName("org.jetbrains.kotlin.gradle.targets.js.KotlinJsCompilerAttribute")
- def jsCompilerAttr = Attribute.of("org.jetbrains.kotlin.js.compiler", jsCompilerType)
- project.dependencies.attributesSchema.attribute(jsCompilerAttr)
- configurations {
- matching {
- it.name.endsWith("Classpath")
- }.forEach {
- it.attributes.attribute(jsCompilerAttr, jsCompilerType.legacy)
+project.kotlin {
+ js(LEGACY) {
+ binaries.executable()
+ browser {
+ distribution {
+ directory = new File(directory.parentFile, "dist")
+ }
+ webpackTask {
+ cssSupport.enabled = true
+ }
+ runTask {
+ cssSupport.enabled = true
+ }
+ testTask {
+ useKarma {
+ useChromeHeadless()
+ webpackConfig.cssSupport.enabled = true
+ }
+ }
}
}
-} catch (java.lang.ClassNotFoundException e) {
- // org.jetbrains.kotlin.gradle.targets.js.JsCompilerType is missing in 1.3.x
- // But 1.3.x doesn't generate Gradle metadata, so this workaround is not needed
-}
-dependencies {
- compile "org.jetbrains.kotlinx:kotlinx-html-js:$html_version"
-}
-
-compileKotlin2Js {
- kotlinOptions {
- main = "call"
- }
-}
-
-task bundle(type: NpmTask, dependsOn: [npmInstall, runDceKotlinJs]) {
- inputs.files(fileTree("$buildDir/kotlin-js-min/main"))
- inputs.files(fileTree(file("src/main/web")))
- inputs.file("npm/webpack.config.js")
- outputs.dir("$buildDir/dist")
- args = ["run", "bundle"]
-}
-
-task start(type: NpmTask, dependsOn: bundle) {
- args = ["run", "start"]
-}
-
-// we have not tests but kotlin-dce-js still tries to work with them and crashed.
-// todo: Remove when KT-22028 is fixed
-afterEvaluate {
- if (tasks.findByName('unpackDependenciesTestKotlinJs')) {
- tasks.unpackDependenciesTestKotlinJs.enabled = false
+ sourceSets {
+ main.dependencies {
+ implementation "org.jetbrains.kotlinx:kotlinx-html-js:$html_version"
+ implementation(npm("html-webpack-plugin", "3.2.0"))
+ }
}
}
diff --git a/js/example-frontend-js/npm/package.json b/js/example-frontend-js/npm/package.json
deleted file mode 100644
index 7668cef..0000000
--- a/js/example-frontend-js/npm/package.json
+++ /dev/null
@@ -1,22 +0,0 @@
-{
- "name": "example-frontend-js",
- "version": "$version",
- "license": "Apache-2.0",
- "repository": {
- "type": "git",
- "url": "https://github.com/Kotlin/kotlinx.coroutines.git"
- },
- "devDependencies": {
- "webpack": "4.29.1",
- "webpack-cli": "3.2.3",
- "webpack-dev-server": "3.1.14",
- "html-webpack-plugin": "3.2.0",
- "uglifyjs-webpack-plugin": "2.1.1",
- "style-loader": "0.23.1",
- "css-loader": "2.1.0"
- },
- "scripts": {
- "bundle": "webpack",
- "start": "webpack-dev-server --open --no-inline"
- }
-}
diff --git a/js/example-frontend-js/npm/webpack.config.js b/js/example-frontend-js/npm/webpack.config.js
deleted file mode 100644
index a208d04..0000000
--- a/js/example-frontend-js/npm/webpack.config.js
+++ /dev/null
@@ -1,53 +0,0 @@
-/*
- * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
- */
-
-// This script is copied to "build" directory and run from there
-
-const webpack = require("webpack");
-const HtmlWebpackPlugin = require('html-webpack-plugin');
-const UglifyJSPlugin = require('uglifyjs-webpack-plugin');
-const path = require("path");
-
-const dist = path.resolve(__dirname, "dist");
-
-module.exports = {
- mode: "production",
- entry: {
- main: "main"
- },
- output: {
- filename: "[name].bundle.js",
- path: dist,
- publicPath: ""
- },
- devServer: {
- contentBase: dist
- },
- module: {
- rules: [
- {
- test: /\.css$/,
- use: [
- 'style-loader',
- 'css-loader'
- ]
- }
- ]
- },
- resolve: {
- modules: [
- path.resolve(__dirname, "kotlin-js-min/main"),
- path.resolve(__dirname, "../src/main/web/")
- ]
- },
- devtool: 'source-map',
- plugins: [
- new HtmlWebpackPlugin({
- title: 'Kotlin Coroutines JS Example'
- }),
- new UglifyJSPlugin({
- sourceMap: true
- })
- ]
-};
diff --git a/js/example-frontend-js/src/ExampleMain.kt b/js/example-frontend-js/src/ExampleMain.kt
index 25a73c6..da6e419 100644
--- a/js/example-frontend-js/src/ExampleMain.kt
+++ b/js/example-frontend-js/src/ExampleMain.kt
@@ -13,7 +13,10 @@
import kotlin.math.*
import kotlin.random.Random
+external fun require(resource: String)
+
fun main() {
+ require("style.css")
println("Starting example application...")
document.addEventListener("DOMContentLoaded", {
Application().start()
diff --git a/js/example-frontend-js/src/main/web/main.js b/js/example-frontend-js/src/main/web/main.js
deleted file mode 100644
index d2440ff..0000000
--- a/js/example-frontend-js/src/main/web/main.js
+++ /dev/null
@@ -1,8 +0,0 @@
-/*
- * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
- */
-
-// ------ Main bundle for example application ------
-
-require("example-frontend");
-require("style.css");
diff --git a/js/example-frontend-js/webpack.config.d/custom-config.js b/js/example-frontend-js/webpack.config.d/custom-config.js
new file mode 100644
index 0000000..21939be
--- /dev/null
+++ b/js/example-frontend-js/webpack.config.d/custom-config.js
@@ -0,0 +1,18 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+;(function (config) {
+ const HtmlWebpackPlugin = require('html-webpack-plugin');
+
+ config.output.filename = "[name].bundle.js"
+
+ config.plugins.push(
+ new HtmlWebpackPlugin({
+ title: 'Kotlin Coroutines JS Example'
+ })
+ )
+
+ // path from <root-build>/js/packages/example-frontend-js to src/main/web
+ config.resolve.modules.push("../../../../js/example-frontend-js/src/main/web");
+})(config);
diff --git a/knit.properties b/knit.properties
new file mode 100644
index 0000000..bc177ce
--- /dev/null
+++ b/knit.properties
@@ -0,0 +1,16 @@
+#
+# Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+#
+
+knit.include=docs/knit.code.include
+test.template=docs/knit.test.template
+
+# Various test validation modes and their corresponding methods from TestUtil
+test.mode.=verifyLines
+test.mode.STARTS_WITH=verifyLinesStartWith
+test.mode.ARBITRARY_TIME=verifyLinesArbitraryTime
+test.mode.FLEXIBLE_TIME=verifyLinesFlexibleTime
+test.mode.FLEXIBLE_THREAD=verifyLinesFlexibleThread
+test.mode.LINES_START_UNORDERED=verifyLinesStartUnordered
+test.mode.LINES_START=verifyLinesStart
+test.mode.EXCEPTION=verifyExceptions
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/api/kotlinx-coroutines-core.api b/kotlinx-coroutines-core/api/kotlinx-coroutines-core.api
index 4609c68..b86076f 100644
--- a/kotlinx-coroutines-core/api/kotlinx-coroutines-core.api
+++ b/kotlinx-coroutines-core/api/kotlinx-coroutines-core.api
@@ -46,6 +46,7 @@
public abstract fun resumeUndispatched (Lkotlinx/coroutines/CoroutineDispatcher;Ljava/lang/Object;)V
public abstract fun resumeUndispatchedWithException (Lkotlinx/coroutines/CoroutineDispatcher;Ljava/lang/Throwable;)V
public abstract fun tryResume (Ljava/lang/Object;Ljava/lang/Object;)Ljava/lang/Object;
+ public abstract fun tryResume (Ljava/lang/Object;Ljava/lang/Object;Lkotlin/jvm/functions/Function1;)Ljava/lang/Object;
public abstract fun tryResumeWithException (Ljava/lang/Throwable;)Ljava/lang/Object;
}
@@ -56,6 +57,8 @@
public class kotlinx/coroutines/CancellableContinuationImpl : kotlin/coroutines/jvm/internal/CoroutineStackFrame, kotlinx/coroutines/CancellableContinuation {
public fun <init> (Lkotlin/coroutines/Continuation;I)V
+ public final fun callCancelHandler (Lkotlinx/coroutines/CancelHandler;Ljava/lang/Throwable;)V
+ public final fun callOnCancellation (Lkotlin/jvm/functions/Function1;Ljava/lang/Throwable;)V
public fun cancel (Ljava/lang/Throwable;)Z
public fun completeResume (Ljava/lang/Object;)V
public fun getCallerFrame ()Lkotlin/coroutines/jvm/internal/CoroutineStackFrame;
@@ -75,14 +78,12 @@
public fun resumeWith (Ljava/lang/Object;)V
public fun toString ()Ljava/lang/String;
public fun tryResume (Ljava/lang/Object;Ljava/lang/Object;)Ljava/lang/Object;
+ public fun tryResume (Ljava/lang/Object;Ljava/lang/Object;Lkotlin/jvm/functions/Function1;)Ljava/lang/Object;
public fun tryResumeWithException (Ljava/lang/Throwable;)Ljava/lang/Object;
}
public final class kotlinx/coroutines/CancellableContinuationKt {
public static final fun disposeOnCancellation (Lkotlinx/coroutines/CancellableContinuation;Lkotlinx/coroutines/DisposableHandle;)V
- public static final fun suspendAtomicCancellableCoroutine (Lkotlin/jvm/functions/Function1;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
- public static final fun suspendAtomicCancellableCoroutine (ZLkotlin/jvm/functions/Function1;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
- public static synthetic fun suspendAtomicCancellableCoroutine$default (ZLkotlin/jvm/functions/Function1;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
public static final fun suspendCancellableCoroutine (Lkotlin/jvm/functions/Function1;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
}
@@ -257,24 +258,21 @@
public abstract interface class kotlinx/coroutines/Delay {
public abstract fun delay (JLkotlin/coroutines/Continuation;)Ljava/lang/Object;
- public abstract fun invokeOnTimeout (JLjava/lang/Runnable;)Lkotlinx/coroutines/DisposableHandle;
+ public abstract fun invokeOnTimeout (JLjava/lang/Runnable;Lkotlin/coroutines/CoroutineContext;)Lkotlinx/coroutines/DisposableHandle;
public abstract fun scheduleResumeAfterDelay (JLkotlinx/coroutines/CancellableContinuation;)V
}
public final class kotlinx/coroutines/Delay$DefaultImpls {
public static fun delay (Lkotlinx/coroutines/Delay;JLkotlin/coroutines/Continuation;)Ljava/lang/Object;
- public static fun invokeOnTimeout (Lkotlinx/coroutines/Delay;JLjava/lang/Runnable;)Lkotlinx/coroutines/DisposableHandle;
+ public static fun invokeOnTimeout (Lkotlinx/coroutines/Delay;JLjava/lang/Runnable;Lkotlin/coroutines/CoroutineContext;)Lkotlinx/coroutines/DisposableHandle;
}
public final class kotlinx/coroutines/DelayKt {
+ public static final fun awaitCancellation (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public static final fun delay (JLkotlin/coroutines/Continuation;)Ljava/lang/Object;
public static final fun delay-p9JZ4hM (DLkotlin/coroutines/Continuation;)Ljava/lang/Object;
}
-public final class kotlinx/coroutines/DispatchedContinuationKt {
- public static final fun resumeCancellableWith (Lkotlin/coroutines/Continuation;Ljava/lang/Object;)V
-}
-
public final class kotlinx/coroutines/Dispatchers {
public static final field INSTANCE Lkotlinx/coroutines/Dispatchers;
public static final fun getDefault ()Lkotlinx/coroutines/CoroutineDispatcher;
@@ -396,6 +394,7 @@
public static final fun cancelFutureOnCompletion (Lkotlinx/coroutines/Job;Ljava/util/concurrent/Future;)Lkotlinx/coroutines/DisposableHandle;
public static final fun ensureActive (Lkotlin/coroutines/CoroutineContext;)V
public static final fun ensureActive (Lkotlinx/coroutines/Job;)V
+ public static final fun getJob (Lkotlin/coroutines/CoroutineContext;)Lkotlinx/coroutines/Job;
public static final fun isActive (Lkotlin/coroutines/CoroutineContext;)Z
}
@@ -580,6 +579,14 @@
public static synthetic fun broadcast$default (Lkotlinx/coroutines/channels/ReceiveChannel;ILkotlinx/coroutines/CoroutineStart;ILjava/lang/Object;)Lkotlinx/coroutines/channels/BroadcastChannel;
}
+public final class kotlinx/coroutines/channels/BufferOverflow : java/lang/Enum {
+ public static final field DROP_LATEST Lkotlinx/coroutines/channels/BufferOverflow;
+ public static final field DROP_OLDEST Lkotlinx/coroutines/channels/BufferOverflow;
+ public static final field SUSPEND Lkotlinx/coroutines/channels/BufferOverflow;
+ public static fun valueOf (Ljava/lang/String;)Lkotlinx/coroutines/channels/BufferOverflow;
+ public static fun values ()[Lkotlinx/coroutines/channels/BufferOverflow;
+}
+
public abstract interface class kotlinx/coroutines/channels/Channel : kotlinx/coroutines/channels/ReceiveChannel, kotlinx/coroutines/channels/SendChannel {
public static final field BUFFERED I
public static final field CONFLATED I
@@ -612,8 +619,10 @@
}
public final class kotlinx/coroutines/channels/ChannelKt {
- public static final fun Channel (I)Lkotlinx/coroutines/channels/Channel;
+ public static final synthetic fun Channel (I)Lkotlinx/coroutines/channels/Channel;
+ public static final fun Channel (ILkotlinx/coroutines/channels/BufferOverflow;Lkotlin/jvm/functions/Function1;)Lkotlinx/coroutines/channels/Channel;
public static synthetic fun Channel$default (IILjava/lang/Object;)Lkotlinx/coroutines/channels/Channel;
+ public static synthetic fun Channel$default (ILkotlinx/coroutines/channels/BufferOverflow;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lkotlinx/coroutines/channels/Channel;
}
public final class kotlinx/coroutines/channels/ChannelsKt {
@@ -787,7 +796,7 @@
public abstract fun iterator ()Lkotlinx/coroutines/channels/ChannelIterator;
public abstract fun poll ()Ljava/lang/Object;
public abstract fun receive (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
- public abstract fun receiveOrClosed (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+ public abstract fun receiveOrClosed-ZYPwvRU (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public abstract fun receiveOrNull (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
}
@@ -868,7 +877,7 @@
public final fun getState ()Ljava/lang/String;
}
-public abstract class kotlinx/coroutines/flow/AbstractFlow : kotlinx/coroutines/flow/Flow {
+public abstract class kotlinx/coroutines/flow/AbstractFlow : kotlinx/coroutines/flow/CancellableFlow, kotlinx/coroutines/flow/Flow {
public fun <init> ()V
public final fun collect (Lkotlinx/coroutines/flow/FlowCollector;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public abstract fun collectSafely (Lkotlinx/coroutines/flow/FlowCollector;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
@@ -895,10 +904,15 @@
public static final fun asFlow ([I)Lkotlinx/coroutines/flow/Flow;
public static final fun asFlow ([J)Lkotlinx/coroutines/flow/Flow;
public static final fun asFlow ([Ljava/lang/Object;)Lkotlinx/coroutines/flow/Flow;
+ public static final fun asSharedFlow (Lkotlinx/coroutines/flow/MutableSharedFlow;)Lkotlinx/coroutines/flow/SharedFlow;
+ public static final fun asStateFlow (Lkotlinx/coroutines/flow/MutableStateFlow;)Lkotlinx/coroutines/flow/StateFlow;
public static final fun broadcastIn (Lkotlinx/coroutines/flow/Flow;Lkotlinx/coroutines/CoroutineScope;Lkotlinx/coroutines/CoroutineStart;)Lkotlinx/coroutines/channels/BroadcastChannel;
public static synthetic fun broadcastIn$default (Lkotlinx/coroutines/flow/Flow;Lkotlinx/coroutines/CoroutineScope;Lkotlinx/coroutines/CoroutineStart;ILjava/lang/Object;)Lkotlinx/coroutines/channels/BroadcastChannel;
- public static final fun buffer (Lkotlinx/coroutines/flow/Flow;I)Lkotlinx/coroutines/flow/Flow;
+ public static final synthetic fun buffer (Lkotlinx/coroutines/flow/Flow;I)Lkotlinx/coroutines/flow/Flow;
+ public static final fun buffer (Lkotlinx/coroutines/flow/Flow;ILkotlinx/coroutines/channels/BufferOverflow;)Lkotlinx/coroutines/flow/Flow;
public static synthetic fun buffer$default (Lkotlinx/coroutines/flow/Flow;IILjava/lang/Object;)Lkotlinx/coroutines/flow/Flow;
+ public static synthetic fun buffer$default (Lkotlinx/coroutines/flow/Flow;ILkotlinx/coroutines/channels/BufferOverflow;ILjava/lang/Object;)Lkotlinx/coroutines/flow/Flow;
+ public static final fun cache (Lkotlinx/coroutines/flow/Flow;)Lkotlinx/coroutines/flow/Flow;
public static final fun callbackFlow (Lkotlin/jvm/functions/Function2;)Lkotlinx/coroutines/flow/Flow;
public static final fun cancellable (Lkotlinx/coroutines/flow/Flow;)Lkotlinx/coroutines/flow/Flow;
public static final fun catch (Lkotlinx/coroutines/flow/Flow;Lkotlin/jvm/functions/Function3;)Lkotlinx/coroutines/flow/Flow;
@@ -928,7 +942,9 @@
public static final fun count (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public static final fun count (Lkotlinx/coroutines/flow/Flow;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public static final fun debounce (Lkotlinx/coroutines/flow/Flow;J)Lkotlinx/coroutines/flow/Flow;
+ public static final fun debounce (Lkotlinx/coroutines/flow/Flow;Lkotlin/jvm/functions/Function1;)Lkotlinx/coroutines/flow/Flow;
public static final fun debounce-8GFy2Ro (Lkotlinx/coroutines/flow/Flow;D)Lkotlinx/coroutines/flow/Flow;
+ public static final fun debounceDuration (Lkotlinx/coroutines/flow/Flow;Lkotlin/jvm/functions/Function1;)Lkotlinx/coroutines/flow/Flow;
public static final fun delayEach (Lkotlinx/coroutines/flow/Flow;J)Lkotlinx/coroutines/flow/Flow;
public static final fun delayFlow (Lkotlinx/coroutines/flow/Flow;J)Lkotlinx/coroutines/flow/Flow;
public static final fun distinctUntilChanged (Lkotlinx/coroutines/flow/Flow;)Lkotlinx/coroutines/flow/Flow;
@@ -976,7 +992,6 @@
public static final fun merge (Lkotlinx/coroutines/flow/Flow;)Lkotlinx/coroutines/flow/Flow;
public static final fun merge ([Lkotlinx/coroutines/flow/Flow;)Lkotlinx/coroutines/flow/Flow;
public static final fun observeOn (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/CoroutineContext;)Lkotlinx/coroutines/flow/Flow;
- public static final synthetic fun onCompletion (Lkotlinx/coroutines/flow/Flow;Lkotlin/jvm/functions/Function2;)Lkotlinx/coroutines/flow/Flow;
public static final fun onCompletion (Lkotlinx/coroutines/flow/Flow;Lkotlin/jvm/functions/Function3;)Lkotlinx/coroutines/flow/Flow;
public static final fun onEach (Lkotlinx/coroutines/flow/Flow;Lkotlin/jvm/functions/Function2;)Lkotlinx/coroutines/flow/Flow;
public static final fun onEmpty (Lkotlinx/coroutines/flow/Flow;Lkotlin/jvm/functions/Function2;)Lkotlinx/coroutines/flow/Flow;
@@ -988,10 +1003,15 @@
public static final fun onErrorReturn (Lkotlinx/coroutines/flow/Flow;Ljava/lang/Object;Lkotlin/jvm/functions/Function1;)Lkotlinx/coroutines/flow/Flow;
public static synthetic fun onErrorReturn$default (Lkotlinx/coroutines/flow/Flow;Ljava/lang/Object;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lkotlinx/coroutines/flow/Flow;
public static final fun onStart (Lkotlinx/coroutines/flow/Flow;Lkotlin/jvm/functions/Function2;)Lkotlinx/coroutines/flow/Flow;
+ public static final fun onSubscription (Lkotlinx/coroutines/flow/SharedFlow;Lkotlin/jvm/functions/Function2;)Lkotlinx/coroutines/flow/SharedFlow;
public static final fun produceIn (Lkotlinx/coroutines/flow/Flow;Lkotlinx/coroutines/CoroutineScope;)Lkotlinx/coroutines/channels/ReceiveChannel;
+ public static final fun publish (Lkotlinx/coroutines/flow/Flow;)Lkotlinx/coroutines/flow/Flow;
+ public static final fun publish (Lkotlinx/coroutines/flow/Flow;I)Lkotlinx/coroutines/flow/Flow;
public static final fun publishOn (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/CoroutineContext;)Lkotlinx/coroutines/flow/Flow;
public static final fun receiveAsFlow (Lkotlinx/coroutines/channels/ReceiveChannel;)Lkotlinx/coroutines/flow/Flow;
public static final fun reduce (Lkotlinx/coroutines/flow/Flow;Lkotlin/jvm/functions/Function3;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+ public static final fun replay (Lkotlinx/coroutines/flow/Flow;)Lkotlinx/coroutines/flow/Flow;
+ public static final fun replay (Lkotlinx/coroutines/flow/Flow;I)Lkotlinx/coroutines/flow/Flow;
public static final synthetic fun retry (Lkotlinx/coroutines/flow/Flow;ILkotlin/jvm/functions/Function1;)Lkotlinx/coroutines/flow/Flow;
public static final fun retry (Lkotlinx/coroutines/flow/Flow;JLkotlin/jvm/functions/Function2;)Lkotlinx/coroutines/flow/Flow;
public static synthetic fun retry$default (Lkotlinx/coroutines/flow/Flow;ILkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lkotlinx/coroutines/flow/Flow;
@@ -1003,11 +1023,15 @@
public static final fun scan (Lkotlinx/coroutines/flow/Flow;Ljava/lang/Object;Lkotlin/jvm/functions/Function3;)Lkotlinx/coroutines/flow/Flow;
public static final fun scanFold (Lkotlinx/coroutines/flow/Flow;Ljava/lang/Object;Lkotlin/jvm/functions/Function3;)Lkotlinx/coroutines/flow/Flow;
public static final fun scanReduce (Lkotlinx/coroutines/flow/Flow;Lkotlin/jvm/functions/Function3;)Lkotlinx/coroutines/flow/Flow;
+ public static final fun shareIn (Lkotlinx/coroutines/flow/Flow;Lkotlinx/coroutines/CoroutineScope;Lkotlinx/coroutines/flow/SharingStarted;I)Lkotlinx/coroutines/flow/SharedFlow;
+ public static synthetic fun shareIn$default (Lkotlinx/coroutines/flow/Flow;Lkotlinx/coroutines/CoroutineScope;Lkotlinx/coroutines/flow/SharingStarted;IILjava/lang/Object;)Lkotlinx/coroutines/flow/SharedFlow;
public static final fun single (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public static final fun singleOrNull (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public static final fun skip (Lkotlinx/coroutines/flow/Flow;I)Lkotlinx/coroutines/flow/Flow;
public static final fun startWith (Lkotlinx/coroutines/flow/Flow;Ljava/lang/Object;)Lkotlinx/coroutines/flow/Flow;
public static final fun startWith (Lkotlinx/coroutines/flow/Flow;Lkotlinx/coroutines/flow/Flow;)Lkotlinx/coroutines/flow/Flow;
+ public static final fun stateIn (Lkotlinx/coroutines/flow/Flow;Lkotlinx/coroutines/CoroutineScope;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+ public static final fun stateIn (Lkotlinx/coroutines/flow/Flow;Lkotlinx/coroutines/CoroutineScope;Lkotlinx/coroutines/flow/SharingStarted;Ljava/lang/Object;)Lkotlinx/coroutines/flow/StateFlow;
public static final fun subscribe (Lkotlinx/coroutines/flow/Flow;)V
public static final fun subscribe (Lkotlinx/coroutines/flow/Flow;Lkotlin/jvm/functions/Function2;)V
public static final fun subscribe (Lkotlinx/coroutines/flow/Flow;Lkotlin/jvm/functions/Function2;Lkotlin/jvm/functions/Function2;)V
@@ -1029,17 +1053,63 @@
}
public final class kotlinx/coroutines/flow/LintKt {
+ public static final fun cancel (Lkotlinx/coroutines/flow/FlowCollector;Ljava/util/concurrent/CancellationException;)V
+ public static synthetic fun cancel$default (Lkotlinx/coroutines/flow/FlowCollector;Ljava/util/concurrent/CancellationException;ILjava/lang/Object;)V
+ public static final fun cancellable (Lkotlinx/coroutines/flow/SharedFlow;)Lkotlinx/coroutines/flow/Flow;
public static final fun conflate (Lkotlinx/coroutines/flow/StateFlow;)Lkotlinx/coroutines/flow/Flow;
public static final fun distinctUntilChanged (Lkotlinx/coroutines/flow/StateFlow;)Lkotlinx/coroutines/flow/Flow;
- public static final fun flowOn (Lkotlinx/coroutines/flow/StateFlow;Lkotlin/coroutines/CoroutineContext;)Lkotlinx/coroutines/flow/Flow;
+ public static final fun flowOn (Lkotlinx/coroutines/flow/SharedFlow;Lkotlin/coroutines/CoroutineContext;)Lkotlinx/coroutines/flow/Flow;
+ public static final fun getCoroutineContext (Lkotlinx/coroutines/flow/FlowCollector;)Lkotlin/coroutines/CoroutineContext;
+ public static final fun isActive (Lkotlinx/coroutines/flow/FlowCollector;)Z
}
-public abstract interface class kotlinx/coroutines/flow/MutableStateFlow : kotlinx/coroutines/flow/StateFlow {
+public abstract interface class kotlinx/coroutines/flow/MutableSharedFlow : kotlinx/coroutines/flow/FlowCollector, kotlinx/coroutines/flow/SharedFlow {
+ public abstract fun getSubscriptionCount ()Lkotlinx/coroutines/flow/StateFlow;
+ public abstract fun resetReplayCache ()V
+ public abstract fun tryEmit (Ljava/lang/Object;)Z
+}
+
+public abstract interface class kotlinx/coroutines/flow/MutableStateFlow : kotlinx/coroutines/flow/MutableSharedFlow, kotlinx/coroutines/flow/StateFlow {
+ public abstract fun compareAndSet (Ljava/lang/Object;Ljava/lang/Object;)Z
public abstract fun getValue ()Ljava/lang/Object;
public abstract fun setValue (Ljava/lang/Object;)V
}
-public abstract interface class kotlinx/coroutines/flow/StateFlow : kotlinx/coroutines/flow/Flow {
+public abstract interface class kotlinx/coroutines/flow/SharedFlow : kotlinx/coroutines/flow/Flow {
+ public abstract fun getReplayCache ()Ljava/util/List;
+}
+
+public final class kotlinx/coroutines/flow/SharedFlowKt {
+ public static final fun MutableSharedFlow (IILkotlinx/coroutines/channels/BufferOverflow;)Lkotlinx/coroutines/flow/MutableSharedFlow;
+ public static synthetic fun MutableSharedFlow$default (IILkotlinx/coroutines/channels/BufferOverflow;ILjava/lang/Object;)Lkotlinx/coroutines/flow/MutableSharedFlow;
+}
+
+public final class kotlinx/coroutines/flow/SharingCommand : java/lang/Enum {
+ public static final field START Lkotlinx/coroutines/flow/SharingCommand;
+ public static final field STOP Lkotlinx/coroutines/flow/SharingCommand;
+ public static final field STOP_AND_RESET_REPLAY_CACHE Lkotlinx/coroutines/flow/SharingCommand;
+ public static fun valueOf (Ljava/lang/String;)Lkotlinx/coroutines/flow/SharingCommand;
+ public static fun values ()[Lkotlinx/coroutines/flow/SharingCommand;
+}
+
+public abstract interface class kotlinx/coroutines/flow/SharingStarted {
+ public static final field Companion Lkotlinx/coroutines/flow/SharingStarted$Companion;
+ public abstract fun command (Lkotlinx/coroutines/flow/StateFlow;)Lkotlinx/coroutines/flow/Flow;
+}
+
+public final class kotlinx/coroutines/flow/SharingStarted$Companion {
+ public final fun WhileSubscribed (JJ)Lkotlinx/coroutines/flow/SharingStarted;
+ public static synthetic fun WhileSubscribed$default (Lkotlinx/coroutines/flow/SharingStarted$Companion;JJILjava/lang/Object;)Lkotlinx/coroutines/flow/SharingStarted;
+ public final fun getEagerly ()Lkotlinx/coroutines/flow/SharingStarted;
+ public final fun getLazily ()Lkotlinx/coroutines/flow/SharingStarted;
+}
+
+public final class kotlinx/coroutines/flow/SharingStartedKt {
+ public static final fun WhileSubscribed-9tZugJw (Lkotlinx/coroutines/flow/SharingStarted$Companion;DD)Lkotlinx/coroutines/flow/SharingStarted;
+ public static synthetic fun WhileSubscribed-9tZugJw$default (Lkotlinx/coroutines/flow/SharingStarted$Companion;DDILjava/lang/Object;)Lkotlinx/coroutines/flow/SharingStarted;
+}
+
+public abstract interface class kotlinx/coroutines/flow/StateFlow : kotlinx/coroutines/flow/SharedFlow {
public abstract fun getValue ()Ljava/lang/Object;
}
@@ -1050,13 +1120,15 @@
public abstract class kotlinx/coroutines/flow/internal/ChannelFlow : kotlinx/coroutines/flow/internal/FusibleFlow {
public final field capacity I
public final field context Lkotlin/coroutines/CoroutineContext;
- public fun <init> (Lkotlin/coroutines/CoroutineContext;I)V
- public fun additionalToStringProps ()Ljava/lang/String;
+ public final field onBufferOverflow Lkotlinx/coroutines/channels/BufferOverflow;
+ public fun <init> (Lkotlin/coroutines/CoroutineContext;ILkotlinx/coroutines/channels/BufferOverflow;)V
+ protected fun additionalToStringProps ()Ljava/lang/String;
public fun broadcastImpl (Lkotlinx/coroutines/CoroutineScope;Lkotlinx/coroutines/CoroutineStart;)Lkotlinx/coroutines/channels/BroadcastChannel;
public fun collect (Lkotlinx/coroutines/flow/FlowCollector;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
protected abstract fun collectTo (Lkotlinx/coroutines/channels/ProducerScope;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
- protected abstract fun create (Lkotlin/coroutines/CoroutineContext;I)Lkotlinx/coroutines/flow/internal/ChannelFlow;
- public fun fuse (Lkotlin/coroutines/CoroutineContext;I)Lkotlinx/coroutines/flow/internal/FusibleFlow;
+ protected abstract fun create (Lkotlin/coroutines/CoroutineContext;ILkotlinx/coroutines/channels/BufferOverflow;)Lkotlinx/coroutines/flow/internal/ChannelFlow;
+ public fun dropChannelOperators ()Lkotlinx/coroutines/flow/Flow;
+ public fun fuse (Lkotlin/coroutines/CoroutineContext;ILkotlinx/coroutines/channels/BufferOverflow;)Lkotlinx/coroutines/flow/Flow;
public fun produceImpl (Lkotlinx/coroutines/CoroutineScope;)Lkotlinx/coroutines/channels/ReceiveChannel;
public fun toString ()Ljava/lang/String;
}
@@ -1070,11 +1142,11 @@
}
public abstract interface class kotlinx/coroutines/flow/internal/FusibleFlow : kotlinx/coroutines/flow/Flow {
- public abstract fun fuse (Lkotlin/coroutines/CoroutineContext;I)Lkotlinx/coroutines/flow/internal/FusibleFlow;
+ public abstract fun fuse (Lkotlin/coroutines/CoroutineContext;ILkotlinx/coroutines/channels/BufferOverflow;)Lkotlinx/coroutines/flow/Flow;
}
public final class kotlinx/coroutines/flow/internal/FusibleFlow$DefaultImpls {
- public static synthetic fun fuse$default (Lkotlinx/coroutines/flow/internal/FusibleFlow;Lkotlin/coroutines/CoroutineContext;IILjava/lang/Object;)Lkotlinx/coroutines/flow/internal/FusibleFlow;
+ public static synthetic fun fuse$default (Lkotlinx/coroutines/flow/internal/FusibleFlow;Lkotlin/coroutines/CoroutineContext;ILkotlinx/coroutines/channels/BufferOverflow;ILjava/lang/Object;)Lkotlinx/coroutines/flow/Flow;
}
public final class kotlinx/coroutines/flow/internal/SafeCollector_commonKt {
diff --git a/kotlinx-coroutines-core/build.gradle b/kotlinx-coroutines-core/build.gradle
index be7622a..f98f6a5 100644
--- a/kotlinx-coroutines-core/build.gradle
+++ b/kotlinx-coroutines-core/build.gradle
@@ -2,14 +2,61 @@
* Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
*/
-apply plugin: 'kotlin-multiplatform'
-apply from: rootProject.file("gradle/targets.gradle")
+apply plugin: 'org.jetbrains.kotlin.multiplatform'
apply from: rootProject.file("gradle/compile-jvm-multiplatform.gradle")
apply from: rootProject.file("gradle/compile-common.gradle")
apply from: rootProject.file("gradle/compile-js-multiplatform.gradle")
apply from: rootProject.file("gradle/compile-native-multiplatform.gradle")
apply from: rootProject.file('gradle/publish-npm-js.gradle')
+/* ==========================================================================
+ Configure source sets structure for kotlinx-coroutines-core:
+
+ TARGETS SOURCE SETS
+ ------- ----------------------------------------------
+
+ js -----------------------------------------------------+
+ |
+ V
+ jvm -------------------------------> concurrent ---> common
+ ^
+ ios \ |
+ macos | ---> nativeDarwin ---> native --+
+ tvos | ^
+ watchos / |
+ |
+ linux \ ---> nativeOther -------+
+ mingw /
+
+ ========================================================================== */
+
+project.ext.sourceSetSuffixes = ["Main", "Test"]
+
+void defineSourceSet(newName, dependsOn, includedInPred) {
+ for (suffix in project.ext.sourceSetSuffixes) {
+ def newSS = kotlin.sourceSets.maybeCreate(newName + suffix)
+ for (dep in dependsOn) {
+ newSS.dependsOn(kotlin.sourceSets[dep + suffix])
+ }
+ for (curSS in kotlin.sourceSets) {
+ def curName = curSS.name
+ if (curName.endsWith(suffix)) {
+ def prefix = curName.substring(0, curName.length() - suffix.length())
+ if (includedInPred(prefix)) curSS.dependsOn(newSS)
+ }
+ }
+ }
+}
+
+static boolean isNativeDarwin(String name) { return ["ios", "macos", "tvos", "watchos"].any { name.startsWith(it) } }
+static boolean isNativeOther(String name) { return ["linux", "mingw"].any { name.startsWith(it) } }
+
+defineSourceSet("concurrent", ["common"]) { it in ["jvm", "native"] }
+defineSourceSet("nativeDarwin", ["native"]) { isNativeDarwin(it) }
+defineSourceSet("nativeOther", ["native"]) { isNativeOther(it) }
+
+/* ========================================================================== */
+
/*
* All platform plugins and configuration magic happens here instead of build.gradle
* because JMV-only projects depend on core, thus core should always be initialized before configuration.
@@ -18,7 +65,7 @@
configure(sourceSets) {
def srcDir = name.endsWith('Main') ? 'src' : 'test'
def platform = name[0..-5]
- kotlin.srcDir "$platform/$srcDir"
+ kotlin.srcDirs = ["$platform/$srcDir"]
if (name == "jvmMain") {
resources.srcDirs = ["$platform/resources"]
} else if (name == "jvmTest") {
@@ -31,12 +78,18 @@
}
configure(targets) {
- def targetName = it.name
- compilations.all { compilation ->
- def compileTask = tasks.getByName(compilation.compileKotlinTaskName)
- // binary compatibility support
- if (targetName.contains("jvm") && compilation.compilationName == "main") {
- compileTask.kotlinOptions.freeCompilerArgs += ["-Xdump-declarations-to=${buildDir}/visibilities.json"]
+ // Configure additional binaries and test runs -- one for each OS
+ if (["macos", "linux", "mingw"].any { name.startsWith(it) }) {
+ binaries {
+ // Test for memory leaks using a special entry point that does not exit but returns from main
+ binaries.getTest("DEBUG").freeCompilerArgs += ["-e", "kotlinx.coroutines.mainNoExit"]
+ // Configure a separate test where code runs in background
+ test("background", [org.jetbrains.kotlin.gradle.plugin.mpp.NativeBuildType.DEBUG]) {
+ freeCompilerArgs += ["-e", "kotlinx.coroutines.mainBackground"]
+ }
+ }
+ testRuns {
+ background { setExecutionSourceFrom(binaries.backgroundDebugTest) }
}
}
}
@@ -54,23 +107,52 @@
}
}
+// :KLUDGE: Idea.active: This is needed to workaround resolve problems after importing this project to IDEA
+def configureNativeSourceSetPreset(name, preset) {
+ def hostMainCompilation = project.kotlin.targetFromPreset(preset).compilations.main
+ // Look for platform libraries in "implementation" for default source set
+ def implementationConfiguration = configurations[hostMainCompilation.defaultSourceSet.implementationMetadataConfigurationName]
+ // Now find the libraries: Finds platform libs & stdlib, but platform declarations are still not resolved due to IDE bugs
+ def hostNativePlatformLibs = files(
+ provider {
+ implementationConfiguration.findAll {
+ it.path.endsWith(".klib") || it.absolutePath.contains("klib${File.separator}platform") || it.absolutePath.contains("stdlib")
+ }
+ }
+ )
+ // Add all those dependencies
+ for (suffix in sourceSetSuffixes) {
+ configure(kotlin.sourceSets[name + suffix]) {
+ dependencies.add(implementationMetadataConfigurationName, hostNativePlatformLibs)
+ }
+ }
+}
+
+// :KLUDGE: Idea.active: Configure platform libraries for native source sets when working in IDEA
+if (Idea.active) {
+ def manager = project.ext.hostManager
+ def linuxPreset = kotlin.presets.linuxX64
+ def macosPreset = kotlin.presets.macosX64
+ // linux should be always available (cross-compilation capable) -- use it as default
+ assert manager.isEnabled(linuxPreset.konanTarget)
+ // use macOS libs for nativeDarwin if available
+ def macosAvailable = manager.isEnabled(macosPreset.konanTarget)
+ // configure source sets
+ configureNativeSourceSetPreset("native", linuxPreset)
+ configureNativeSourceSetPreset("nativeOther", linuxPreset)
+ configureNativeSourceSetPreset("nativeDarwin", macosAvailable ? macosPreset : linuxPreset)
+}
+
kotlin.sourceSets {
jvmMain.dependencies {
compileOnly "com.google.android:annotations:4.1.1.4"
}
jvmTest.dependencies {
- // This is a workaround for https://youtrack.jetbrains.com/issue/KT-39037
- def excludingCurrentProject = { dependency ->
- def result = project.dependencies.create(dependency)
- result.exclude(module: project.name)
- return result
- }
-
- api(excludingCurrentProject("org.jetbrains.kotlinx:lincheck:$lincheck_version"))
+ api "org.jetbrains.kotlinx:lincheck:$lincheck_version"
api "org.jetbrains.kotlinx:kotlinx-knit-test:$knit_version"
api "com.esotericsoftware:kryo:4.0.0"
- implementation(excludingCurrentProject(project(":android-unit-tests")))
+ implementation project(":android-unit-tests")
}
}
@@ -97,7 +179,7 @@
enableAssertions = true
systemProperty 'java.security.manager', 'kotlinx.coroutines.TestSecurityManager'
// 'stress' is required to be able to run all subpackage tests like ":jvmTests --tests "*channels*" -Pstress=true"
- if (!project.ext.ideaActive && rootProject.properties['stress'] == null) {
+ if (!Idea.active && rootProject.properties['stress'] == null) {
exclude '**/*StressTest.*'
}
systemProperty 'kotlinx.coroutines.scheduler.keep.alive.sec', '100000' // any unpark problem hangs test
@@ -131,6 +213,7 @@
exclude '**/*LCStressTest.*' // lin-check tests use LinChecker which needs JDK8
exclude '**/exceptions/**' // exceptions tests check suppressed exception which needs JDK8
exclude '**/ExceptionsGuideTest.*'
+ exclude '**/RunInterruptibleStressTest.*' // fails on JDK 1.6 due to JDK bug
}
// Run these tests only during nightly stress test
diff --git a/kotlinx-coroutines-core/common/src/Await.kt b/kotlinx-coroutines-core/common/src/Await.kt
index dd1e177..7189349 100644
--- a/kotlinx-coroutines-core/common/src/Await.kt
+++ b/kotlinx-coroutines-core/common/src/Await.kt
@@ -5,6 +5,7 @@
package kotlinx.coroutines
import kotlinx.atomicfu.*
+import kotlinx.coroutines.channels.*
import kotlin.coroutines.*
/**
@@ -18,6 +19,8 @@
* This suspending function is cancellable.
* If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting,
* this function immediately resumes with [CancellationException].
+ * There is a **prompt cancellation guarantee**. If the job was cancelled while this function was
+ * suspended, it will not resume successfully. See [suspendCancellableCoroutine] documentation for low-level details.
*/
public suspend fun <T> awaitAll(vararg deferreds: Deferred<T>): List<T> =
if (deferreds.isEmpty()) emptyList() else AwaitAll(deferreds).await()
@@ -33,6 +36,8 @@
* This suspending function is cancellable.
* If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting,
* this function immediately resumes with [CancellationException].
+ * There is a **prompt cancellation guarantee**. If the job was cancelled while this function was
+ * suspended, it will not resume successfully. See [suspendCancellableCoroutine] documentation for low-level details.
*/
public suspend fun <T> Collection<Deferred<T>>.awaitAll(): List<T> =
if (isEmpty()) emptyList() else AwaitAll(toTypedArray()).await()
@@ -41,8 +46,11 @@
* Suspends current coroutine until all given jobs are complete.
* This method is semantically equivalent to joining all given jobs one by one with `jobs.forEach { it.join() }`.
*
- * This suspending function is cancellable. If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting,
+ * This suspending function is cancellable.
+ * If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting,
* this function immediately resumes with [CancellationException].
+ * There is a **prompt cancellation guarantee**. If the job was cancelled while this function was
+ * suspended, it will not resume successfully. See [suspendCancellableCoroutine] documentation for low-level details.
*/
public suspend fun joinAll(vararg jobs: Job): Unit = jobs.forEach { it.join() }
@@ -50,8 +58,11 @@
* Suspends current coroutine until all given jobs are complete.
* This method is semantically equivalent to joining all given jobs one by one with `forEach { it.join() }`.
*
- * This suspending function is cancellable. If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting,
+ * This suspending function is cancellable.
+ * If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting,
* this function immediately resumes with [CancellationException].
+ * There is a **prompt cancellation guarantee**. If the job was cancelled while this function was
+ * suspended, it will not resume successfully. See [suspendCancellableCoroutine] documentation for low-level details.
*/
public suspend fun Collection<Job>.joinAll(): Unit = forEach { it.join() }
diff --git a/kotlinx-coroutines-core/common/src/Builders.common.kt b/kotlinx-coroutines-core/common/src/Builders.common.kt
index 64bff50..b7deacc 100644
--- a/kotlinx-coroutines-core/common/src/Builders.common.kt
+++ b/kotlinx-coroutines-core/common/src/Builders.common.kt
@@ -129,8 +129,9 @@
* This function uses dispatcher from the new context, shifting execution of the [block] into the
* different thread if a new dispatcher is specified, and back to the original dispatcher
* when it completes. Note that the result of `withContext` invocation is
- * dispatched into the original context in a cancellable way, which means that if the original [coroutineContext],
- * in which `withContext` was invoked, is cancelled by the time its dispatcher starts to execute the code,
+ * dispatched into the original context in a cancellable way with a **prompt cancellation guarantee**,
+ * which means that if the original [coroutineContext], in which `withContext` was invoked,
+ * is cancelled by the time its dispatcher starts to execute the code,
* it discards the result of `withContext` and throws [CancellationException].
*/
public suspend fun <T> withContext(
@@ -174,7 +175,6 @@
*
* This inline function calls [withContext].
*/
-@ExperimentalCoroutinesApi
public suspend inline operator fun <T> CoroutineDispatcher.invoke(
noinline block: suspend CoroutineScope.() -> T
): T = withContext(this, block)
diff --git a/kotlinx-coroutines-core/common/src/CancellableContinuation.kt b/kotlinx-coroutines-core/common/src/CancellableContinuation.kt
index 0d3fe84..7d9315a 100644
--- a/kotlinx-coroutines-core/common/src/CancellableContinuation.kt
+++ b/kotlinx-coroutines-core/common/src/CancellableContinuation.kt
@@ -15,6 +15,8 @@
* When the [cancel] function is explicitly invoked, this continuation immediately resumes with a [CancellationException] or
* the specified cancel cause.
*
+ * An instance of `CancellableContinuation` is created by the [suspendCancellableCoroutine] function.
+ *
* Cancellable continuation has three states (as subset of [Job] states):
*
* | **State** | [isActive] | [isCompleted] | [isCancelled] |
@@ -24,14 +26,12 @@
* | _Canceled_ (final _completed_ state)| `false` | `true` | `true` |
*
* Invocation of [cancel] transitions this continuation from _active_ to _cancelled_ state, while
- * invocation of [resume] or [resumeWithException] transitions it from _active_ to _resumed_ state.
+ * invocation of [Continuation.resume] or [Continuation.resumeWithException] transitions it from _active_ to _resumed_ state.
*
* A [cancelled][isCancelled] continuation implies that it is [completed][isCompleted].
*
- * Invocation of [resume] or [resumeWithException] in _resumed_ state produces an [IllegalStateException].
- * Invocation of [resume] in _cancelled_ state is ignored (it is a trivial race between resume from the continuation owner and
- * outer job's cancellation, and the cancellation wins).
- * Invocation of [resumeWithException] in _cancelled_ state triggers exception handling of the passed exception.
+ * Invocation of [Continuation.resume] or [Continuation.resumeWithException] in _resumed_ state produces an [IllegalStateException],
+ * but is ignored in _cancelled_ state.
*
* ```
* +-----------+ resume +---------+
@@ -43,7 +43,6 @@
* +-----------+
* | Cancelled |
* +-----------+
- *
* ```
*/
public interface CancellableContinuation<in T> : Continuation<T> {
@@ -79,6 +78,14 @@
public fun tryResume(value: T, idempotent: Any? = null): Any?
/**
+ * Same as [tryResume] but with [onCancellation] handler that called if and only if the value is not
+ * delivered to the caller because of the dispatch in the process, so that atomicity delivery
+ * guaranteed can be provided by having a cancellation fallback.
+ */
+ @InternalCoroutinesApi
+ public fun tryResume(value: T, idempotent: Any?, onCancellation: ((cause: Throwable) -> Unit)?): Any?
+
+ /**
* Tries to resume this continuation with the specified [exception] and returns a non-null object token if successful,
* or `null` otherwise (it was already resumed or cancelled). When a non-null object is returned,
* [completeResume] must be invoked with it.
@@ -112,8 +119,8 @@
public fun cancel(cause: Throwable? = null): Boolean
/**
- * Registers a [handler] to be **synchronously** invoked on cancellation (regular or exceptional) of this continuation.
- * When the continuation is already cancelled, the handler will be immediately invoked
+ * Registers a [handler] to be **synchronously** invoked on [cancellation][cancel] (regular or exceptional) of this continuation.
+ * When the continuation is already cancelled, the handler is immediately invoked
* with the cancellation exception. Otherwise, the handler will be invoked as soon as this
* continuation is cancelled.
*
@@ -122,7 +129,15 @@
* processed as an uncaught exception in the context of the current coroutine
* (see [CoroutineExceptionHandler]).
*
- * At most one [handler] can be installed on a continuation.
+ * At most one [handler] can be installed on a continuation. Attempt to call `invokeOnCancellation` second
+ * time produces [IllegalStateException].
+ *
+ * This handler is also called when this continuation [resumes][Continuation.resume] normally (with a value) and then
+ * is cancelled while waiting to be dispatched. More generally speaking, this handler is called whenever
+ * the caller of [suspendCancellableCoroutine] is getting a [CancellationException].
+ *
+ * A typical example for `invokeOnCancellation` usage is given in
+ * the documentation for the [suspendCancellableCoroutine] function.
*
* **Note**: Implementation of `CompletionHandler` must be fast, non-blocking, and thread-safe.
* This `handler` can be invoked concurrently with the surrounding code.
@@ -165,7 +180,7 @@
* (see [CoroutineExceptionHandler]).
*
* This function shall be used when resuming with a resource that must be closed by
- * code that called the corresponding suspending function, e.g.:
+ * code that called the corresponding suspending function, for example:
*
* ```
* continuation.resume(resource) {
@@ -173,17 +188,119 @@
* }
* ```
*
+ * A more complete example and further details are given in
+ * the documentation for the [suspendCancellableCoroutine] function.
+ *
* **Note**: The [onCancellation] handler must be fast, non-blocking, and thread-safe.
* It can be invoked concurrently with the surrounding code.
* There is no guarantee on the execution context of its invocation.
*/
@ExperimentalCoroutinesApi // since 1.2.0
- public fun resume(value: T, onCancellation: (cause: Throwable) -> Unit)
+ public fun resume(value: T, onCancellation: ((cause: Throwable) -> Unit)?)
}
/**
* Suspends the coroutine like [suspendCoroutine], but providing a [CancellableContinuation] to
- * the [block]. This function throws a [CancellationException] if the coroutine is cancelled or completed while suspended.
+ * the [block]. This function throws a [CancellationException] if the [Job] of the coroutine is
+ * cancelled or completed while it is suspended.
+ *
+ * A typical use of this function is to suspend a coroutine while waiting for a result
+ * from a single-shot callback API and to return the result to the caller.
+ * For multi-shot callback APIs see [callbackFlow][kotlinx.coroutines.flow.callbackFlow].
+ *
+ * ```
+ * suspend fun awaitCallback(): T = suspendCancellableCoroutine { continuation ->
+ * val callback = object : Callback { // Implementation of some callback interface
+ * override fun onCompleted(value: T) {
+ * // Resume coroutine with a value provided by the callback
+ * continuation.resume(value)
+ * }
+ * override fun onApiError(cause: Throwable) {
+ * // Resume coroutine with an exception provided by the callback
+ * continuation.resumeWithException(cause)
+ * }
+ * }
+ * // Register callback with an API
+ * api.register(callback)
+ * // Remove callback on cancellation
+ * continuation.invokeOnCancellation { api.unregister(callback) }
+ * // At this point the coroutine is suspended by suspendCancellableCoroutine until callback fires
+ * }
+ * ```
+ *
+ * > The callback `register`/`unregister` methods provided by an external API must be thread-safe, because
+ * > `invokeOnCancellation` block can be called at any time due to asynchronous nature of cancellation, even
+ * > concurrently with the call of the callback.
+ *
+ * ### Prompt cancellation guarantee
+ *
+ * This function provides **prompt cancellation guarantee**.
+ * If the [Job] of the current coroutine was cancelled while this function was suspended it will not resume
+ * successfully.
+ *
+ * The cancellation of the coroutine's job is generally asynchronous with respect to the suspended coroutine.
+ * The suspended coroutine is resumed with the call it to its [Continuation.resumeWith] member function or to
+ * [resume][Continuation.resume] extension function.
+ * However, when coroutine is resumed, it does not immediately start executing, but is passed to its
+ * [CoroutineDispatcher] to schedule its execution when dispatcher's resources become available for execution.
+ * The job's cancellation can happen both before, after, and concurrently with the call to `resume`. In any
+ * case, prompt cancellation guarantees that the the coroutine will not resume its code successfully.
+ *
+ * If the coroutine was resumed with an exception (for example, using [Continuation.resumeWithException] extension
+ * function) and cancelled, then the resulting exception of the `suspendCancellableCoroutine` function is determined
+ * by whichever action (exceptional resume or cancellation) that happened first.
+ *
+ * ### Returning resources from a suspended coroutine
+ *
+ * As a result of a prompt cancellation guarantee, when a closeable resource
+ * (like open file or a handle to another native resource) is returned from a suspended coroutine as a value
+ * it can be lost when the coroutine is cancelled. In order to ensure that the resource can be properly closed
+ * in this case, the [CancellableContinuation] interface provides two functions.
+ *
+ * * [invokeOnCancellation][CancellableContinuation.invokeOnCancellation] installs a handler that is called
+ * whenever a suspend coroutine is being cancelled. In addition to the example at the beginning, it can be
+ * used to ensure that a resource that was opened before the call to
+ * `suspendCancellableCoroutine` or in its body is closed in case of cancellation.
+ *
+ * ```
+ * suspendCancellableCoroutine { continuation ->
+ * val resource = openResource() // Opens some resource
+ * continuation.invokeOnCancellation {
+ * resource.close() // Ensures the resource is closed on cancellation
+ * }
+ * // ...
+ * }
+ * ```
+ *
+ * * [resume(value) { ... }][CancellableContinuation.resume] method on a [CancellableContinuation] takes
+ * an optional `onCancellation` block. It can be used when resuming with a resource that must be closed by
+ * the code that called the corresponding suspending function.
+ *
+ * ```
+ * suspendCancellableCoroutine { continuation ->
+ * val callback = object : Callback { // Implementation of some callback interface
+ * // A callback provides a reference to some closeable resource
+ * override fun onCompleted(resource: T) {
+ * // Resume coroutine with a value provided by the callback and ensure the resource is closed in case
+ * // when the coroutine is cancelled before the caller gets a reference to the resource.
+ * continuation.resume(resource) {
+ * resource.close() // Close the resource on cancellation
+ * }
+ * }
+ * // ...
+ * }
+ * ```
+ *
+ * ### Implementation details and custom continuation interceptors
+ *
+ * The prompt cancellation guarantee is the result of a coordinated implementation inside `suspendCancellableCoroutine`
+ * function and the [CoroutineDispatcher] class. The coroutine dispatcher checks for the status of the [Job] immediately
+ * before continuing its normal execution and aborts this normal execution, calling all the corresponding
+ * cancellation handlers, if the job was cancelled.
+ *
+ * If a custom implementation of [ContinuationInterceptor] is used in a coroutine's context that does not extend
+ * [CoroutineDispatcher] class, then there is no prompt cancellation guarantee. A custom continuation interceptor
+ * can resume execution of a previously suspended coroutine even if its job was already cancelled.
*/
public suspend inline fun <T> suspendCancellableCoroutine(
crossinline block: (CancellableContinuation<T>) -> Unit
@@ -201,29 +318,10 @@
}
/**
- * Suspends the coroutine like [suspendCancellableCoroutine], but with *atomic cancellation*.
- *
- * When the suspended function throws a [CancellationException], it means that the continuation was not resumed.
- * As a side-effect of atomic cancellation, a thread-bound coroutine (to some UI thread, for example) may
- * continue to execute even after it was cancelled from the same thread in the case when the continuation
- * was already resumed and was posted for execution to the thread's queue.
- *
- * @suppress **This an internal API and should not be used from general code.**
+ * Suspends the coroutine similar to [suspendCancellableCoroutine], but an instance of
+ * [CancellableContinuationImpl] is reused.
*/
-@InternalCoroutinesApi
-public suspend inline fun <T> suspendAtomicCancellableCoroutine(
- crossinline block: (CancellableContinuation<T>) -> Unit
-): T =
- suspendCoroutineUninterceptedOrReturn { uCont ->
- val cancellable = CancellableContinuationImpl(uCont.intercepted(), resumeMode = MODE_ATOMIC_DEFAULT)
- block(cancellable)
- cancellable.getResult()
- }
-
-/**
- * Suspends coroutine similar to [suspendAtomicCancellableCoroutine], but an instance of [CancellableContinuationImpl] is reused if possible.
- */
-internal suspend inline fun <T> suspendAtomicCancellableCoroutineReusable(
+internal suspend inline fun <T> suspendCancellableCoroutineReusable(
crossinline block: (CancellableContinuation<T>) -> Unit
): T = suspendCoroutineUninterceptedOrReturn { uCont ->
val cancellable = getOrCreateCancellableContinuation(uCont.intercepted())
@@ -234,12 +332,12 @@
internal fun <T> getOrCreateCancellableContinuation(delegate: Continuation<T>): CancellableContinuationImpl<T> {
// If used outside of our dispatcher
if (delegate !is DispatchedContinuation<T>) {
- return CancellableContinuationImpl(delegate, resumeMode = MODE_ATOMIC_DEFAULT)
+ return CancellableContinuationImpl(delegate, MODE_CANCELLABLE_REUSABLE)
}
/*
* Attempt to claim reusable instance.
*
- * suspendAtomicCancellableCoroutineReusable { // <- claimed
+ * suspendCancellableCoroutineReusable { // <- claimed
* // Any asynchronous cancellation is "postponed" while this block
* // is being executed
* } // postponed cancellation is checked here.
@@ -250,26 +348,13 @@
* thus leaking CC instance for indefinite time.
* 2) Continuation was cancelled. Then we should prevent any further reuse and bail out.
*/
- return delegate.claimReusableCancellableContinuation()?.takeIf { it.resetState() }
- ?: return CancellableContinuationImpl(delegate, MODE_ATOMIC_DEFAULT)
+ return delegate.claimReusableCancellableContinuation()?.takeIf { it.resetStateReusable() }
+ ?: return CancellableContinuationImpl(delegate, MODE_CANCELLABLE_REUSABLE)
}
/**
- * @suppress **Deprecated**
- */
-@Deprecated(
- message = "holdCancellability parameter is deprecated and is no longer used",
- replaceWith = ReplaceWith("suspendAtomicCancellableCoroutine(block)")
-)
-@InternalCoroutinesApi
-public suspend inline fun <T> suspendAtomicCancellableCoroutine(
- holdCancellability: Boolean = false,
- crossinline block: (CancellableContinuation<T>) -> Unit
-): T =
- suspendAtomicCancellableCoroutine(block)
-
-/**
- * Removes the specified [node] on cancellation.
+ * Removes the specified [node] on cancellation. This function assumes that this node is already
+ * removed on successful resume and does not try to remove it if the continuation is cancelled during dispatch.
*/
internal fun CancellableContinuation<*>.removeOnCancellation(node: LockFreeLinkedListNode) =
invokeOnCancellation(handler = RemoveOnCancel(node).asHandler)
@@ -290,7 +375,7 @@
// --------------- implementation details ---------------
-private class RemoveOnCancel(private val node: LockFreeLinkedListNode) : CancelHandler() {
+private class RemoveOnCancel(private val node: LockFreeLinkedListNode) : BeforeResumeCancelHandler() {
override fun invoke(cause: Throwable?) { node.remove() }
override fun toString() = "RemoveOnCancel[$node]"
}
diff --git a/kotlinx-coroutines-core/common/src/CancellableContinuationImpl.kt b/kotlinx-coroutines-core/common/src/CancellableContinuationImpl.kt
index e25ebd3..cdb1b78 100644
--- a/kotlinx-coroutines-core/common/src/CancellableContinuationImpl.kt
+++ b/kotlinx-coroutines-core/common/src/CancellableContinuationImpl.kt
@@ -27,6 +27,10 @@
final override val delegate: Continuation<T>,
resumeMode: Int
) : DispatchedTask<T>(resumeMode), CancellableContinuation<T>, CoroutineStackFrame {
+ init {
+ assert { resumeMode != MODE_UNINITIALIZED } // invalid mode for CancellableContinuationImpl
+ }
+
public override val context: CoroutineContext = delegate.context
/*
@@ -88,15 +92,17 @@
private fun isReusable(): Boolean = delegate is DispatchedContinuation<*> && delegate.isReusable(this)
/**
- * Resets cancellability state in order to [suspendAtomicCancellableCoroutineReusable] to work.
- * Invariant: used only by [suspendAtomicCancellableCoroutineReusable] in [REUSABLE_CLAIMED] state.
+ * Resets cancellability state in order to [suspendCancellableCoroutineReusable] to work.
+ * Invariant: used only by [suspendCancellableCoroutineReusable] in [REUSABLE_CLAIMED] state.
*/
- @JvmName("resetState") // Prettier stack traces
- internal fun resetState(): Boolean {
+ @JvmName("resetStateReusable") // Prettier stack traces
+ internal fun resetStateReusable(): Boolean {
+ assert { resumeMode == MODE_CANCELLABLE_REUSABLE } // invalid mode for CancellableContinuationImpl
assert { parentHandle !== NonDisposableHandle }
val state = _state.value
assert { state !is NotCompleted }
- if (state is CompletedIdempotentResult) {
+ if (state is CompletedContinuation && state.idempotentResume != null) {
+ // Cannot reuse continuation that was resumed with idempotent marker
detachChild()
return false
}
@@ -114,7 +120,6 @@
if (checkCompleted()) return
if (parentHandle !== null) return // fast path 2 -- was already initialized
val parent = delegate.context[Job] ?: return // fast path 3 -- don't do anything without parent
- parent.start() // make sure the parent is started
val handle = parent.invokeOnCompletion(
onCancelling = true,
handler = ChildContinuation(parent, this).asHandler
@@ -130,7 +135,7 @@
private fun checkCompleted(): Boolean {
val completed = isCompleted
- if (resumeMode != MODE_ATOMIC_DEFAULT) return completed // Do not check postponed cancellation for non-reusable continuations
+ if (!resumeMode.isReusableMode) return completed // Do not check postponed cancellation for non-reusable continuations
val dispatched = delegate as? DispatchedContinuation<*> ?: return completed
val cause = dispatched.checkPostponedCancellation(this) ?: return completed
if (!completed) {
@@ -147,10 +152,26 @@
override fun takeState(): Any? = state
- override fun cancelResult(state: Any?, cause: Throwable) {
- if (state is CompletedWithCancellation) {
- invokeHandlerSafely {
- state.onCancellation(cause)
+ // Note: takeState does not clear the state so we don't use takenState
+ // and we use the actual current state where in CAS-loop
+ override fun cancelCompletedResult(takenState: Any?, cause: Throwable): Unit = _state.loop { state ->
+ when (state) {
+ is NotCompleted -> error("Not completed")
+ is CompletedExceptionally -> return // already completed exception or cancelled, nothing to do
+ is CompletedContinuation -> {
+ check(!state.cancelled) { "Must be called at most once" }
+ val update = state.copy(cancelCause = cause)
+ if (_state.compareAndSet(state, update)) {
+ state.invokeHandlers(this, cause)
+ return // done
+ }
+ }
+ else -> {
+ // completed normally without marker class, promote to CompletedContinuation in case
+ // if invokeOnCancellation if called later
+ if (_state.compareAndSet(state, CompletedContinuation(state, cancelCause = cause))) {
+ return // done
+ }
}
}
}
@@ -159,7 +180,7 @@
* Attempt to postpone cancellation for reusable cancellable continuation
*/
private fun cancelLater(cause: Throwable): Boolean {
- if (resumeMode != MODE_ATOMIC_DEFAULT) return false
+ if (!resumeMode.isReusableMode) return false
val dispatched = (delegate as? DispatchedContinuation<*>) ?: return false
return dispatched.postponeCancellation(cause)
}
@@ -171,10 +192,10 @@
val update = CancelledContinuation(this, cause, handled = state is CancelHandler)
if (!_state.compareAndSet(state, update)) return@loop // retry on cas failure
// Invoke cancel handler if it was present
- if (state is CancelHandler) invokeHandlerSafely { state.invoke(cause) }
+ (state as? CancelHandler)?.let { callCancelHandler(it, cause) }
// Complete state update
detachChildIfNonResuable()
- dispatchResume(mode = MODE_ATOMIC_DEFAULT)
+ dispatchResume(resumeMode) // no need for additional cancellation checks
return true
}
}
@@ -186,14 +207,36 @@
detachChildIfNonResuable()
}
- private inline fun invokeHandlerSafely(block: () -> Unit) {
+ private inline fun callCancelHandlerSafely(block: () -> Unit) {
try {
- block()
+ block()
} catch (ex: Throwable) {
// Handler should never fail, if it does -- it is an unhandled exception
handleCoroutineException(
context,
- CompletionHandlerException("Exception in cancellation handler for $this", ex)
+ CompletionHandlerException("Exception in invokeOnCancellation handler for $this", ex)
+ )
+ }
+ }
+
+ private fun callCancelHandler(handler: CompletionHandler, cause: Throwable?) =
+ /*
+ * :KLUDGE: We have to invoke a handler in platform-specific way via `invokeIt` extension,
+ * because we play type tricks on Kotlin/JS and handler is not necessarily a function there
+ */
+ callCancelHandlerSafely { handler.invokeIt(cause) }
+
+ fun callCancelHandler(handler: CancelHandler, cause: Throwable?) =
+ callCancelHandlerSafely { handler.invoke(cause) }
+
+ fun callOnCancellation(onCancellation: (cause: Throwable) -> Unit, cause: Throwable) {
+ try {
+ onCancellation.invoke(cause)
+ } catch (ex: Throwable) {
+ // Handler should never fail, if it does -- it is an unhandled exception
+ handleCoroutineException(
+ context,
+ CompletionHandlerException("Exception in resume onCancellation handler for $this", ex)
)
}
}
@@ -232,64 +275,75 @@
val state = this.state
if (state is CompletedExceptionally) throw recoverStackTrace(state.cause, this)
// if the parent job was already cancelled, then throw the corresponding cancellation exception
- // otherwise, there is a race is suspendCancellableCoroutine { cont -> ... } does cont.resume(...)
+ // otherwise, there is a race if suspendCancellableCoroutine { cont -> ... } does cont.resume(...)
// before the block returns. This getResult would return a result as opposed to cancellation
// exception that should have happened if the continuation is dispatched for execution later.
- if (resumeMode == MODE_CANCELLABLE) {
+ if (resumeMode.isCancellableMode) {
val job = context[Job]
if (job != null && !job.isActive) {
val cause = job.getCancellationException()
- cancelResult(state, cause)
+ cancelCompletedResult(state, cause)
throw recoverStackTrace(cause, this)
}
}
return getSuccessfulResult(state)
}
- override fun resumeWith(result: Result<T>) {
+ override fun resumeWith(result: Result<T>) =
resumeImpl(result.toState(this), resumeMode)
- }
- override fun resume(value: T, onCancellation: (cause: Throwable) -> Unit) {
- val cancelled = resumeImpl(CompletedWithCancellation(value, onCancellation), resumeMode)
- if (cancelled != null) {
- // too late to resume (was cancelled) -- call handler
- invokeHandlerSafely {
- onCancellation(cancelled.cause)
- }
- }
- }
+ override fun resume(value: T, onCancellation: ((cause: Throwable) -> Unit)?) =
+ resumeImpl(value, resumeMode, onCancellation)
public override fun invokeOnCancellation(handler: CompletionHandler) {
- var handleCache: CancelHandler? = null
+ val cancelHandler = makeCancelHandler(handler)
_state.loop { state ->
when (state) {
is Active -> {
- val node = handleCache ?: makeHandler(handler).also { handleCache = it }
- if (_state.compareAndSet(state, node)) return // quit on cas success
+ if (_state.compareAndSet(state, cancelHandler)) return // quit on cas success
}
is CancelHandler -> multipleHandlersError(handler, state)
- is CancelledContinuation -> {
+ is CompletedExceptionally -> {
/*
- * Continuation was already cancelled, invoke directly.
+ * Continuation was already cancelled or completed exceptionally.
* NOTE: multiple invokeOnCancellation calls with different handlers are not allowed,
- * so we check to make sure that handler was installed just once.
+ * so we check to make sure handler was installed just once.
*/
if (!state.makeHandled()) multipleHandlersError(handler, state)
/*
+ * Call the handler only if it was cancelled (not called when completed exceptionally).
* :KLUDGE: We have to invoke a handler in platform-specific way via `invokeIt` extension,
* because we play type tricks on Kotlin/JS and handler is not necessarily a function there
*/
- invokeHandlerSafely { handler.invokeIt((state as? CompletedExceptionally)?.cause) }
+ if (state is CancelledContinuation) {
+ callCancelHandler(handler, (state as? CompletedExceptionally)?.cause)
+ }
return
}
+ is CompletedContinuation -> {
+ /*
+ * Continuation was already completed, and might already have cancel handler.
+ */
+ if (state.cancelHandler != null) multipleHandlersError(handler, state)
+ // BeforeResumeCancelHandler does not need to be called on a completed continuation
+ if (cancelHandler is BeforeResumeCancelHandler) return
+ if (state.cancelled) {
+ // Was already cancelled while being dispatched -- invoke the handler directly
+ callCancelHandler(handler, state.cancelCause)
+ return
+ }
+ val update = state.copy(cancelHandler = cancelHandler)
+ if (_state.compareAndSet(state, update)) return // quit on cas success
+ }
else -> {
/*
- * Continuation was already completed, do nothing.
- * NOTE: multiple invokeOnCancellation calls with different handlers are not allowed,
- * but we have no way to check that it was installed just once in this case.
+ * Continuation was already completed normally, but might get cancelled while being dispatched.
+ * Change its state to CompletedContinuation, unless we have BeforeResumeCancelHandler which
+ * does not need to be called in this case.
*/
- return
+ if (cancelHandler is BeforeResumeCancelHandler) return
+ val update = CompletedContinuation(state, cancelHandler = cancelHandler)
+ if (_state.compareAndSet(state, update)) return // quit on cas success
}
}
}
@@ -299,7 +353,7 @@
error("It's prohibited to register multiple handlers, tried to register $handler, already has $state")
}
- private fun makeHandler(handler: CompletionHandler): CancelHandler =
+ private fun makeCancelHandler(handler: CompletionHandler): CancelHandler =
if (handler is CancelHandler) handler else InvokeOnCancel(handler)
private fun dispatchResume(mode: Int) {
@@ -308,15 +362,39 @@
dispatch(mode)
}
- // returns null when successfully dispatched resumed, CancelledContinuation if too late (was already cancelled)
- private fun resumeImpl(proposedUpdate: Any?, resumeMode: Int): CancelledContinuation? {
+ private fun resumedState(
+ state: NotCompleted,
+ proposedUpdate: Any?,
+ resumeMode: Int,
+ onCancellation: ((cause: Throwable) -> Unit)?,
+ idempotent: Any?
+ ): Any? = when {
+ proposedUpdate is CompletedExceptionally -> {
+ assert { idempotent == null } // there are no idempotent exceptional resumes
+ assert { onCancellation == null } // only successful results can be cancelled
+ proposedUpdate
+ }
+ !resumeMode.isCancellableMode && idempotent == null -> proposedUpdate // cannot be cancelled in process, all is fine
+ onCancellation != null || (state is CancelHandler && state !is BeforeResumeCancelHandler) || idempotent != null ->
+ // mark as CompletedContinuation if special cases are present:
+ // Cancellation handlers that shall be called after resume or idempotent resume
+ CompletedContinuation(proposedUpdate, state as? CancelHandler, onCancellation, idempotent)
+ else -> proposedUpdate // simple case -- use the value directly
+ }
+
+ private fun resumeImpl(
+ proposedUpdate: Any?,
+ resumeMode: Int,
+ onCancellation: ((cause: Throwable) -> Unit)? = null
+ ) {
_state.loop { state ->
when (state) {
is NotCompleted -> {
- if (!_state.compareAndSet(state, proposedUpdate)) return@loop // retry on cas failure
+ val update = resumedState(state, proposedUpdate, resumeMode, onCancellation, idempotent = null)
+ if (!_state.compareAndSet(state, update)) return@loop // retry on cas failure
detachChildIfNonResuable()
- dispatchResume(resumeMode)
- return null
+ dispatchResume(resumeMode) // dispatch resume, but it might get cancelled in process
+ return // done
}
is CancelledContinuation -> {
/*
@@ -324,14 +402,48 @@
* because cancellation is asynchronous and may race with resume.
* Racy exceptions will be lost, too.
*/
- if (state.makeResumed()) return state // tried to resume just once, but was cancelled
+ if (state.makeResumed()) { // check if trying to resume one (otherwise error)
+ // call onCancellation
+ onCancellation?.let { callOnCancellation(it, state.cause) }
+ return // done
+ }
}
}
- alreadyResumedError(proposedUpdate) // otherwise -- an error (second resume attempt)
+ alreadyResumedError(proposedUpdate) // otherwise, an error (second resume attempt)
}
}
- private fun alreadyResumedError(proposedUpdate: Any?) {
+ /**
+ * Similar to [tryResume], but does not actually completes resume (needs [completeResume] call).
+ * Returns [RESUME_TOKEN] when resumed, `null` when it was already resumed or cancelled.
+ */
+ private fun tryResumeImpl(
+ proposedUpdate: Any?,
+ idempotent: Any?,
+ onCancellation: ((cause: Throwable) -> Unit)?
+ ): Symbol? {
+ _state.loop { state ->
+ when (state) {
+ is NotCompleted -> {
+ val update = resumedState(state, proposedUpdate, resumeMode, onCancellation, idempotent)
+ if (!_state.compareAndSet(state, update)) return@loop // retry on cas failure
+ detachChildIfNonResuable()
+ return RESUME_TOKEN
+ }
+ is CompletedContinuation -> {
+ return if (idempotent != null && state.idempotentResume === idempotent) {
+ assert { state.result == proposedUpdate } // "Non-idempotent resume"
+ RESUME_TOKEN // resumed with the same token -- ok
+ } else {
+ null // resumed with a different token or non-idempotent -- too late
+ }
+ }
+ else -> return null // cannot resume -- not active anymore
+ }
+ }
+ }
+
+ private fun alreadyResumedError(proposedUpdate: Any?): Nothing {
error("Already resumed, but proposed with update $proposedUpdate")
}
@@ -343,7 +455,7 @@
/**
* Detaches from the parent.
- * Invariant: used used from [CoroutineDispatcher.releaseInterceptedContinuation] iff [isReusable] is `true`
+ * Invariant: used from [CoroutineDispatcher.releaseInterceptedContinuation] iff [isReusable] is `true`
*/
internal fun detachChild() {
val handle = parentHandle
@@ -352,42 +464,14 @@
}
// Note: Always returns RESUME_TOKEN | null
- override fun tryResume(value: T, idempotent: Any?): Any? {
- _state.loop { state ->
- when (state) {
- is NotCompleted -> {
- val update: Any? = if (idempotent == null) value else
- CompletedIdempotentResult(idempotent, value)
- if (!_state.compareAndSet(state, update)) return@loop // retry on cas failure
- detachChildIfNonResuable()
- return RESUME_TOKEN
- }
- is CompletedIdempotentResult -> {
- return if (state.idempotentResume === idempotent) {
- assert { state.result === value } // "Non-idempotent resume"
- RESUME_TOKEN
- } else {
- null
- }
- }
- else -> return null // cannot resume -- not active anymore
- }
- }
- }
+ override fun tryResume(value: T, idempotent: Any?): Any? =
+ tryResumeImpl(value, idempotent, onCancellation = null)
- override fun tryResumeWithException(exception: Throwable): Any? {
- _state.loop { state ->
- when (state) {
- is NotCompleted -> {
- val update = CompletedExceptionally(exception)
- if (!_state.compareAndSet(state, update)) return@loop // retry on cas failure
- detachChildIfNonResuable()
- return RESUME_TOKEN
- }
- else -> return null // cannot resume -- not active anymore
- }
- }
- }
+ override fun tryResume(value: T, idempotent: Any?, onCancellation: ((cause: Throwable) -> Unit)?): Any? =
+ tryResumeImpl(value, idempotent, onCancellation)
+
+ override fun tryResumeWithException(exception: Throwable): Any? =
+ tryResumeImpl(CompletedExceptionally(exception), idempotent = null, onCancellation = null)
// note: token is always RESUME_TOKEN
override fun completeResume(token: Any) {
@@ -408,11 +492,15 @@
@Suppress("UNCHECKED_CAST")
override fun <T> getSuccessfulResult(state: Any?): T =
when (state) {
- is CompletedIdempotentResult -> state.result as T
- is CompletedWithCancellation -> state.result as T
+ is CompletedContinuation -> state.result as T
else -> state as T
}
+ // The exceptional state in CancellableContinuationImpl is stored directly and it is not recovered yet.
+ // The stacktrace recovery is invoked here.
+ override fun getExceptionalResult(state: Any?): Throwable? =
+ super.getExceptionalResult(state)?.let { recoverStackTrace(it, delegate) }
+
// For nicer debugging
public override fun toString(): String =
"${nameString()}(${delegate.toDebugString()}){$state}@$hexAddress"
@@ -429,8 +517,20 @@
override fun toString(): String = "Active"
}
+/**
+ * Base class for all [CancellableContinuation.invokeOnCancellation] handlers to avoid an extra instance
+ * on JVM, yet support JS where you cannot extend from a functional type.
+ */
internal abstract class CancelHandler : CancelHandlerBase(), NotCompleted
+/**
+ * Base class for all [CancellableContinuation.invokeOnCancellation] handlers that don't need to be invoked
+ * if continuation is cancelled after resumption, during dispatch, because the corresponding resources
+ * were already released before calling `resume`. This cancel handler is called only before `resume`.
+ * It avoids allocation of [CompletedContinuation] instance during resume on JVM.
+ */
+internal abstract class BeforeResumeCancelHandler : CancelHandler()
+
// Wrapper for lambdas, for the performance sake CancelHandler can be subclassed directly
private class InvokeOnCancel( // Clashes with InvokeOnCancellation
private val handler: CompletionHandler
@@ -441,16 +541,18 @@
override fun toString() = "InvokeOnCancel[${handler.classSimpleName}@$hexAddress]"
}
-private class CompletedIdempotentResult(
- @JvmField val idempotentResume: Any?,
- @JvmField val result: Any?
-) {
- override fun toString(): String = "CompletedIdempotentResult[$result]"
-}
-
-private class CompletedWithCancellation(
+// Completed with additional metadata
+private data class CompletedContinuation(
@JvmField val result: Any?,
- @JvmField val onCancellation: (cause: Throwable) -> Unit
+ @JvmField val cancelHandler: CancelHandler? = null, // installed via invokeOnCancellation
+ @JvmField val onCancellation: ((cause: Throwable) -> Unit)? = null, // installed via resume block
+ @JvmField val idempotentResume: Any? = null,
+ @JvmField val cancelCause: Throwable? = null
) {
- override fun toString(): String = "CompletedWithCancellation[$result]"
+ val cancelled: Boolean get() = cancelCause != null
+
+ fun invokeHandlers(cont: CancellableContinuationImpl<*>, cause: Throwable) {
+ cancelHandler?.let { cont.callCancelHandler(it, cause) }
+ onCancellation?.let { cont.callOnCancellation(it, cause) }
+ }
}
diff --git a/kotlinx-coroutines-core/common/src/CompletableDeferred.kt b/kotlinx-coroutines-core/common/src/CompletableDeferred.kt
index d24f183..2f00847 100644
--- a/kotlinx-coroutines-core/common/src/CompletableDeferred.kt
+++ b/kotlinx-coroutines-core/common/src/CompletableDeferred.kt
@@ -19,7 +19,7 @@
* All functions on this interface are **thread-safe** and can
* be safely invoked from concurrent coroutines without external synchronization.
*
- * **`CompletableDeferred` interface is not stable for inheritance in 3rd party libraries**,
+ * **The `CompletableDeferred` interface is not stable for inheritance in 3rd party libraries**,
* as new methods might be added to this interface in the future, but is stable for use.
*/
public interface CompletableDeferred<T> : Deferred<T> {
@@ -57,7 +57,6 @@
* This function transitions this deferred in the same ways described by [CompletableDeferred.complete] and
* [CompletableDeferred.completeExceptionally].
*/
-@ExperimentalCoroutinesApi // since 1.3.2, tentatively until 1.4.0
public fun <T> CompletableDeferred<T>.completeWith(result: Result<T>): Boolean =
result.fold({ complete(it) }, { completeExceptionally(it) })
diff --git a/kotlinx-coroutines-core/common/src/CompletableJob.kt b/kotlinx-coroutines-core/common/src/CompletableJob.kt
index 8e6b1ab..74a92e3 100644
--- a/kotlinx-coroutines-core/common/src/CompletableJob.kt
+++ b/kotlinx-coroutines-core/common/src/CompletableJob.kt
@@ -11,7 +11,7 @@
* All functions on this interface are **thread-safe** and can
* be safely invoked from concurrent coroutines without external synchronization.
*
- * **`CompletableJob` interface is not stable for inheritance in 3rd party libraries**,
+ * **The `CompletableJob` interface is not stable for inheritance in 3rd party libraries**,
* as new methods might be added to this interface in the future, but is stable for use.
*/
public interface CompletableJob : Job {
diff --git a/kotlinx-coroutines-core/common/src/CompletedExceptionally.kt b/kotlinx-coroutines-core/common/src/CompletionState.kt
similarity index 77%
rename from kotlinx-coroutines-core/common/src/CompletedExceptionally.kt
rename to kotlinx-coroutines-core/common/src/CompletionState.kt
index b426785..f09aa3c 100644
--- a/kotlinx-coroutines-core/common/src/CompletedExceptionally.kt
+++ b/kotlinx-coroutines-core/common/src/CompletionState.kt
@@ -9,10 +9,17 @@
import kotlin.coroutines.*
import kotlin.jvm.*
-internal fun <T> Result<T>.toState(): Any? = fold({ it }, { CompletedExceptionally(it) })
+internal fun <T> Result<T>.toState(
+ onCancellation: ((cause: Throwable) -> Unit)? = null
+): Any? = fold(
+ onSuccess = { if (onCancellation != null) CompletedWithCancellation(it, onCancellation) else it },
+ onFailure = { CompletedExceptionally(it) }
+)
-internal fun <T> Result<T>.toState(caller: CancellableContinuation<*>): Any? = fold({ it },
- { CompletedExceptionally(recoverStackTrace(it, caller)) })
+internal fun <T> Result<T>.toState(caller: CancellableContinuation<*>): Any? = fold(
+ onSuccess = { it },
+ onFailure = { CompletedExceptionally(recoverStackTrace(it, caller)) }
+)
@Suppress("RESULT_CLASS_IN_RETURN_TYPE", "UNCHECKED_CAST")
internal fun <T> recoverResult(state: Any?, uCont: Continuation<T>): Result<T> =
@@ -21,6 +28,11 @@
else
Result.success(state as T)
+internal data class CompletedWithCancellation(
+ @JvmField val result: Any?,
+ @JvmField val onCancellation: (cause: Throwable) -> Unit
+)
+
/**
* Class for an internal state of a job that was cancelled (completed exceptionally).
*
diff --git a/kotlinx-coroutines-core/common/src/CoroutineDispatcher.kt b/kotlinx-coroutines-core/common/src/CoroutineDispatcher.kt
index 1b6e7eb..ab1e814 100644
--- a/kotlinx-coroutines-core/common/src/CoroutineDispatcher.kt
+++ b/kotlinx-coroutines-core/common/src/CoroutineDispatcher.kt
@@ -4,6 +4,7 @@
package kotlinx.coroutines
+import kotlinx.coroutines.internal.*
import kotlin.coroutines.*
/**
diff --git a/kotlinx-coroutines-core/common/src/CoroutineScope.kt b/kotlinx-coroutines-core/common/src/CoroutineScope.kt
index 7dbd6a6..0dde6c9 100644
--- a/kotlinx-coroutines-core/common/src/CoroutineScope.kt
+++ b/kotlinx-coroutines-core/common/src/CoroutineScope.kt
@@ -226,10 +226,10 @@
/**
* Ensures that current scope is [active][CoroutineScope.isActive].
- * Throws [IllegalStateException] if the context does not have a job in it.
*
* If the job is no longer active, throws [CancellationException].
* If the job was cancelled, thrown exception contains the original cancellation cause.
+ * This function does not do anything if there is no [Job] in the scope's [coroutineContext][CoroutineScope.coroutineContext].
*
* This method is a drop-in replacement for the following code, but with more precise exception:
* ```
@@ -237,6 +237,8 @@
* throw CancellationException()
* }
* ```
+ *
+ * @see CoroutineContext.ensureActive
*/
public fun CoroutineScope.ensureActive(): Unit = coroutineContext.ensureActive()
diff --git a/kotlinx-coroutines-core/common/src/CoroutineStart.kt b/kotlinx-coroutines-core/common/src/CoroutineStart.kt
index 05e80e3..d5791c7 100644
--- a/kotlinx-coroutines-core/common/src/CoroutineStart.kt
+++ b/kotlinx-coroutines-core/common/src/CoroutineStart.kt
@@ -55,7 +55,7 @@
* Cancellability of coroutine at suspension points depends on the particular implementation details of
* suspending functions as in [DEFAULT].
*/
- @ExperimentalCoroutinesApi
+ @ExperimentalCoroutinesApi // Since 1.0.0, no ETA on stability
ATOMIC,
/**
@@ -71,7 +71,7 @@
*
* **Note: This is an experimental api.** Execution semantics of coroutines may change in the future when this mode is used.
*/
- @ExperimentalCoroutinesApi
+ @ExperimentalCoroutinesApi // Since 1.0.0, no ETA on stability
UNDISPATCHED;
/**
diff --git a/kotlinx-coroutines-core/common/src/Debug.common.kt b/kotlinx-coroutines-core/common/src/Debug.common.kt
index 013b983..949b05c 100644
--- a/kotlinx-coroutines-core/common/src/Debug.common.kt
+++ b/kotlinx-coroutines-core/common/src/Debug.common.kt
@@ -27,7 +27,7 @@
* Copy mechanism is used only on JVM, but it might be convenient to implement it in common exceptions,
* so on JVM their stacktraces will be properly recovered.
*/
-@ExperimentalCoroutinesApi
+@ExperimentalCoroutinesApi // Since 1.2.0, no ETA on stability
public interface CopyableThrowable<T> where T : Throwable, T : CopyableThrowable<T> {
/**
diff --git a/kotlinx-coroutines-core/common/src/Deferred.kt b/kotlinx-coroutines-core/common/src/Deferred.kt
index 72f3fde..ff99675 100644
--- a/kotlinx-coroutines-core/common/src/Deferred.kt
+++ b/kotlinx-coroutines-core/common/src/Deferred.kt
@@ -43,6 +43,8 @@
* This suspending function is cancellable.
* If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function
* immediately resumes with [CancellationException].
+ * There is a **prompt cancellation guarantee**. If the job was cancelled while this function was
+ * suspended, it will not resume successfully. See [suspendCancellableCoroutine] documentation for low-level details.
*
* This function can be used in [select] invocation with [onAwait] clause.
* Use [isCompleted] to check for completion of this deferred value without waiting.
diff --git a/kotlinx-coroutines-core/common/src/Delay.kt b/kotlinx-coroutines-core/common/src/Delay.kt
index ab80912..aae623d 100644
--- a/kotlinx-coroutines-core/common/src/Delay.kt
+++ b/kotlinx-coroutines-core/common/src/Delay.kt
@@ -21,9 +21,12 @@
public interface Delay {
/**
* Delays coroutine for a given time without blocking a thread and resumes it after a specified time.
+ *
* This suspending function is cancellable.
* If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function
* immediately resumes with [CancellationException].
+ * There is a **prompt cancellation guarantee**. If the job was cancelled while this function was
+ * suspended, it will not resume successfully. See [suspendCancellableCoroutine] documentation for low-level details.
*/
public suspend fun delay(time: Long) {
if (time <= 0) return // don't delay
@@ -54,15 +57,56 @@
*
* This implementation uses a built-in single-threaded scheduled executor service.
*/
- public fun invokeOnTimeout(timeMillis: Long, block: Runnable): DisposableHandle =
- DefaultDelay.invokeOnTimeout(timeMillis, block)
+ public fun invokeOnTimeout(timeMillis: Long, block: Runnable, context: CoroutineContext): DisposableHandle =
+ DefaultDelay.invokeOnTimeout(timeMillis, block, context)
}
/**
+ * Suspends until cancellation, in which case it will throw a [CancellationException].
+ *
+ * This function returns [Nothing], so it can be used in any coroutine,
+ * regardless of the required return type.
+ *
+ * Usage example in callback adapting code:
+ *
+ * ```kotlin
+ * fun currentTemperature(): Flow<Temperature> = callbackFlow {
+ * val callback = SensorCallback { degreesCelsius: Double ->
+ * trySend(Temperature.celsius(degreesCelsius))
+ * }
+ * try {
+ * registerSensorCallback(callback)
+ * awaitCancellation() // Suspends to keep getting updates until cancellation.
+ * } finally {
+ * unregisterSensorCallback(callback)
+ * }
+ * }
+ * ```
+ *
+ * Usage example in (non declarative) UI code:
+ *
+ * ```kotlin
+ * suspend fun showStuffUntilCancelled(content: Stuff): Nothing {
+ * someSubView.text = content.title
+ * anotherSubView.text = content.description
+ * someView.visibleInScope {
+ * awaitCancellation() // Suspends so the view stays visible.
+ * }
+ * }
+ * ```
+ */
+public suspend fun awaitCancellation(): Nothing = suspendCancellableCoroutine {}
+
+/**
* Delays coroutine for a given time without blocking a thread and resumes it after a specified time.
+ *
* This suspending function is cancellable.
* If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function
* immediately resumes with [CancellationException].
+ * There is a **prompt cancellation guarantee**. If the job was cancelled while this function was
+ * suspended, it will not resume successfully. See [suspendCancellableCoroutine] documentation for low-level details.
+ *
+ * If you want to delay forever (until cancellation), consider using [awaitCancellation] instead.
*
* Note that delay can be used in [select] invocation with [onTimeout][SelectBuilder.onTimeout] clause.
*
@@ -72,15 +116,23 @@
public suspend fun delay(timeMillis: Long) {
if (timeMillis <= 0) return // don't delay
return suspendCancellableCoroutine sc@ { cont: CancellableContinuation<Unit> ->
- cont.context.delay.scheduleResumeAfterDelay(timeMillis, cont)
+ // if timeMillis == Long.MAX_VALUE then just wait forever like awaitCancellation, don't schedule.
+ if (timeMillis < Long.MAX_VALUE) {
+ cont.context.delay.scheduleResumeAfterDelay(timeMillis, cont)
+ }
}
}
/**
* Delays coroutine for a given [duration] without blocking a thread and resumes it after the specified time.
+ *
* This suspending function is cancellable.
* If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function
* immediately resumes with [CancellationException].
+ * There is a **prompt cancellation guarantee**. If the job was cancelled while this function was
+ * suspended, it will not resume successfully. See [suspendCancellableCoroutine] documentation for low-level details.
+ *
+ * If you want to delay forever (until cancellation), consider using [awaitCancellation] instead.
*
* Note that delay can be used in [select] invocation with [onTimeout][SelectBuilder.onTimeout] clause.
*
diff --git a/kotlinx-coroutines-core/common/src/Job.kt b/kotlinx-coroutines-core/common/src/Job.kt
index 754fa43..2e05635 100644
--- a/kotlinx-coroutines-core/common/src/Job.kt
+++ b/kotlinx-coroutines-core/common/src/Job.kt
@@ -635,6 +635,15 @@
public fun CoroutineContext.cancelChildren(): Unit = cancelChildren(null)
/**
+ * Retrieves the current [Job] instance from the given [CoroutineContext] or
+ * throws [IllegalStateException] if no job is present in the context.
+ *
+ * This method is a short-cut for `coroutineContext[Job]!!` and should be used only when it is known in advance that
+ * the context does have instance of the job in it.
+ */
+public val CoroutineContext.job: Job get() = get(Job) ?: error("Current context doesn't contain Job in it: $this")
+
+/**
* @suppress This method has bad semantics when cause is not a [CancellationException]. Use [CoroutineContext.cancelChildren].
*/
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
diff --git a/kotlinx-coroutines-core/common/src/Timeout.kt b/kotlinx-coroutines-core/common/src/Timeout.kt
index c8e4455..4bfff11 100644
--- a/kotlinx-coroutines-core/common/src/Timeout.kt
+++ b/kotlinx-coroutines-core/common/src/Timeout.kt
@@ -24,7 +24,14 @@
* The sibling function that does not throw an exception on timeout is [withTimeoutOrNull].
* Note that the timeout action can be specified for a [select] invocation with [onTimeout][SelectBuilder.onTimeout] clause.
*
- * Implementation note: how the time is tracked exactly is an implementation detail of the context's [CoroutineDispatcher].
+ * **The timeout event is asynchronous with respect to the code running in the block** and may happen at any time,
+ * 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.
+ * See the
+ * [Asynchronous timeout and resources][https://kotlinlang.org/docs/reference/coroutines/cancellation-and-timeouts.html#asynchronous-timeout-and-resources]
+ * section of the coroutines guide for details.
+ *
+ * > Implementation note: how the time is tracked exactly is an implementation detail of the context's [CoroutineDispatcher].
*
* @param timeMillis timeout time in milliseconds.
*/
@@ -48,7 +55,14 @@
* The sibling function that does not throw an exception on timeout is [withTimeoutOrNull].
* Note that the timeout action can be specified for a [select] invocation with [onTimeout][SelectBuilder.onTimeout] clause.
*
- * Implementation note: how the time is tracked exactly is an implementation detail of the context's [CoroutineDispatcher].
+ * **The timeout event is asynchronous with respect to the code running in the block** and may happen at any time,
+ * 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.
+ * See the
+ * [Asynchronous timeout and resources][https://kotlinlang.org/docs/reference/coroutines/cancellation-and-timeouts.html#asynchronous-timeout-and-resources]
+ * section of the coroutines guide for details.
+ *
+ * > Implementation note: how the time is tracked exactly is an implementation detail of the context's [CoroutineDispatcher].
*/
@ExperimentalTime
public suspend fun <T> withTimeout(timeout: Duration, block: suspend CoroutineScope.() -> T): T {
@@ -68,7 +82,14 @@
* The sibling function that throws an exception on timeout is [withTimeout].
* Note that the timeout action can be specified for a [select] invocation with [onTimeout][SelectBuilder.onTimeout] clause.
*
- * Implementation note: how the time is tracked exactly is an implementation detail of the context's [CoroutineDispatcher].
+ * **The timeout event is asynchronous with respect to the code running in the block** and may happen at any time,
+ * 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.
+ * See the
+ * [Asynchronous timeout and resources][https://kotlinlang.org/docs/reference/coroutines/cancellation-and-timeouts.html#asynchronous-timeout-and-resources]
+ * section of the coroutines guide for details.
+ *
+ * > Implementation note: how the time is tracked exactly is an implementation detail of the context's [CoroutineDispatcher].
*
* @param timeMillis timeout time in milliseconds.
*/
@@ -101,7 +122,14 @@
* The sibling function that throws an exception on timeout is [withTimeout].
* Note that the timeout action can be specified for a [select] invocation with [onTimeout][SelectBuilder.onTimeout] clause.
*
- * Implementation note: how the time is tracked exactly is an implementation detail of the context's [CoroutineDispatcher].
+ * **The timeout event is asynchronous with respect to the code running in the block** and may happen at any time,
+ * 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.
+ * See the
+ * [Asynchronous timeout and resources][https://kotlinlang.org/docs/reference/coroutines/cancellation-and-timeouts.html#asynchronous-timeout-and-resources]
+ * section of the coroutines guide for details.
+ *
+ * > Implementation note: how the time is tracked exactly is an implementation detail of the context's [CoroutineDispatcher].
*/
@ExperimentalTime
public suspend fun <T> withTimeoutOrNull(timeout: Duration, block: suspend CoroutineScope.() -> T): T? =
@@ -114,7 +142,7 @@
// schedule cancellation of this coroutine on time
val cont = coroutine.uCont
val context = cont.context
- coroutine.disposeOnCompletion(context.delay.invokeOnTimeout(coroutine.time, coroutine))
+ coroutine.disposeOnCompletion(context.delay.invokeOnTimeout(coroutine.time, coroutine, coroutine.context))
// restart the block using a new coroutine with a new job,
// however, start it undispatched, because we already are in the proper context
return coroutine.startUndispatchedOrReturnIgnoreTimeout(coroutine, block)
diff --git a/kotlinx-coroutines-core/common/src/Yield.kt b/kotlinx-coroutines-core/common/src/Yield.kt
index e0af04d..0d8bd3b 100644
--- a/kotlinx-coroutines-core/common/src/Yield.kt
+++ b/kotlinx-coroutines-core/common/src/Yield.kt
@@ -4,6 +4,7 @@
package kotlinx.coroutines
+import kotlinx.coroutines.internal.*
import kotlin.coroutines.*
import kotlin.coroutines.intrinsics.*
@@ -13,6 +14,8 @@
* This suspending function is cancellable.
* If the [Job] of the current coroutine is cancelled or completed when this suspending function is invoked or while
* this function is waiting for dispatch, it resumes with a [CancellationException].
+ * There is a **prompt cancellation guarantee**. If the job was cancelled while this function was
+ * suspended, it will not resume successfully. See [suspendCancellableCoroutine] documentation for low-level details.
*
* **Note**: This function always [checks for cancellation][ensureActive] even when it does not suspend.
*
diff --git a/kotlinx-coroutines-core/common/src/channels/AbstractChannel.kt b/kotlinx-coroutines-core/common/src/channels/AbstractChannel.kt
index 28c7cea..8edd2b3 100644
--- a/kotlinx-coroutines-core/common/src/channels/AbstractChannel.kt
+++ b/kotlinx-coroutines-core/common/src/channels/AbstractChannel.kt
@@ -16,7 +16,9 @@
/**
* Abstract send channel. It is a base class for all send channel implementations.
*/
-internal abstract class AbstractSendChannel<E> : SendChannel<E> {
+internal abstract class AbstractSendChannel<E>(
+ @JvmField protected val onUndeliveredElement: OnUndeliveredElement<E>?
+) : SendChannel<E> {
/** @suppress **This is unstable API and it is subject to change.** */
protected val queue = LockFreeLinkedListHead()
@@ -135,14 +137,6 @@
return sendSuspend(element)
}
- internal suspend fun sendFair(element: E) {
- if (offerInternal(element) === OFFER_SUCCESS) {
- yield() // Works only on fast path to properly work in sequential use-cases
- return
- }
- return sendSuspend(element)
- }
-
public final override fun offer(element: E): Boolean {
val result = offerInternal(element)
return when {
@@ -151,24 +145,34 @@
// We should check for closed token on offer as well, otherwise offer won't be linearizable
// in the face of concurrent close()
// See https://github.com/Kotlin/kotlinx.coroutines/issues/359
- throw recoverStackTrace(helpCloseAndGetSendException(closedForSend ?: return false))
+ throw recoverStackTrace(helpCloseAndGetSendException(element, closedForSend ?: return false))
}
- result is Closed<*> -> throw recoverStackTrace(helpCloseAndGetSendException(result))
+ result is Closed<*> -> {
+ throw recoverStackTrace(helpCloseAndGetSendException(element, result))
+ }
else -> error("offerInternal returned $result")
}
}
- private fun helpCloseAndGetSendException(closed: Closed<*>): Throwable {
+ private fun helpCloseAndGetSendException(element: E, closed: Closed<*>): Throwable {
// To ensure linearizablity we must ALWAYS help close the channel when we observe that it was closed
// See https://github.com/Kotlin/kotlinx.coroutines/issues/1419
helpClose(closed)
+ // Element was not delivered -> cals onUndeliveredElement
+ onUndeliveredElement?.callUndeliveredElementCatchingException(element)?.let {
+ // If it crashes, add send exception as suppressed for better diagnostics
+ it.addSuppressed(closed.sendException)
+ throw it
+ }
return closed.sendException
}
- private suspend fun sendSuspend(element: E): Unit = suspendAtomicCancellableCoroutineReusable sc@ { cont ->
+ private suspend fun sendSuspend(element: E): Unit = suspendCancellableCoroutineReusable sc@ { cont ->
loop@ while (true) {
if (isFullImpl) {
- val send = SendElement(element, cont)
+ val send = if (onUndeliveredElement == null)
+ SendElement(element, cont) else
+ SendElementWithUndeliveredHandler(element, cont, onUndeliveredElement)
val enqueueResult = enqueueSend(send)
when {
enqueueResult == null -> { // enqueued successfully
@@ -176,7 +180,7 @@
return@sc
}
enqueueResult is Closed<*> -> {
- cont.helpCloseAndResumeWithSendException(enqueueResult)
+ cont.helpCloseAndResumeWithSendException(element, enqueueResult)
return@sc
}
enqueueResult === ENQUEUE_FAILED -> {} // try to offer instead
@@ -193,7 +197,7 @@
}
offerResult === OFFER_FAILED -> continue@loop
offerResult is Closed<*> -> {
- cont.helpCloseAndResumeWithSendException(offerResult)
+ cont.helpCloseAndResumeWithSendException(element, offerResult)
return@sc
}
else -> error("offerInternal returned $offerResult")
@@ -201,9 +205,15 @@
}
}
- private fun Continuation<*>.helpCloseAndResumeWithSendException(closed: Closed<*>) {
+ private fun Continuation<*>.helpCloseAndResumeWithSendException(element: E, closed: Closed<*>) {
helpClose(closed)
- resumeWithException(closed.sendException)
+ val sendException = closed.sendException
+ onUndeliveredElement?.callUndeliveredElementCatchingException(element)?.let {
+ it.addSuppressed(sendException)
+ resumeWithException(it)
+ return
+ }
+ resumeWithException(sendException)
}
/**
@@ -375,7 +385,7 @@
select.disposeOnSelect(node)
return
}
- enqueueResult is Closed<*> -> throw recoverStackTrace(helpCloseAndGetSendException(enqueueResult))
+ enqueueResult is Closed<*> -> throw recoverStackTrace(helpCloseAndGetSendException(element, enqueueResult))
enqueueResult === ENQUEUE_FAILED -> {} // try to offer
enqueueResult is Receive<*> -> {} // try to offer
else -> error("enqueueSend returned $enqueueResult ")
@@ -391,7 +401,7 @@
block.startCoroutineUnintercepted(receiver = this, completion = select.completion)
return
}
- offerResult is Closed<*> -> throw recoverStackTrace(helpCloseAndGetSendException(offerResult))
+ offerResult is Closed<*> -> throw recoverStackTrace(helpCloseAndGetSendException(element, offerResult))
else -> error("offerSelectInternal returned $offerResult")
}
}
@@ -431,7 +441,7 @@
// ------ private ------
private class SendSelect<E, R>(
- override val pollResult: Any?,
+ override val pollResult: E, // E | Closed - the result pollInternal returns when it rendezvous with this node
@JvmField val channel: AbstractSendChannel<E>,
@JvmField val select: SelectInstance<R>,
@JvmField val block: suspend (SendChannel<E>) -> R
@@ -440,11 +450,13 @@
select.trySelectOther(otherOp) as Symbol? // must return symbol
override fun completeResumeSend() {
- block.startCoroutine(receiver = channel, completion = select.completion)
+ block.startCoroutineCancellable(receiver = channel, completion = select.completion)
}
override fun dispose() { // invoked on select completion
- remove()
+ if (!remove()) return
+ // if the node was successfully removed (meaning it was added but was not received) then element not delivered
+ undeliveredElement()
}
override fun resumeSendClosed(closed: Closed<*>) {
@@ -452,6 +464,10 @@
select.resumeSelectWithException(closed.sendException)
}
+ override fun undeliveredElement() {
+ channel.onUndeliveredElement?.callUndeliveredElement(pollResult, select.completion.context)
+ }
+
override fun toString(): String = "SendSelect@$hexAddress($pollResult)[$channel, $select]"
}
@@ -469,7 +485,9 @@
/**
* Abstract send/receive channel. It is a base class for all channel implementations.
*/
-internal abstract class AbstractChannel<E> : AbstractSendChannel<E>(), Channel<E> {
+internal abstract class AbstractChannel<E>(
+ onUndeliveredElement: OnUndeliveredElement<E>?
+) : AbstractSendChannel<E>(onUndeliveredElement), Channel<E> {
// ------ extension points for buffered channels ------
/**
@@ -501,6 +519,8 @@
send.completeResumeSend()
return send.pollResult
}
+ // too late, already cancelled, but we removed it from the queue and need to notify on undelivered element
+ send.undeliveredElement()
}
}
@@ -547,8 +567,10 @@
}
@Suppress("UNCHECKED_CAST")
- private suspend fun <R> receiveSuspend(receiveMode: Int): R = suspendAtomicCancellableCoroutineReusable sc@ { cont ->
- val receive = ReceiveElement<E>(cont as CancellableContinuation<Any?>, receiveMode)
+ private suspend fun <R> receiveSuspend(receiveMode: Int): R = suspendCancellableCoroutineReusable sc@ { cont ->
+ val receive = if (onUndeliveredElement == null)
+ ReceiveElement(cont as CancellableContinuation<Any?>, receiveMode) else
+ ReceiveElementWithUndeliveredHandler(cont as CancellableContinuation<Any?>, receiveMode, onUndeliveredElement)
while (true) {
if (enqueueReceive(receive)) {
removeReceiveOnCancel(cont, receive)
@@ -561,7 +583,7 @@
return@sc
}
if (result !== POLL_FAILED) {
- cont.resume(receive.resumeValue(result as E))
+ cont.resume(receive.resumeValue(result as E), receive.resumeOnCancellationFun(result as E))
return@sc
}
}
@@ -676,6 +698,11 @@
assert { token === RESUME_TOKEN }
return null
}
+
+ override fun onRemoved(affected: LockFreeLinkedListNode) {
+ // Called when we removed it from the queue but were too late to resume, so we have undelivered element
+ (affected as Send).undeliveredElement()
+ }
}
final override val onReceive: SelectClause1<E>
@@ -785,7 +812,7 @@
private fun removeReceiveOnCancel(cont: CancellableContinuation<*>, receive: Receive<*>) =
cont.invokeOnCancellation(handler = RemoveReceiveOnCancel(receive).asHandler)
- private inner class RemoveReceiveOnCancel(private val receive: Receive<*>) : CancelHandler() {
+ private inner class RemoveReceiveOnCancel(private val receive: Receive<*>) : BeforeResumeCancelHandler() {
override fun invoke(cause: Throwable?) {
if (receive.remove())
onReceiveDequeued()
@@ -793,7 +820,7 @@
override fun toString(): String = "RemoveReceiveOnCancel[$receive]"
}
- private class Itr<E>(val channel: AbstractChannel<E>) : ChannelIterator<E> {
+ private class Itr<E>(@JvmField val channel: AbstractChannel<E>) : ChannelIterator<E> {
var result: Any? = POLL_FAILED // E | POLL_FAILED | Closed
override suspend fun hasNext(): Boolean {
@@ -814,7 +841,7 @@
return true
}
- private suspend fun hasNextSuspend(): Boolean = suspendAtomicCancellableCoroutineReusable sc@ { cont ->
+ private suspend fun hasNextSuspend(): Boolean = suspendCancellableCoroutineReusable sc@ { cont ->
val receive = ReceiveHasNext(this, cont)
while (true) {
if (channel.enqueueReceive(receive)) {
@@ -832,7 +859,8 @@
return@sc
}
if (result !== POLL_FAILED) {
- cont.resume(true)
+ @Suppress("UNCHECKED_CAST")
+ cont.resume(true, channel.onUndeliveredElement?.bindCancellationFun(result as E, cont.context))
return@sc
}
}
@@ -851,7 +879,7 @@
}
}
- private class ReceiveElement<in E>(
+ private open class ReceiveElement<in E>(
@JvmField val cont: CancellableContinuation<Any?>,
@JvmField val receiveMode: Int
) : Receive<E>() {
@@ -860,9 +888,8 @@
else -> value
}
- @Suppress("IMPLICIT_CAST_TO_ANY")
override fun tryResumeReceive(value: E, otherOp: PrepareOp?): Symbol? {
- val token = cont.tryResume(resumeValue(value), otherOp?.desc) ?: return null
+ val token = cont.tryResume(resumeValue(value), otherOp?.desc, resumeOnCancellationFun(value)) ?: return null
assert { token === RESUME_TOKEN } // the only other possible result
// We can call finishPrepare only after successful tryResume, so that only good affected node is saved
otherOp?.finishPrepare()
@@ -881,12 +908,22 @@
override fun toString(): String = "ReceiveElement@$hexAddress[receiveMode=$receiveMode]"
}
- private class ReceiveHasNext<E>(
+ private class ReceiveElementWithUndeliveredHandler<in E>(
+ cont: CancellableContinuation<Any?>,
+ receiveMode: Int,
+ @JvmField val onUndeliveredElement: OnUndeliveredElement<E>
+ ) : ReceiveElement<E>(cont, receiveMode) {
+ override fun resumeOnCancellationFun(value: E): ((Throwable) -> Unit)? =
+ onUndeliveredElement.bindCancellationFun(value, cont.context)
+ }
+
+ private open class ReceiveHasNext<E>(
@JvmField val iterator: Itr<E>,
@JvmField val cont: CancellableContinuation<Boolean>
) : Receive<E>() {
override fun tryResumeReceive(value: E, otherOp: PrepareOp?): Symbol? {
- val token = cont.tryResume(true, otherOp?.desc) ?: return null
+ val token = cont.tryResume(true, otherOp?.desc, resumeOnCancellationFun(value))
+ ?: return null
assert { token === RESUME_TOKEN } // the only other possible result
// We can call finishPrepare only after successful tryResume, so that only good affected node is saved
otherOp?.finishPrepare()
@@ -906,13 +943,17 @@
val token = if (closed.closeCause == null) {
cont.tryResume(false)
} else {
- cont.tryResumeWithException(recoverStackTrace(closed.receiveException, cont))
+ cont.tryResumeWithException(closed.receiveException)
}
if (token != null) {
iterator.result = closed
cont.completeResume(token)
}
}
+
+ override fun resumeOnCancellationFun(value: E): ((Throwable) -> Unit)? =
+ iterator.channel.onUndeliveredElement?.bindCancellationFun(value, cont.context)
+
override fun toString(): String = "ReceiveHasNext@$hexAddress"
}
@@ -927,16 +968,20 @@
@Suppress("UNCHECKED_CAST")
override fun completeResumeReceive(value: E) {
- block.startCoroutine(if (receiveMode == RECEIVE_RESULT) ValueOrClosed.value(value) else value, select.completion)
+ block.startCoroutineCancellable(
+ if (receiveMode == RECEIVE_RESULT) ValueOrClosed.value(value) else value,
+ select.completion,
+ resumeOnCancellationFun(value)
+ )
}
override fun resumeReceiveClosed(closed: Closed<*>) {
if (!select.trySelect()) return
when (receiveMode) {
RECEIVE_THROWS_ON_CLOSE -> select.resumeSelectWithException(closed.receiveException)
- RECEIVE_RESULT -> block.startCoroutine(ValueOrClosed.closed<R>(closed.closeCause), select.completion)
+ RECEIVE_RESULT -> block.startCoroutineCancellable(ValueOrClosed.closed<R>(closed.closeCause), select.completion)
RECEIVE_NULL_ON_CLOSE -> if (closed.closeCause == null) {
- block.startCoroutine(null, select.completion)
+ block.startCoroutineCancellable(null, select.completion)
} else {
select.resumeSelectWithException(closed.receiveException)
}
@@ -948,6 +993,9 @@
channel.onReceiveDequeued() // notify cancellation of receive
}
+ override fun resumeOnCancellationFun(value: E): ((Throwable) -> Unit)? =
+ channel.onUndeliveredElement?.bindCancellationFun(value, select.completion.context)
+
override fun toString(): String = "ReceiveSelect@$hexAddress[$select,receiveMode=$receiveMode]"
}
}
@@ -959,23 +1007,27 @@
@JvmField
@SharedImmutable
-internal val OFFER_SUCCESS: Any = Symbol("OFFER_SUCCESS")
+internal val EMPTY = Symbol("EMPTY") // marker for Conflated & Buffered channels
@JvmField
@SharedImmutable
-internal val OFFER_FAILED: Any = Symbol("OFFER_FAILED")
+internal val OFFER_SUCCESS = Symbol("OFFER_SUCCESS")
@JvmField
@SharedImmutable
-internal val POLL_FAILED: Any = Symbol("POLL_FAILED")
+internal val OFFER_FAILED = Symbol("OFFER_FAILED")
@JvmField
@SharedImmutable
-internal val ENQUEUE_FAILED: Any = Symbol("ENQUEUE_FAILED")
+internal val POLL_FAILED = Symbol("POLL_FAILED")
@JvmField
@SharedImmutable
-internal val HANDLER_INVOKED: Any = Symbol("ON_CLOSE_HANDLER_INVOKED")
+internal val ENQUEUE_FAILED = Symbol("ENQUEUE_FAILED")
+
+@JvmField
+@SharedImmutable
+internal val HANDLER_INVOKED = Symbol("ON_CLOSE_HANDLER_INVOKED")
internal typealias Handler = (Throwable?) -> Unit
@@ -983,7 +1035,7 @@
* Represents sending waiter in the queue.
*/
internal abstract class Send : LockFreeLinkedListNode() {
- abstract val pollResult: Any? // E | Closed
+ abstract val pollResult: Any? // E | Closed - the result pollInternal returns when it rendezvous with this node
// Returns: null - failure,
// RETRY_ATOMIC for retry (only when otherOp != null),
// RESUME_TOKEN on success (call completeResumeSend)
@@ -991,6 +1043,7 @@
abstract fun tryResumeSend(otherOp: PrepareOp?): Symbol?
abstract fun completeResumeSend()
abstract fun resumeSendClosed(closed: Closed<*>)
+ open fun undeliveredElement() {}
}
/**
@@ -1009,9 +1062,8 @@
/**
* Represents sender for a specific element.
*/
-@Suppress("UNCHECKED_CAST")
-internal class SendElement(
- override val pollResult: Any?,
+internal open class SendElement<E>(
+ override val pollResult: E,
@JvmField val cont: CancellableContinuation<Unit>
) : Send() {
override fun tryResumeSend(otherOp: PrepareOp?): Symbol? {
@@ -1021,9 +1073,27 @@
otherOp?.finishPrepare() // finish preparations
return RESUME_TOKEN
}
+
override fun completeResumeSend() = cont.completeResume(RESUME_TOKEN)
override fun resumeSendClosed(closed: Closed<*>) = cont.resumeWithException(closed.sendException)
- override fun toString(): String = "SendElement@$hexAddress($pollResult)"
+ override fun toString(): String = "$classSimpleName@$hexAddress($pollResult)"
+}
+
+internal class SendElementWithUndeliveredHandler<E>(
+ pollResult: E,
+ cont: CancellableContinuation<Unit>,
+ @JvmField val onUndeliveredElement: OnUndeliveredElement<E>
+) : SendElement<E>(pollResult, cont) {
+ override fun remove(): Boolean {
+ if (!super.remove()) return false
+ // if the node was successfully removed (meaning it was added but was not received) then we have undelivered element
+ undeliveredElement()
+ return true
+ }
+
+ override fun undeliveredElement() {
+ onUndeliveredElement.callUndeliveredElement(pollResult, cont.context)
+ }
}
/**
@@ -1048,6 +1118,7 @@
internal abstract class Receive<in E> : LockFreeLinkedListNode(), ReceiveOrClosed<E> {
override val offerResult get() = OFFER_SUCCESS
abstract fun resumeReceiveClosed(closed: Closed<*>)
+ open fun resumeOnCancellationFun(value: E): ((Throwable) -> Unit)? = null
}
@Suppress("NOTHING_TO_INLINE", "UNCHECKED_CAST")
diff --git a/kotlinx-coroutines-core/common/src/channels/ArrayBroadcastChannel.kt b/kotlinx-coroutines-core/common/src/channels/ArrayBroadcastChannel.kt
index 155652f..91b5473 100644
--- a/kotlinx-coroutines-core/common/src/channels/ArrayBroadcastChannel.kt
+++ b/kotlinx-coroutines-core/common/src/channels/ArrayBroadcastChannel.kt
@@ -28,7 +28,7 @@
* Buffer capacity.
*/
val capacity: Int
-) : AbstractSendChannel<E>(), BroadcastChannel<E> {
+) : AbstractSendChannel<E>(null), BroadcastChannel<E> {
init {
require(capacity >= 1) { "ArrayBroadcastChannel capacity must be at least 1, but $capacity was specified" }
}
@@ -180,6 +180,8 @@
this.tail = tail + 1
return@withLock // go out of lock to wakeup this sender
}
+ // Too late, already cancelled, but we removed it from the queue and need to release resources.
+ // However, ArrayBroadcastChannel does not support onUndeliveredElement, so nothing to do
}
}
}
@@ -205,7 +207,7 @@
private class Subscriber<E>(
private val broadcastChannel: ArrayBroadcastChannel<E>
- ) : AbstractChannel<E>(), ReceiveChannel<E> {
+ ) : AbstractChannel<E>(null), ReceiveChannel<E> {
private val subLock = ReentrantLock()
private val _subHead = atomic(0L)
diff --git a/kotlinx-coroutines-core/common/src/channels/ArrayChannel.kt b/kotlinx-coroutines-core/common/src/channels/ArrayChannel.kt
index e26579e..80cb8aa 100644
--- a/kotlinx-coroutines-core/common/src/channels/ArrayChannel.kt
+++ b/kotlinx-coroutines-core/common/src/channels/ArrayChannel.kt
@@ -23,25 +23,31 @@
/**
* Buffer capacity.
*/
- val capacity: Int
-) : AbstractChannel<E>() {
+ private val capacity: Int,
+ private val onBufferOverflow: BufferOverflow,
+ onUndeliveredElement: OnUndeliveredElement<E>?
+) : AbstractChannel<E>(onUndeliveredElement) {
init {
+ // This check is actually used by the Channel(...) constructor function which checks only for known
+ // capacities and calls ArrayChannel constructor for everything else.
require(capacity >= 1) { "ArrayChannel capacity must be at least 1, but $capacity was specified" }
}
private val lock = ReentrantLock()
+
/*
* Guarded by lock.
* Allocate minimum of capacity and 16 to avoid excess memory pressure for large channels when it's not necessary.
*/
- private var buffer: Array<Any?> = arrayOfNulls<Any?>(min(capacity, 8))
+ private var buffer: Array<Any?> = arrayOfNulls<Any?>(min(capacity, 8)).apply { fill(EMPTY) }
+
private var head: Int = 0
private val size = atomic(0) // Invariant: size <= capacity
protected final override val isBufferAlwaysEmpty: Boolean get() = false
protected final override val isBufferEmpty: Boolean get() = size.value == 0
protected final override val isBufferAlwaysFull: Boolean get() = false
- protected final override val isBufferFull: Boolean get() = size.value == capacity
+ protected final override val isBufferFull: Boolean get() = size.value == capacity && onBufferOverflow == BufferOverflow.SUSPEND
override val isFull: Boolean get() = lock.withLock { isFullImpl }
override val isEmpty: Boolean get() = lock.withLock { isEmptyImpl }
@@ -53,31 +59,26 @@
lock.withLock {
val size = this.size.value
closedForSend?.let { return it }
- if (size < capacity) {
- // tentatively put element to buffer
- this.size.value = size + 1 // update size before checking queue (!!!)
- // check for receivers that were waiting on empty queue
- if (size == 0) {
- loop@ while (true) {
- receive = takeFirstReceiveOrPeekClosed() ?: break@loop // break when no receivers queued
- if (receive is Closed) {
- this.size.value = size // restore size
- return receive!!
- }
- val token = receive!!.tryResumeReceive(element, null)
- if (token != null) {
- assert { token === RESUME_TOKEN }
- this.size.value = size // restore size
- return@withLock
- }
+ // update size before checking queue (!!!)
+ updateBufferSize(size)?.let { return it }
+ // check for receivers that were waiting on empty queue
+ if (size == 0) {
+ loop@ while (true) {
+ receive = takeFirstReceiveOrPeekClosed() ?: break@loop // break when no receivers queued
+ if (receive is Closed) {
+ this.size.value = size // restore size
+ return receive!!
+ }
+ val token = receive!!.tryResumeReceive(element, null)
+ if (token != null) {
+ assert { token === RESUME_TOKEN }
+ this.size.value = size // restore size
+ return@withLock
}
}
- ensureCapacity(size)
- buffer[(head + size) % buffer.size] = element // actually queue element
- return OFFER_SUCCESS
}
- // size == capacity: full
- return OFFER_FAILED
+ enqueueElement(size, element)
+ return OFFER_SUCCESS
}
// breaks here if offer meets receiver
receive!!.completeResumeReceive(element)
@@ -90,41 +91,36 @@
lock.withLock {
val size = this.size.value
closedForSend?.let { return it }
- if (size < capacity) {
- // tentatively put element to buffer
- this.size.value = size + 1 // update size before checking queue (!!!)
- // check for receivers that were waiting on empty queue
- if (size == 0) {
- loop@ while (true) {
- val offerOp = describeTryOffer(element)
- val failure = select.performAtomicTrySelect(offerOp)
- when {
- failure == null -> { // offered successfully
- this.size.value = size // restore size
- receive = offerOp.result
- return@withLock
- }
- failure === OFFER_FAILED -> break@loop // cannot offer -> Ok to queue to buffer
- failure === RETRY_ATOMIC -> {} // retry
- failure === ALREADY_SELECTED || failure is Closed<*> -> {
- this.size.value = size // restore size
- return failure
- }
- else -> error("performAtomicTrySelect(describeTryOffer) returned $failure")
+ // update size before checking queue (!!!)
+ updateBufferSize(size)?.let { return it }
+ // check for receivers that were waiting on empty queue
+ if (size == 0) {
+ loop@ while (true) {
+ val offerOp = describeTryOffer(element)
+ val failure = select.performAtomicTrySelect(offerOp)
+ when {
+ failure == null -> { // offered successfully
+ this.size.value = size // restore size
+ receive = offerOp.result
+ return@withLock
}
+ failure === OFFER_FAILED -> break@loop // cannot offer -> Ok to queue to buffer
+ failure === RETRY_ATOMIC -> {} // retry
+ failure === ALREADY_SELECTED || failure is Closed<*> -> {
+ this.size.value = size // restore size
+ return failure
+ }
+ else -> error("performAtomicTrySelect(describeTryOffer) returned $failure")
}
}
- // let's try to select sending this element to buffer
- if (!select.trySelect()) { // :todo: move trySelect completion outside of lock
- this.size.value = size // restore size
- return ALREADY_SELECTED
- }
- ensureCapacity(size)
- buffer[(head + size) % buffer.size] = element // actually queue element
- return OFFER_SUCCESS
}
- // size == capacity: full
- return OFFER_FAILED
+ // let's try to select sending this element to buffer
+ if (!select.trySelect()) { // :todo: move trySelect completion outside of lock
+ this.size.value = size // restore size
+ return ALREADY_SELECTED
+ }
+ enqueueElement(size, element)
+ return OFFER_SUCCESS
}
// breaks here if offer meets receiver
receive!!.completeResumeReceive(element)
@@ -136,6 +132,35 @@
}
// Guarded by lock
+ // Result is `OFFER_SUCCESS | OFFER_FAILED | null`
+ private fun updateBufferSize(currentSize: Int): Symbol? {
+ if (currentSize < capacity) {
+ size.value = currentSize + 1 // tentatively put it into the buffer
+ return null // proceed
+ }
+ // buffer is full
+ return when (onBufferOverflow) {
+ BufferOverflow.SUSPEND -> OFFER_FAILED
+ BufferOverflow.DROP_LATEST -> OFFER_SUCCESS
+ BufferOverflow.DROP_OLDEST -> null // proceed, will drop oldest in enqueueElement
+ }
+ }
+
+ // Guarded by lock
+ private fun enqueueElement(currentSize: Int, element: E) {
+ if (currentSize < capacity) {
+ ensureCapacity(currentSize)
+ buffer[(head + currentSize) % buffer.size] = element // actually queue element
+ } else {
+ // buffer is full
+ assert { onBufferOverflow == BufferOverflow.DROP_OLDEST } // the only way we can get here
+ buffer[head % buffer.size] = null // drop oldest element
+ buffer[(head + currentSize) % buffer.size] = element // actually queue element
+ head = (head + 1) % buffer.size
+ }
+ }
+
+ // Guarded by lock
private fun ensureCapacity(currentSize: Int) {
if (currentSize >= buffer.size) {
val newSize = min(buffer.size * 2, capacity)
@@ -143,6 +168,7 @@
for (i in 0 until currentSize) {
newBuffer[i] = buffer[(head + i) % buffer.size]
}
+ newBuffer.fill(EMPTY, currentSize, newSize)
buffer = newBuffer
head = 0
}
@@ -172,6 +198,8 @@
replacement = send!!.pollResult
break@loop
}
+ // too late, already cancelled, but we removed it from the queue and need to notify on undelivered element
+ send!!.undeliveredElement()
}
}
if (replacement !== POLL_FAILED && replacement !is Closed<*>) {
@@ -254,17 +282,23 @@
// Note: this function is invoked when channel is already closed
override fun onCancelIdempotent(wasClosed: Boolean) {
// clear buffer first, but do not wait for it in helpers
- if (wasClosed) {
- lock.withLock {
- repeat(size.value) {
- buffer[head] = 0
- head = (head + 1) % buffer.size
+ val onUndeliveredElement = onUndeliveredElement
+ var undeliveredElementException: UndeliveredElementException? = null // first cancel exception, others suppressed
+ lock.withLock {
+ repeat(size.value) {
+ val value = buffer[head]
+ if (onUndeliveredElement != null && value !== EMPTY) {
+ @Suppress("UNCHECKED_CAST")
+ undeliveredElementException = onUndeliveredElement.callUndeliveredElementCatchingException(value as E, undeliveredElementException)
}
- size.value = 0
+ buffer[head] = EMPTY
+ head = (head + 1) % buffer.size
}
+ size.value = 0
}
// then clean all queued senders
super.onCancelIdempotent(wasClosed)
+ undeliveredElementException?.let { throw it } // throw cancel exception at the end if there was one
}
// ------ debug ------
diff --git a/kotlinx-coroutines-core/common/src/channels/Broadcast.kt b/kotlinx-coroutines-core/common/src/channels/Broadcast.kt
index 863d138..0193ed0 100644
--- a/kotlinx-coroutines-core/common/src/channels/Broadcast.kt
+++ b/kotlinx-coroutines-core/common/src/channels/Broadcast.kt
@@ -10,7 +10,6 @@
import kotlinx.coroutines.intrinsics.*
import kotlin.coroutines.*
import kotlin.coroutines.intrinsics.*
-import kotlin.native.concurrent.*
/**
* Broadcasts all elements of the channel.
@@ -34,8 +33,10 @@
*
* This function has an inappropriate result type of [BroadcastChannel] which provides
* [send][BroadcastChannel.send] and [close][BroadcastChannel.close] operations that interfere with
- * the broadcasting coroutine in hard-to-specify ways. It will be replaced with
- * sharing operators on [Flow][kotlinx.coroutines.flow.Flow] in the future.
+ * the broadcasting coroutine in hard-to-specify ways.
+ *
+ * **Note: This API is obsolete.** It will be deprecated and replaced with the
+ * [Flow.shareIn][kotlinx.coroutines.flow.shareIn] operator when it becomes stable.
*
* @param start coroutine start option. The default value is [CoroutineStart.LAZY].
*/
@@ -46,7 +47,7 @@
val scope = GlobalScope + Dispatchers.Unconfined + CoroutineExceptionHandler { _, _ -> }
// We can run this coroutine in the context that ignores all exceptions, because of `onCompletion = consume()`
// which passes all exceptions upstream to the source ReceiveChannel
- return scope.broadcast(capacity = capacity, start = start, onCompletion = consumes()) {
+ return scope.broadcast(capacity = capacity, start = start, onCompletion = { cancelConsumed(it) }) {
for (e in this@broadcast) {
send(e)
}
diff --git a/kotlinx-coroutines-core/common/src/channels/BroadcastChannel.kt b/kotlinx-coroutines-core/common/src/channels/BroadcastChannel.kt
index 312480f..d356566 100644
--- a/kotlinx-coroutines-core/common/src/channels/BroadcastChannel.kt
+++ b/kotlinx-coroutines-core/common/src/channels/BroadcastChannel.kt
@@ -7,9 +7,9 @@
package kotlinx.coroutines.channels
import kotlinx.coroutines.*
-import kotlinx.coroutines.channels.Channel.Factory.CONFLATED
import kotlinx.coroutines.channels.Channel.Factory.BUFFERED
import kotlinx.coroutines.channels.Channel.Factory.CHANNEL_DEFAULT_CAPACITY
+import kotlinx.coroutines.channels.Channel.Factory.CONFLATED
import kotlinx.coroutines.channels.Channel.Factory.UNLIMITED
/**
@@ -20,9 +20,10 @@
* See `BroadcastChannel()` factory function for the description of available
* broadcast channel implementations.
*
- * **Note: This is an experimental api.** It may be changed in the future updates.
+ * **Note: This API is obsolete.** It will be deprecated and replaced by [SharedFlow][kotlinx.coroutines.flow.SharedFlow]
+ * when it becomes stable.
*/
-@ExperimentalCoroutinesApi
+@ExperimentalCoroutinesApi // not @ObsoleteCoroutinesApi to reduce burden for people who are still using it
public interface BroadcastChannel<E> : SendChannel<E> {
/**
* Subscribes to this [BroadcastChannel] and returns a channel to receive elements from it.
diff --git a/kotlinx-coroutines-core/common/src/channels/BufferOverflow.kt b/kotlinx-coroutines-core/common/src/channels/BufferOverflow.kt
new file mode 100644
index 0000000..a89c633
--- /dev/null
+++ b/kotlinx-coroutines-core/common/src/channels/BufferOverflow.kt
@@ -0,0 +1,35 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.channels
+
+import kotlinx.coroutines.*
+
+/**
+ * A strategy for buffer overflow handling in [channels][Channel] and [flows][kotlinx.coroutines.flow.Flow] that
+ * controls what is going to be sacrificed on buffer overflow:
+ *
+ * * [SUSPEND] — the upstream that is [sending][SendChannel.send] or
+ * is [emitting][kotlinx.coroutines.flow.FlowCollector.emit] a value is **suspended** while the buffer is full.
+ * * [DROP_OLDEST] — drop **the oldest** value in the buffer on overflow, add the new value to the buffer, do not suspend.
+ * * [DROP_LATEST] — drop **the latest** value that is being added to the buffer right now on buffer overflow
+ * (so that buffer contents stay the same), do not suspend.
+ */
+public enum class BufferOverflow {
+ /**
+ * Suspend on buffer overflow.
+ */
+ SUSPEND,
+
+ /**
+ * Drop **the oldest** value in the buffer on overflow, add the new value to the buffer, do not suspend.
+ */
+ DROP_OLDEST,
+
+ /**
+ * Drop **the latest** value that is being added to the buffer right now on buffer overflow
+ * (so that buffer contents stay the same), do not suspend.
+ */
+ DROP_LATEST
+}
diff --git a/kotlinx-coroutines-core/common/src/channels/Channel.kt b/kotlinx-coroutines-core/common/src/channels/Channel.kt
index c4b4a9b..72c08e1 100644
--- a/kotlinx-coroutines-core/common/src/channels/Channel.kt
+++ b/kotlinx-coroutines-core/common/src/channels/Channel.kt
@@ -44,19 +44,17 @@
* Sends the specified [element] to this channel, suspending the caller while the buffer of this channel is full
* or if it does not exist, or throws an exception if the channel [is closed for `send`][isClosedForSend] (see [close] for details).
*
- * Note that closing a channel _after_ this function has suspended does not cause this suspended [send] invocation
+ * [Closing][close] a channel _after_ this function has suspended does not cause this suspended [send] invocation
* to abort, because closing a channel is conceptually like sending a special "close token" over this channel.
* All elements sent over the channel are delivered in first-in first-out order. The sent element
* will be delivered to receivers before the close token.
*
* This suspending function is cancellable. If the [Job] of the current coroutine is cancelled or completed while this
* function is suspended, this function immediately resumes with a [CancellationException].
- *
- * *Cancellation of suspended `send` is atomic*: when this function
- * throws a [CancellationException], it means that the [element] was not sent to this channel.
- * As a side-effect of atomic cancellation, a thread-bound coroutine (to some UI thread, for example) may
- * continue to execute even after it was cancelled from the same thread in the case when this `send` operation
- * was already resumed and the continuation was posted for execution to the thread's queue.
+ * There is a **prompt cancellation guarantee**. If the job was cancelled while this function was
+ * suspended, it will not resume successfully. The `send` call can send the element to the channel,
+ * but then throw [CancellationException], thus an exception should not be treated as a failure to deliver the element.
+ * See "Undelivered elements" section in [Channel] documentation for details on handling undelivered elements.
*
* Note that this function does not check for cancellation when it is not suspended.
* Use [yield] or [CoroutineScope.isActive] to periodically check for cancellation in tight loops if needed.
@@ -81,6 +79,11 @@
* in situations when `send` suspends.
*
* Throws an exception if the channel [is closed for `send`][isClosedForSend] (see [close] for details).
+ *
+ * When `offer` call returns `false` it guarantees that the element was not delivered to the consumer and it
+ * it does not call `onUndeliveredElement` that was installed for this channel. If the channel was closed,
+ * then it calls `onUndeliveredElement` before throwing an exception.
+ * See "Undelivered elements" section in [Channel] documentation for details on handling undelivered elements.
*/
public fun offer(element: E): Boolean
@@ -170,12 +173,10 @@
*
* This suspending function is cancellable. If the [Job] of the current coroutine is cancelled or completed while this
* function is suspended, this function immediately resumes with a [CancellationException].
- *
- * *Cancellation of suspended `receive` is atomic*: when this function
- * throws a [CancellationException], it means that the element was not retrieved from this channel.
- * As a side-effect of atomic cancellation, a thread-bound coroutine (to some UI thread, for example) may
- * continue to execute even after it was cancelled from the same thread in the case when this `receive` operation
- * was already resumed and the continuation was posted for execution to the thread's queue.
+ * There is a **prompt cancellation guarantee**. If the job was cancelled while this function was
+ * suspended, it will not resume successfully. The `receive` call can retrieve the element from the channel,
+ * but then throw [CancellationException], thus failing to deliver the element.
+ * See "Undelivered elements" section in [Channel] documentation for details on handling undelivered elements.
*
* Note that this function does not check for cancellation when it is not suspended.
* Use [yield] or [CoroutineScope.isActive] to periodically check for cancellation in tight loops if needed.
@@ -200,12 +201,10 @@
*
* This suspending function is cancellable. If the [Job] of the current coroutine is cancelled or completed while this
* function is suspended, this function immediately resumes with a [CancellationException].
- *
- * *Cancellation of suspended `receive` is atomic*: when this function
- * throws a [CancellationException], it means that the element was not retrieved from this channel.
- * As a side-effect of atomic cancellation, a thread-bound coroutine (to some UI thread, for example) may
- * continue to execute even after it was cancelled from the same thread in the case when this `receive` operation
- * was already resumed and the continuation was posted for execution to the thread's queue.
+ * There is a **prompt cancellation guarantee**. If the job was cancelled while this function was
+ * suspended, it will not resume successfully. The `receiveOrNull` call can retrieve the element from the channel,
+ * but then throw [CancellationException], thus failing to deliver the element.
+ * See "Undelivered elements" section in [Channel] documentation for details on handling undelivered elements.
*
* Note that this function does not check for cancellation when it is not suspended.
* Use [yield] or [CoroutineScope.isActive] to periodically check for cancellation in tight loops if needed.
@@ -250,12 +249,10 @@
*
* This suspending function is cancellable. If the [Job] of the current coroutine is cancelled or completed while this
* function is suspended, this function immediately resumes with a [CancellationException].
- *
- * *Cancellation of suspended `receive` is atomic*: when this function
- * throws a [CancellationException], it means that the element was not retrieved from this channel.
- * As a side-effect of atomic cancellation, a thread-bound coroutine (to some UI thread, for example) may
- * continue to execute even after it was cancelled from the same thread in the case when this receive operation
- * was already resumed and the continuation was posted for execution to the thread's queue.
+ * There is a **prompt cancellation guarantee**. If the job was cancelled while this function was
+ * suspended, it will not resume successfully. The `receiveOrClosed` call can retrieve the element from the channel,
+ * but then throw [CancellationException], thus failing to deliver the element.
+ * See "Undelivered elements" section in [Channel] documentation for details on handling undelivered elements.
*
* Note that this function does not check for cancellation when it is not suspended.
* Use [yield] or [CoroutineScope.isActive] to periodically check for cancellation in tight loops if needed.
@@ -332,7 +329,7 @@
* @suppress *This is an internal API, do not use*: Inline classes ABI is not stable yet and
* [KT-27524](https://youtrack.jetbrains.com/issue/KT-27524) needs to be fixed.
*/
-@Suppress("NON_PUBLIC_PRIMARY_CONSTRUCTOR_OF_INLINE_CLASS")
+@Suppress("NON_PUBLIC_PRIMARY_CONSTRUCTOR_OF_INLINE_CLASS", "EXPERIMENTAL_FEATURE_WARNING")
@InternalCoroutinesApi // until https://youtrack.jetbrains.com/issue/KT-27524 is fixed
public inline class ValueOrClosed<out T>
internal constructor(private val holder: Any?) {
@@ -439,12 +436,10 @@
*
* This suspending function is cancellable. If the [Job] of the current coroutine is cancelled or completed while this
* function is suspended, this function immediately resumes with a [CancellationException].
- *
- * *Cancellation of suspended `receive` is atomic*: when this function
- * throws a [CancellationException], it means that the element was not retrieved from this channel.
- * As a side-effect of atomic cancellation, a thread-bound coroutine (to some UI thread, for example) may
- * continue to execute even after it was cancelled from the same thread in the case when this receive operation
- * was already resumed and the continuation was posted for execution to the thread's queue.
+ * There is a **prompt cancellation guarantee**. If the job was cancelled while this function was
+ * suspended, it will not resume successfully. The `hasNext` call can retrieve the element from the channel,
+ * but then throw [CancellationException], thus failing to deliver the element.
+ * See "Undelivered elements" section in [Channel] documentation for details on handling undelivered elements.
*
* Note that this function does not check for cancellation when it is not suspended.
* Use [yield] or [CoroutineScope.isActive] to periodically check for cancellation in tight loops if needed.
@@ -486,28 +481,108 @@
* Conceptually, a channel is similar to Java's [BlockingQueue][java.util.concurrent.BlockingQueue],
* but it has suspending operations instead of blocking ones and can be [closed][SendChannel.close].
*
+ * ### Creating channels
+ *
* The `Channel(capacity)` factory function is used to create channels of different kinds depending on
* the value of the `capacity` integer:
*
- * * When `capacity` is 0 — it creates a `RendezvousChannel`.
+ * * When `capacity` is 0 — it creates a _rendezvous_ channel.
* This channel does not have any buffer at all. An element is transferred from the sender
* to the receiver only when [send] and [receive] invocations meet in time (rendezvous), so [send] suspends
* until another coroutine invokes [receive], and [receive] suspends until another coroutine invokes [send].
*
- * * When `capacity` is [Channel.UNLIMITED] — it creates a `LinkedListChannel`.
+ * * When `capacity` is [Channel.UNLIMITED] — it creates a channel with effectively unlimited buffer.
* This channel has a linked-list buffer of unlimited capacity (limited only by available memory).
* [Sending][send] to this channel never suspends, and [offer] always returns `true`.
*
- * * When `capacity` is [Channel.CONFLATED] — it creates a `ConflatedChannel`.
+ * * When `capacity` is [Channel.CONFLATED] — it creates a _conflated_ channel
* This channel buffers at most one element and conflates all subsequent `send` and `offer` invocations,
* so that the receiver always gets the last element sent.
- * Back-to-send sent elements are _conflated_ — only the last sent element is received,
+ * Back-to-send sent elements are conflated — only the last sent element is received,
* while previously sent elements **are lost**.
* [Sending][send] to this channel never suspends, and [offer] always returns `true`.
*
* * When `capacity` is positive but less than [UNLIMITED] — it creates an array-based channel with the specified capacity.
* This channel has an array buffer of a fixed `capacity`.
* [Sending][send] suspends only when the buffer is full, and [receiving][receive] suspends only when the buffer is empty.
+ *
+ * Buffered channels can be configured with an additional [`onBufferOverflow`][BufferOverflow] parameter. It controls the behaviour
+ * of the channel's [send][Channel.send] function on buffer overflow:
+ *
+ * * [SUSPEND][BufferOverflow.SUSPEND] — the default, suspend `send` on buffer overflow until there is
+ * free space in the buffer.
+ * * [DROP_OLDEST][BufferOverflow.DROP_OLDEST] — do not suspend the `send`, add the latest value to the buffer,
+ * drop the oldest one from the buffer.
+ * A channel with `capacity = 1` and `onBufferOverflow = DROP_OLDEST` is a _conflated_ channel.
+ * * [DROP_LATEST][BufferOverflow.DROP_LATEST] — do not suspend the `send`, drop the value that is being sent,
+ * keep the buffer contents intact.
+ *
+ * A non-default `onBufferOverflow` implicitly creates a channel with at least one buffered element and
+ * is ignored for a channel with unlimited buffer. It cannot be specified for `capacity = CONFLATED`, which
+ * is a shortcut by itself.
+ *
+ * ### Prompt cancellation guarantee
+ *
+ * All suspending functions with channels provide **prompt cancellation guarantee**.
+ * If the job was cancelled while send or receive function was suspended, it will not resume successfully,
+ * but throws a [CancellationException].
+ * With a single-threaded [dispatcher][CoroutineDispatcher] like [Dispatchers.Main] this gives a
+ * guarantee that if a piece code running in this thread cancels a [Job], then a coroutine running this job cannot
+ * resume successfully and continue to run, ensuring a prompt response to its cancellation.
+ *
+ * > **Prompt cancellation guarantee** for channel operations was added since `kotlinx.coroutines` version `1.4.0`
+ * > and had replaced a channel-specific atomic-cancellation that was not consistent with other suspending functions.
+ * > The low-level mechanics of prompt cancellation are explained in [suspendCancellableCoroutine] function.
+ *
+ * ### Undelivered elements
+ *
+ * As a result of a prompt cancellation guarantee, when a closeable resource
+ * (like open file or a handle to another native resource) is transferred via channel from one coroutine to another
+ * it can fail to be delivered and will be lost if either send or receive operations are cancelled in transit.
+ *
+ * A `Channel()` constructor function has an `onUndeliveredElement` optional parameter.
+ * When `onUndeliveredElement` parameter is set, the corresponding function is called once for each element
+ * that was sent to the channel with the call to the [send][SendChannel.send] function but failed to be delivered,
+ * which can happen in the following cases:
+ *
+ * * When [send][SendChannel.send] operation throws an exception because it was cancelled before it had a chance to actually
+ * send the element or because the channel was [closed][SendChannel.close] or [cancelled][ReceiveChannel.cancel].
+ * * When [offer][SendChannel.offer] operation throws an exception when
+ * the channel was [closed][SendChannel.close] or [cancelled][ReceiveChannel.cancel].
+ * * When [receive][ReceiveChannel.receive], [receiveOrNull][ReceiveChannel.receiveOrNull], or [hasNext][ChannelIterator.hasNext]
+ * operation throws an exception when it had retrieved the element from the
+ * channel but was cancelled before the code following the receive call resumed.
+ * * The channel was [cancelled][ReceiveChannel.cancel], in which case `onUndeliveredElement` is called on every
+ * remaining element in the channel's buffer.
+ *
+ * Note, that `onUndeliveredElement` function is called synchronously in an arbitrary context. It should be fast, non-blocking,
+ * and should not throw exceptions. Any exception thrown by `onUndeliveredElement` is wrapped into an internal runtime
+ * exception which is either rethrown from the caller method or handed off to the exception handler in the current context
+ * (see [CoroutineExceptionHandler]) when one is available.
+ *
+ * A typical usage for `onDeliveredElement` is to close a resource that is being transferred via the channel. The
+ * following code pattern guarantees that opened resources are closed even if producer, consumer, and/or channel
+ * are cancelled. Resources are never lost.
+ *
+ * ```
+ * // Create the channel with onUndeliveredElement block that closes a resource
+ * val channel = Channel<Resource>(capacity) { resource -> resource.close() }
+ *
+ * // Producer code
+ * val resourceToSend = openResource()
+ * channel.send(resourceToSend)
+ *
+ * // Consumer code
+ * val resourceReceived = channel.receive()
+ * try {
+ * // work with received resource
+ * } finally {
+ * resourceReceived.close()
+ * }
+ * ```
+ *
+ * > Note, that if you do any kind of work in between `openResource()` and `channel.send(...)`, then you should
+ * > ensure that resource gets closed in case this additional code fails.
*/
public interface Channel<E> : SendChannel<E>, ReceiveChannel<E> {
/**
@@ -515,25 +590,26 @@
*/
public companion object Factory {
/**
- * Requests a channel with an unlimited capacity buffer in the `Channel(...)` factory function
+ * Requests a channel with an unlimited capacity buffer in the `Channel(...)` factory function.
*/
public const val UNLIMITED: Int = Int.MAX_VALUE
/**
- * Requests a rendezvous channel in the `Channel(...)` factory function — a `RendezvousChannel` gets created.
+ * Requests a rendezvous channel in the `Channel(...)` factory function — a channel that does not have a buffer.
*/
public const val RENDEZVOUS: Int = 0
/**
- * Requests a conflated channel in the `Channel(...)` factory function — a `ConflatedChannel` gets created.
+ * Requests a conflated channel in the `Channel(...)` factory function. This is a shortcut to creating
+ * a channel with [`onBufferOverflow = DROP_OLDEST`][BufferOverflow.DROP_OLDEST].
*/
public const val CONFLATED: Int = -1
/**
- * Requests a buffered channel with the default buffer capacity in the `Channel(...)` factory function —
- * an `ArrayChannel` gets created with the default capacity.
- * The default capacity is 64 and can be overridden by setting
- * [DEFAULT_BUFFER_PROPERTY_NAME] on JVM.
+ * Requests a buffered channel with the default buffer capacity in the `Channel(...)` factory function.
+ * The default capacity for a channel that [suspends][BufferOverflow.SUSPEND] on overflow
+ * is 64 and can be overridden by setting [DEFAULT_BUFFER_PROPERTY_NAME] on JVM.
+ * For non-suspending channels, a buffer of capacity 1 is used.
*/
public const val BUFFERED: Int = -2
@@ -557,17 +633,48 @@
* See [Channel] interface documentation for details.
*
* @param capacity either a positive channel capacity or one of the constants defined in [Channel.Factory].
+ * @param onBufferOverflow configures an action on buffer overflow (optional, defaults to
+ * a [suspending][BufferOverflow.SUSPEND] attempt to [send][Channel.send] a value,
+ * supported only when `capacity >= 0` or `capacity == Channel.BUFFERED`,
+ * implicitly creates a channel with at least one buffered element).
+ * @param onUndeliveredElement an optional function that is called when element was sent but was not delivered to the consumer.
+ * See "Undelivered elements" section in [Channel] documentation.
* @throws IllegalArgumentException when [capacity] < -2
*/
-public fun <E> Channel(capacity: Int = RENDEZVOUS): Channel<E> =
+public fun <E> Channel(
+ capacity: Int = RENDEZVOUS,
+ onBufferOverflow: BufferOverflow = BufferOverflow.SUSPEND,
+ onUndeliveredElement: ((E) -> Unit)? = null
+): Channel<E> =
when (capacity) {
- RENDEZVOUS -> RendezvousChannel()
- UNLIMITED -> LinkedListChannel()
- CONFLATED -> ConflatedChannel()
- BUFFERED -> ArrayChannel(CHANNEL_DEFAULT_CAPACITY)
- else -> ArrayChannel(capacity)
+ RENDEZVOUS -> {
+ if (onBufferOverflow == BufferOverflow.SUSPEND)
+ RendezvousChannel(onUndeliveredElement) // an efficient implementation of rendezvous channel
+ else
+ ArrayChannel(1, onBufferOverflow, onUndeliveredElement) // support buffer overflow with buffered channel
+ }
+ CONFLATED -> {
+ require(onBufferOverflow == BufferOverflow.SUSPEND) {
+ "CONFLATED capacity cannot be used with non-default onBufferOverflow"
+ }
+ ConflatedChannel(onUndeliveredElement)
+ }
+ UNLIMITED -> LinkedListChannel(onUndeliveredElement) // ignores onBufferOverflow: it has buffer, but it never overflows
+ BUFFERED -> ArrayChannel( // uses default capacity with SUSPEND
+ if (onBufferOverflow == BufferOverflow.SUSPEND) CHANNEL_DEFAULT_CAPACITY else 1,
+ onBufferOverflow, onUndeliveredElement
+ )
+ else -> {
+ if (capacity == 1 && onBufferOverflow == BufferOverflow.DROP_OLDEST)
+ ConflatedChannel(onUndeliveredElement) // conflated implementation is more efficient but appears to work in the same way
+ else
+ ArrayChannel(capacity, onBufferOverflow, onUndeliveredElement)
+ }
}
+@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.4.0, binary compatibility with earlier versions")
+public fun <E> Channel(capacity: Int = RENDEZVOUS): Channel<E> = Channel(capacity)
+
/**
* Indicates an attempt to [send][SendChannel.send] to a [isClosedForSend][SendChannel.isClosedForSend] channel
* that was closed without a cause. A _failed_ channel rethrows the original [close][SendChannel.close] cause
diff --git a/kotlinx-coroutines-core/common/src/channels/ChannelCoroutine.kt b/kotlinx-coroutines-core/common/src/channels/ChannelCoroutine.kt
index 3f53b48..a75d466 100644
--- a/kotlinx-coroutines-core/common/src/channels/ChannelCoroutine.kt
+++ b/kotlinx-coroutines-core/common/src/channels/ChannelCoroutine.kt
@@ -34,9 +34,4 @@
_channel.cancel(exception) // cancel the channel
cancelCoroutine(exception) // cancel the job
}
-
- @Suppress("UNCHECKED_CAST")
- suspend fun sendFair(element: E) {
- (_channel as AbstractSendChannel<E>).sendFair(element)
- }
}
diff --git a/kotlinx-coroutines-core/common/src/channels/Channels.common.kt b/kotlinx-coroutines-core/common/src/channels/Channels.common.kt
index 8c61928..398d5ca 100644
--- a/kotlinx-coroutines-core/common/src/channels/Channels.common.kt
+++ b/kotlinx-coroutines-core/common/src/channels/Channels.common.kt
@@ -3,7 +3,7 @@
*/
@file:JvmMultifileClass
@file:JvmName("ChannelsKt")
-@file:Suppress("DEPRECATION")
+@file:Suppress("DEPRECATION_ERROR")
package kotlinx.coroutines.channels
@@ -40,12 +40,9 @@
*
* This suspending function is cancellable. If the [Job] of the current coroutine is cancelled or completed while this
* function is suspended, this function immediately resumes with [CancellationException].
- *
- * *Cancellation of suspended receive is atomic* -- when this function
- * throws [CancellationException] it means that the element was not retrieved from this channel.
- * As a side-effect of atomic cancellation, a thread-bound coroutine (to some UI thread, for example) may
- * continue to execute even after it was cancelled from the same thread in the case when this receive operation
- * was already resumed and the continuation was posted for execution to the thread's queue.
+ * There is a **prompt cancellation guarantee**. If the job was cancelled while this function was
+ * suspended, it will not resume successfully. If the `receiveOrNull` call threw [CancellationException] there is no way
+ * to tell if some element was already received from the channel or not. See [Channel] documentation for details.
*
* Note, that this function does not check for cancellation when it is not suspended.
* Use [yield] or [CoroutineScope.isActive] to periodically check for cancellation in tight loops if needed.
@@ -55,7 +52,7 @@
* to find bugs.
*/
@Suppress("EXTENSION_SHADOWED_BY_MEMBER")
-@ExperimentalCoroutinesApi // since 1.3.0, tentatively stable in 1.4.0
+@ExperimentalCoroutinesApi // since 1.3.0, tentatively stable in 1.4.x
public suspend fun <E : Any> ReceiveChannel<E>.receiveOrNull(): E? {
@Suppress("DEPRECATION", "UNCHECKED_CAST")
return (this as ReceiveChannel<E?>).receiveOrNull()
@@ -71,7 +68,7 @@
* these extensions do not accidentally confuse `null` value and a normally closed channel, leading to hard
* to find bugs.
**/
-@ExperimentalCoroutinesApi // since 1.3.0, tentatively stable in 1.4.0
+@ExperimentalCoroutinesApi // since 1.3.0, tentatively stable in 1.4.x
public fun <E : Any> ReceiveChannel<E>.onReceiveOrNull(): SelectClause1<E?> {
@Suppress("DEPRECATION", "UNCHECKED_CAST")
return (this as ReceiveChannel<E?>).onReceiveOrNull
@@ -105,8 +102,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public fun ReceiveChannel<*>.consumes(): CompletionHandler = { cause: Throwable? ->
cancelConsumed(cause)
@@ -128,8 +125,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public fun consumesAll(vararg channels: ReceiveChannel<*>): CompletionHandler =
{ cause: Throwable? ->
@@ -153,7 +150,6 @@
*
* The operation is _terminal_.
*/
-@ExperimentalCoroutinesApi // since 1.3.0, tentatively graduates in 1.4.0
public inline fun <E, R> ReceiveChannel<E>.consume(block: ReceiveChannel<E>.() -> R): R {
var cause: Throwable? = null
try {
@@ -174,7 +170,6 @@
* The operation is _terminal_.
* This function [consumes][ReceiveChannel.consume] all elements of the original [ReceiveChannel].
*/
-@ExperimentalCoroutinesApi // since 1.3.0, tentatively graduates in 1.4.0
public suspend inline fun <E> ReceiveChannel<E>.consumeEach(action: (E) -> Unit): Unit =
consume {
for (e in this) action(e)
@@ -190,8 +185,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E> ReceiveChannel<E>.consumeEachIndexed(action: (IndexedValue<E>) -> Unit) {
var index = 0
@@ -210,8 +205,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend fun <E> ReceiveChannel<E>.elementAt(index: Int): E =
elementAtOrElse(index) { throw IndexOutOfBoundsException("ReceiveChannel doesn't contain element at index $index.") }
@@ -226,8 +221,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E> ReceiveChannel<E>.elementAtOrElse(index: Int, defaultValue: (Int) -> E): E =
consume {
@@ -251,8 +246,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend fun <E> ReceiveChannel<E>.elementAtOrNull(index: Int): E? =
consume {
@@ -276,8 +271,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E> ReceiveChannel<E>.find(predicate: (E) -> Boolean): E? =
firstOrNull(predicate)
@@ -292,8 +287,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E> ReceiveChannel<E>.findLast(predicate: (E) -> Boolean): E? =
lastOrNull(predicate)
@@ -309,8 +304,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend fun <E> ReceiveChannel<E>.first(): E =
consume {
@@ -331,8 +326,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E> ReceiveChannel<E>.first(predicate: (E) -> Boolean): E {
consumeEach {
@@ -351,8 +346,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend fun <E> ReceiveChannel<E>.firstOrNull(): E? =
consume {
@@ -372,8 +367,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E> ReceiveChannel<E>.firstOrNull(predicate: (E) -> Boolean): E? {
consumeEach {
@@ -392,8 +387,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend fun <E> ReceiveChannel<E>.indexOf(element: E): Int {
var index = 0
@@ -415,8 +410,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E> ReceiveChannel<E>.indexOfFirst(predicate: (E) -> Boolean): Int {
var index = 0
@@ -438,8 +433,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E> ReceiveChannel<E>.indexOfLast(predicate: (E) -> Boolean): Int {
var lastIndex = -1
@@ -463,8 +458,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend fun <E> ReceiveChannel<E>.last(): E =
consume {
@@ -488,8 +483,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E> ReceiveChannel<E>.last(predicate: (E) -> Boolean): E {
var last: E? = null
@@ -515,8 +510,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend fun <E> ReceiveChannel<E>.lastIndexOf(element: E): Int {
var lastIndex = -1
@@ -539,8 +534,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend fun <E> ReceiveChannel<E>.lastOrNull(): E? =
consume {
@@ -563,8 +558,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E> ReceiveChannel<E>.lastOrNull(predicate: (E) -> Boolean): E? {
var last: E? = null
@@ -586,8 +581,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend fun <E> ReceiveChannel<E>.single(): E =
consume {
@@ -610,8 +605,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E> ReceiveChannel<E>.single(predicate: (E) -> Boolean): E {
var single: E? = null
@@ -638,8 +633,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend fun <E> ReceiveChannel<E>.singleOrNull(): E? =
consume {
@@ -662,8 +657,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E> ReceiveChannel<E>.singleOrNull(predicate: (E) -> Boolean): E? {
var single: E? = null
@@ -689,8 +684,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public fun <E> ReceiveChannel<E>.drop(n: Int, context: CoroutineContext = Dispatchers.Unconfined): ReceiveChannel<E> =
GlobalScope.produce(context, onCompletion = consumes()) {
@@ -717,8 +712,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public fun <E> ReceiveChannel<E>.dropWhile(context: CoroutineContext = Dispatchers.Unconfined, predicate: suspend (E) -> Boolean): ReceiveChannel<E> =
GlobalScope.produce(context, onCompletion = consumes()) {
@@ -743,8 +738,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public fun <E> ReceiveChannel<E>.filter(context: CoroutineContext = Dispatchers.Unconfined, predicate: suspend (E) -> Boolean): ReceiveChannel<E> =
GlobalScope.produce(context, onCompletion = consumes()) {
@@ -765,8 +760,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public fun <E> ReceiveChannel<E>.filterIndexed(context: CoroutineContext = Dispatchers.Unconfined, predicate: suspend (index: Int, E) -> Boolean): ReceiveChannel<E> =
GlobalScope.produce(context, onCompletion = consumes()) {
@@ -788,8 +783,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, C : MutableCollection<in E>> ReceiveChannel<E>.filterIndexedTo(destination: C, predicate: (index: Int, E) -> Boolean): C {
consumeEachIndexed { (index, element) ->
@@ -810,8 +805,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, C : SendChannel<E>> ReceiveChannel<E>.filterIndexedTo(destination: C, predicate: (index: Int, E) -> Boolean): C {
consumeEachIndexed { (index, element) ->
@@ -830,8 +825,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public fun <E> ReceiveChannel<E>.filterNot(context: CoroutineContext = Dispatchers.Unconfined, predicate: suspend (E) -> Boolean): ReceiveChannel<E> =
filter(context) { !predicate(it) }
@@ -846,8 +841,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
@Suppress("UNCHECKED_CAST")
public fun <E : Any> ReceiveChannel<E?>.filterNotNull(): ReceiveChannel<E> =
@@ -863,8 +858,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend fun <E : Any, C : MutableCollection<in E>> ReceiveChannel<E?>.filterNotNullTo(destination: C): C {
consumeEach {
@@ -883,8 +878,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend fun <E : Any, C : SendChannel<E>> ReceiveChannel<E?>.filterNotNullTo(destination: C): C {
consumeEach {
@@ -903,8 +898,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, C : MutableCollection<in E>> ReceiveChannel<E>.filterNotTo(destination: C, predicate: (E) -> Boolean): C {
consumeEach {
@@ -923,8 +918,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, C : SendChannel<E>> ReceiveChannel<E>.filterNotTo(destination: C, predicate: (E) -> Boolean): C {
consumeEach {
@@ -943,8 +938,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, C : MutableCollection<in E>> ReceiveChannel<E>.filterTo(destination: C, predicate: (E) -> Boolean): C {
consumeEach {
@@ -963,8 +958,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, C : SendChannel<E>> ReceiveChannel<E>.filterTo(destination: C, predicate: (E) -> Boolean): C {
consumeEach {
@@ -983,8 +978,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public fun <E> ReceiveChannel<E>.take(n: Int, context: CoroutineContext = Dispatchers.Unconfined): ReceiveChannel<E> =
GlobalScope.produce(context, onCompletion = consumes()) {
@@ -1009,8 +1004,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public fun <E> ReceiveChannel<E>.takeWhile(context: CoroutineContext = Dispatchers.Unconfined, predicate: suspend (E) -> Boolean): ReceiveChannel<E> =
GlobalScope.produce(context, onCompletion = consumes()) {
@@ -1035,8 +1030,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, K, V> ReceiveChannel<E>.associate(transform: (E) -> Pair<K, V>): Map<K, V> =
associateTo(LinkedHashMap(), transform)
@@ -1056,8 +1051,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, K> ReceiveChannel<E>.associateBy(keySelector: (E) -> K): Map<K, E> =
associateByTo(LinkedHashMap(), keySelector)
@@ -1076,8 +1071,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, K, V> ReceiveChannel<E>.associateBy(keySelector: (E) -> K, valueTransform: (E) -> V): Map<K, V> =
associateByTo(LinkedHashMap(), keySelector, valueTransform)
@@ -1096,8 +1091,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, K, M : MutableMap<in K, in E>> ReceiveChannel<E>.associateByTo(destination: M, keySelector: (E) -> K): M {
consumeEach {
@@ -1120,8 +1115,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, K, V, M : MutableMap<in K, in V>> ReceiveChannel<E>.associateByTo(destination: M, keySelector: (E) -> K, valueTransform: (E) -> V): M {
consumeEach {
@@ -1143,8 +1138,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, K, V, M : MutableMap<in K, in V>> ReceiveChannel<E>.associateTo(destination: M, transform: (E) -> Pair<K, V>): M {
consumeEach {
@@ -1164,8 +1159,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend fun <E, C : SendChannel<E>> ReceiveChannel<E>.toChannel(destination: C): C {
consumeEach {
@@ -1184,8 +1179,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend fun <E, C : MutableCollection<in E>> ReceiveChannel<E>.toCollection(destination: C): C {
consumeEach {
@@ -1213,8 +1208,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend fun <K, V> ReceiveChannel<Pair<K, V>>.toMap(): Map<K, V> =
toMap(LinkedHashMap())
@@ -1229,8 +1224,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend fun <K, V, M : MutableMap<in K, in V>> ReceiveChannel<Pair<K, V>>.toMap(destination: M): M {
consumeEach {
@@ -1249,8 +1244,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend fun <E> ReceiveChannel<E>.toMutableList(): MutableList<E> =
toCollection(ArrayList())
@@ -1267,8 +1262,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend fun <E> ReceiveChannel<E>.toSet(): Set<E> =
this.toMutableSet()
@@ -1283,8 +1278,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public fun <E, R> ReceiveChannel<E>.flatMap(context: CoroutineContext = Dispatchers.Unconfined, transform: suspend (E) -> ReceiveChannel<R>): ReceiveChannel<R> =
GlobalScope.produce(context, onCompletion = consumes()) {
@@ -1306,8 +1301,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, K> ReceiveChannel<E>.groupBy(keySelector: (E) -> K): Map<K, List<E>> =
groupByTo(LinkedHashMap(), keySelector)
@@ -1326,8 +1321,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, K, V> ReceiveChannel<E>.groupBy(keySelector: (E) -> K, valueTransform: (E) -> V): Map<K, List<V>> =
groupByTo(LinkedHashMap(), keySelector, valueTransform)
@@ -1345,8 +1340,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, K, M : MutableMap<in K, MutableList<E>>> ReceiveChannel<E>.groupByTo(destination: M, keySelector: (E) -> K): M {
consumeEach {
@@ -1371,8 +1366,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, K, V, M : MutableMap<in K, MutableList<V>>> ReceiveChannel<E>.groupByTo(destination: M, keySelector: (E) -> K, valueTransform: (E) -> V): M {
consumeEach {
@@ -1391,8 +1386,8 @@
* This function [consumes][ReceiveChannel.consume] all elements of the original [ReceiveChannel].
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public fun <E, R> ReceiveChannel<E>.map(context: CoroutineContext = Dispatchers.Unconfined, transform: suspend (E) -> R): ReceiveChannel<R> =
GlobalScope.produce(context, onCompletion = consumes()) {
@@ -1414,8 +1409,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public fun <E, R> ReceiveChannel<E>.mapIndexed(context: CoroutineContext = Dispatchers.Unconfined, transform: suspend (index: Int, E) -> R): ReceiveChannel<R> =
GlobalScope.produce(context, onCompletion = consumes()) {
@@ -1438,8 +1433,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public fun <E, R : Any> ReceiveChannel<E>.mapIndexedNotNull(context: CoroutineContext = Dispatchers.Unconfined, transform: suspend (index: Int, E) -> R?): ReceiveChannel<R> =
mapIndexed(context, transform).filterNotNull()
@@ -1457,8 +1452,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, R : Any, C : MutableCollection<in R>> ReceiveChannel<E>.mapIndexedNotNullTo(destination: C, transform: (index: Int, E) -> R?): C {
consumeEachIndexed { (index, element) ->
@@ -1480,8 +1475,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, R : Any, C : SendChannel<R>> ReceiveChannel<E>.mapIndexedNotNullTo(destination: C, transform: (index: Int, E) -> R?): C {
consumeEachIndexed { (index, element) ->
@@ -1503,8 +1498,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, R, C : MutableCollection<in R>> ReceiveChannel<E>.mapIndexedTo(destination: C, transform: (index: Int, E) -> R): C {
var index = 0
@@ -1527,8 +1522,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, R, C : SendChannel<R>> ReceiveChannel<E>.mapIndexedTo(destination: C, transform: (index: Int, E) -> R): C {
var index = 0
@@ -1549,8 +1544,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public fun <E, R : Any> ReceiveChannel<E>.mapNotNull(context: CoroutineContext = Dispatchers.Unconfined, transform: suspend (E) -> R?): ReceiveChannel<R> =
map(context, transform).filterNotNull()
@@ -1566,8 +1561,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, R : Any, C : MutableCollection<in R>> ReceiveChannel<E>.mapNotNullTo(destination: C, transform: (E) -> R?): C {
consumeEach {
@@ -1587,8 +1582,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, R : Any, C : SendChannel<R>> ReceiveChannel<E>.mapNotNullTo(destination: C, transform: (E) -> R?): C {
consumeEach {
@@ -1608,8 +1603,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, R, C : MutableCollection<in R>> ReceiveChannel<E>.mapTo(destination: C, transform: (E) -> R): C {
consumeEach {
@@ -1629,8 +1624,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, R, C : SendChannel<R>> ReceiveChannel<E>.mapTo(destination: C, transform: (E) -> R): C {
consumeEach {
@@ -1649,8 +1644,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public fun <E> ReceiveChannel<E>.withIndex(context: CoroutineContext = Dispatchers.Unconfined): ReceiveChannel<IndexedValue<E>> =
GlobalScope.produce(context, onCompletion = consumes()) {
@@ -1672,8 +1667,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public fun <E> ReceiveChannel<E>.distinct(): ReceiveChannel<E> =
this.distinctBy { it }
@@ -1691,8 +1686,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public fun <E, K> ReceiveChannel<E>.distinctBy(context: CoroutineContext = Dispatchers.Unconfined, selector: suspend (E) -> K): ReceiveChannel<E> =
GlobalScope.produce(context, onCompletion = consumes()) {
@@ -1718,8 +1713,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend fun <E> ReceiveChannel<E>.toMutableSet(): MutableSet<E> =
toCollection(LinkedHashSet())
@@ -1734,8 +1729,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E> ReceiveChannel<E>.all(predicate: (E) -> Boolean): Boolean {
consumeEach {
@@ -1754,8 +1749,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend fun <E> ReceiveChannel<E>.any(): Boolean =
consume {
@@ -1772,8 +1767,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E> ReceiveChannel<E>.any(predicate: (E) -> Boolean): Boolean {
consumeEach {
@@ -1792,8 +1787,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend fun <E> ReceiveChannel<E>.count(): Int {
var count = 0
@@ -1811,8 +1806,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E> ReceiveChannel<E>.count(predicate: (E) -> Boolean): Int {
var count = 0
@@ -1832,8 +1827,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, R> ReceiveChannel<E>.fold(initial: R, operation: (acc: R, E) -> R): R {
var accumulator = initial
@@ -1856,8 +1851,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, R> ReceiveChannel<E>.foldIndexed(initial: R, operation: (index: Int, acc: R, E) -> R): R {
var index = 0
@@ -1878,8 +1873,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, R : Comparable<R>> ReceiveChannel<E>.maxBy(selector: (E) -> R): E? =
consume {
@@ -1908,8 +1903,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend fun <E> ReceiveChannel<E>.maxWith(comparator: Comparator<in E>): E? =
consume {
@@ -1933,8 +1928,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E, R : Comparable<R>> ReceiveChannel<E>.minBy(selector: (E) -> R): E? =
consume {
@@ -1963,8 +1958,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend fun <E> ReceiveChannel<E>.minWith(comparator: Comparator<in E>): E? =
consume {
@@ -1988,8 +1983,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend fun <E> ReceiveChannel<E>.none(): Boolean =
consume {
@@ -2006,8 +2001,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E> ReceiveChannel<E>.none(predicate: (E) -> Boolean): Boolean {
consumeEach {
@@ -2026,8 +2021,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <S, E : S> ReceiveChannel<E>.reduce(operation: (acc: S, E) -> S): S =
consume {
@@ -2053,8 +2048,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <S, E : S> ReceiveChannel<E>.reduceIndexed(operation: (index: Int, acc: S, E) -> S): S =
consume {
@@ -2078,8 +2073,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E> ReceiveChannel<E>.sumBy(selector: (E) -> Int): Int {
var sum = 0
@@ -2099,8 +2094,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E> ReceiveChannel<E>.sumByDouble(selector: (E) -> Double): Double {
var sum = 0.0
@@ -2120,8 +2115,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public fun <E : Any> ReceiveChannel<E?>.requireNoNulls(): ReceiveChannel<E> =
map { it ?: throw IllegalArgumentException("null element found in $this.") }
@@ -2138,8 +2133,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public suspend inline fun <E> ReceiveChannel<E>.partition(predicate: (E) -> Boolean): Pair<List<E>, List<E>> {
val first = ArrayList<E>()
@@ -2165,8 +2160,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public infix fun <E, R> ReceiveChannel<E>.zip(other: ReceiveChannel<R>): ReceiveChannel<Pair<E, R>> =
zip(other) { t1, t2 -> t1 to t2 }
@@ -2181,8 +2176,8 @@
* See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
*/
@Deprecated(
- message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4",
- level = DeprecationLevel.WARNING
+ message = "Channel operators are deprecated in favour of Flow and will be removed in 1.4.x",
+ level = DeprecationLevel.ERROR
)
public fun <E, R, V> ReceiveChannel<E>.zip(other: ReceiveChannel<R>, context: CoroutineContext = Dispatchers.Unconfined, transform: (a: E, b: R) -> V): ReceiveChannel<V> =
GlobalScope.produce(context, onCompletion = consumesAll(this, other)) {
diff --git a/kotlinx-coroutines-core/common/src/channels/ConflatedBroadcastChannel.kt b/kotlinx-coroutines-core/common/src/channels/ConflatedBroadcastChannel.kt
index 2b9375d..5986dae 100644
--- a/kotlinx-coroutines-core/common/src/channels/ConflatedBroadcastChannel.kt
+++ b/kotlinx-coroutines-core/common/src/channels/ConflatedBroadcastChannel.kt
@@ -10,7 +10,6 @@
import kotlinx.coroutines.intrinsics.*
import kotlinx.coroutines.selects.*
import kotlin.jvm.*
-import kotlin.native.concurrent.*
/**
* Broadcasts the most recently sent element (aka [value]) to all [openSubscription] subscribers.
@@ -27,9 +26,10 @@
* [opening][openSubscription] and [closing][ReceiveChannel.cancel] subscription takes O(N) time, where N is the
* number of subscribers.
*
- * **Note: This API is experimental.** It may be changed in the future updates.
+ * **Note: This API is obsolete.** It will be deprecated and replaced by [StateFlow][kotlinx.coroutines.flow.StateFlow]
+ * when it becomes stable.
*/
-@ExperimentalCoroutinesApi
+@ExperimentalCoroutinesApi // not @ObsoleteCoroutinesApi to reduce burden for people who are still using it
public class ConflatedBroadcastChannel<E>() : BroadcastChannel<E> {
/**
* Creates an instance of this class that already holds a value.
@@ -282,7 +282,7 @@
private class Subscriber<E>(
private val broadcastChannel: ConflatedBroadcastChannel<E>
- ) : ConflatedChannel<E>(), ReceiveChannel<E> {
+ ) : ConflatedChannel<E>(null), ReceiveChannel<E> {
override fun onCancelIdempotent(wasClosed: Boolean) {
if (wasClosed) {
diff --git a/kotlinx-coroutines-core/common/src/channels/ConflatedChannel.kt b/kotlinx-coroutines-core/common/src/channels/ConflatedChannel.kt
index 4734766..75e421c 100644
--- a/kotlinx-coroutines-core/common/src/channels/ConflatedChannel.kt
+++ b/kotlinx-coroutines-core/common/src/channels/ConflatedChannel.kt
@@ -7,7 +7,6 @@
import kotlinx.coroutines.*
import kotlinx.coroutines.internal.*
import kotlinx.coroutines.selects.*
-import kotlin.native.concurrent.*
/**
* Channel that buffers at most one element and conflates all subsequent `send` and `offer` invocations,
@@ -18,7 +17,7 @@
*
* This channel is created by `Channel(Channel.CONFLATED)` factory function invocation.
*/
-internal open class ConflatedChannel<E> : AbstractChannel<E>() {
+internal open class ConflatedChannel<E>(onUndeliveredElement: OnUndeliveredElement<E>?) : AbstractChannel<E>(onUndeliveredElement) {
protected final override val isBufferAlwaysEmpty: Boolean get() = false
protected final override val isBufferEmpty: Boolean get() = value === EMPTY
protected final override val isBufferAlwaysFull: Boolean get() = false
@@ -30,10 +29,6 @@
private var value: Any? = EMPTY
- private companion object {
- private val EMPTY = Symbol("EMPTY")
- }
-
// result is `OFFER_SUCCESS | Closed`
protected override fun offerInternal(element: E): Any {
var receive: ReceiveOrClosed<E>? = null
@@ -54,7 +49,7 @@
}
}
}
- value = element
+ updateValueLocked(element)?.let { throw it }
return OFFER_SUCCESS
}
// breaks here if offer meets receiver
@@ -87,7 +82,7 @@
if (!select.trySelect()) {
return ALREADY_SELECTED
}
- value = element
+ updateValueLocked(element)?.let { throw it }
return OFFER_SUCCESS
}
// breaks here if offer meets receiver
@@ -120,12 +115,20 @@
}
protected override fun onCancelIdempotent(wasClosed: Boolean) {
- if (wasClosed) {
- lock.withLock {
- value = EMPTY
- }
+ var undeliveredElementException: UndeliveredElementException? = null // resource cancel exception
+ lock.withLock {
+ undeliveredElementException = updateValueLocked(EMPTY)
}
super.onCancelIdempotent(wasClosed)
+ undeliveredElementException?.let { throw it } // throw exception at the end if there was one
+ }
+
+ private fun updateValueLocked(element: Any?): UndeliveredElementException? {
+ val old = value
+ val undeliveredElementException = if (old === EMPTY) null else
+ onUndeliveredElement?.callUndeliveredElementCatchingException(old as E)
+ value = element
+ return undeliveredElementException
}
override fun enqueueReceiveInternal(receive: Receive<E>): Boolean = lock.withLock {
diff --git a/kotlinx-coroutines-core/common/src/channels/LinkedListChannel.kt b/kotlinx-coroutines-core/common/src/channels/LinkedListChannel.kt
index e66bbb2..2f46421 100644
--- a/kotlinx-coroutines-core/common/src/channels/LinkedListChannel.kt
+++ b/kotlinx-coroutines-core/common/src/channels/LinkedListChannel.kt
@@ -17,7 +17,7 @@
*
* @suppress **This an internal API and should not be used from general code.**
*/
-internal open class LinkedListChannel<E> : AbstractChannel<E>() {
+internal open class LinkedListChannel<E>(onUndeliveredElement: OnUndeliveredElement<E>?) : AbstractChannel<E>(onUndeliveredElement) {
protected final override val isBufferAlwaysEmpty: Boolean get() = true
protected final override val isBufferEmpty: Boolean get() = true
protected final override val isBufferAlwaysFull: Boolean get() = false
diff --git a/kotlinx-coroutines-core/common/src/channels/Produce.kt b/kotlinx-coroutines-core/common/src/channels/Produce.kt
index 1b1581a..10a15e2 100644
--- a/kotlinx-coroutines-core/common/src/channels/Produce.kt
+++ b/kotlinx-coroutines-core/common/src/channels/Produce.kt
@@ -27,7 +27,11 @@
/**
* Suspends the current coroutine until the channel is either [closed][SendChannel.close] or [cancelled][ReceiveChannel.cancel]
- * and invokes the given [block] before resuming the coroutine. This suspending function is cancellable.
+ * and invokes the given [block] before resuming the coroutine.
+ *
+ * This suspending function is cancellable.
+ * There is a **prompt cancellation guarantee**. If the job was cancelled while this function was
+ * suspended, it will not resume successfully. See [suspendCancellableCoroutine] documentation for low-level details.
*
* Note that when the producer channel is cancelled, this function resumes with a cancellation exception.
* Therefore, in case of cancellation, no code after the call to this function will be executed.
@@ -91,13 +95,8 @@
context: CoroutineContext = EmptyCoroutineContext,
capacity: Int = 0,
@BuilderInference block: suspend ProducerScope<E>.() -> Unit
-): ReceiveChannel<E> {
- val channel = Channel<E>(capacity)
- val newContext = newCoroutineContext(context)
- val coroutine = ProducerCoroutine(newContext, channel)
- coroutine.start(CoroutineStart.DEFAULT, coroutine, block)
- return coroutine
-}
+): ReceiveChannel<E> =
+ produce(context, capacity, BufferOverflow.SUSPEND, CoroutineStart.DEFAULT, onCompletion = null, block = block)
/**
* **This is an internal API and should not be used from general code.**
@@ -118,8 +117,19 @@
start: CoroutineStart = CoroutineStart.DEFAULT,
onCompletion: CompletionHandler? = null,
@BuilderInference block: suspend ProducerScope<E>.() -> Unit
+): ReceiveChannel<E> =
+ produce(context, capacity, BufferOverflow.SUSPEND, start, onCompletion, block)
+
+// Internal version of produce that is maximally flexible, but is not exposed through public API (too many params)
+internal fun <E> CoroutineScope.produce(
+ context: CoroutineContext = EmptyCoroutineContext,
+ capacity: Int = 0,
+ onBufferOverflow: BufferOverflow = BufferOverflow.SUSPEND,
+ start: CoroutineStart = CoroutineStart.DEFAULT,
+ onCompletion: CompletionHandler? = null,
+ @BuilderInference block: suspend ProducerScope<E>.() -> Unit
): ReceiveChannel<E> {
- val channel = Channel<E>(capacity)
+ val channel = Channel<E>(capacity, onBufferOverflow)
val newContext = newCoroutineContext(context)
val coroutine = ProducerCoroutine(newContext, channel)
if (onCompletion != null) coroutine.invokeOnCompletion(handler = onCompletion)
diff --git a/kotlinx-coroutines-core/common/src/channels/RendezvousChannel.kt b/kotlinx-coroutines-core/common/src/channels/RendezvousChannel.kt
index 700f509..857a979 100644
--- a/kotlinx-coroutines-core/common/src/channels/RendezvousChannel.kt
+++ b/kotlinx-coroutines-core/common/src/channels/RendezvousChannel.kt
@@ -4,6 +4,8 @@
package kotlinx.coroutines.channels
+import kotlinx.coroutines.internal.*
+
/**
* Rendezvous channel. This channel does not have any buffer at all. An element is transferred from sender
* to receiver only when [send] and [receive] invocations meet in time (rendezvous), so [send] suspends
@@ -13,7 +15,7 @@
*
* This implementation is fully lock-free.
**/
-internal open class RendezvousChannel<E> : AbstractChannel<E>() {
+internal open class RendezvousChannel<E>(onUndeliveredElement: OnUndeliveredElement<E>?) : AbstractChannel<E>(onUndeliveredElement) {
protected final override val isBufferAlwaysEmpty: Boolean get() = true
protected final override val isBufferEmpty: Boolean get() = true
protected final override val isBufferAlwaysFull: Boolean get() = true
diff --git a/kotlinx-coroutines-core/common/src/flow/Builders.kt b/kotlinx-coroutines-core/common/src/flow/Builders.kt
index 8fd9ae7..7d84cd2 100644
--- a/kotlinx-coroutines-core/common/src/flow/Builders.kt
+++ b/kotlinx-coroutines-core/common/src/flow/Builders.kt
@@ -16,7 +16,8 @@
import kotlinx.coroutines.flow.internal.unsafeFlow as flow
/**
- * Creates a flow from the given suspendable [block].
+ * Creates a _cold_ flow from the given suspendable [block].
+ * The flow being _cold_ means that the [block] is called every time a terminal operator is applied to the resulting flow.
*
* Example of usage:
*
@@ -62,7 +63,7 @@
}
/**
- * Creates a flow that produces a single value from the given functional type.
+ * Creates a _cold_ flow that produces a single value from the given functional type.
*/
@FlowPreview
public fun <T> (() -> T).asFlow(): Flow<T> = flow {
@@ -70,8 +71,10 @@
}
/**
- * Creates a flow that produces a single value from the given functional type.
+ * Creates a _cold_ flow that produces a single value from the given functional type.
+ *
* Example of usage:
+ *
* ```
* suspend fun remoteCall(): R = ...
* fun remoteCallFlow(): Flow<R> = ::remoteCall.asFlow()
@@ -83,7 +86,7 @@
}
/**
- * Creates a flow that produces values from the given iterable.
+ * Creates a _cold_ flow that produces values from the given iterable.
*/
public fun <T> Iterable<T>.asFlow(): Flow<T> = flow {
forEach { value ->
@@ -92,7 +95,7 @@
}
/**
- * Creates a flow that produces values from the given iterator.
+ * Creates a _cold_ flow that produces values from the given iterator.
*/
public fun <T> Iterator<T>.asFlow(): Flow<T> = flow {
forEach { value ->
@@ -101,7 +104,7 @@
}
/**
- * Creates a flow that produces values from the given sequence.
+ * Creates a _cold_ flow that produces values from the given sequence.
*/
public fun <T> Sequence<T>.asFlow(): Flow<T> = flow {
forEach { value ->
@@ -113,6 +116,7 @@
* Creates a flow that produces values from the specified `vararg`-arguments.
*
* Example of usage:
+ *
* ```
* flowOf(1, 2, 3)
* ```
@@ -124,7 +128,7 @@
}
/**
- * Creates flow that produces the given [value].
+ * Creates a flow that produces the given [value].
*/
public fun <T> flowOf(value: T): Flow<T> = flow {
/*
@@ -144,7 +148,9 @@
}
/**
- * Creates a flow that produces values from the given array.
+ * Creates a _cold_ flow that produces values from the given array.
+ * The flow being _cold_ means that the array components are read every time a terminal operator is applied
+ * to the resulting flow.
*/
public fun <T> Array<T>.asFlow(): Flow<T> = flow {
forEach { value ->
@@ -153,7 +159,9 @@
}
/**
- * Creates a flow that produces values from the array.
+ * Creates a _cold_ flow that produces values from the array.
+ * The flow being _cold_ means that the array components are read every time a terminal operator is applied
+ * to the resulting flow.
*/
public fun IntArray.asFlow(): Flow<Int> = flow {
forEach { value ->
@@ -162,7 +170,9 @@
}
/**
- * Creates a flow that produces values from the array.
+ * Creates a _cold_ flow that produces values from the given array.
+ * The flow being _cold_ means that the array components are read every time a terminal operator is applied
+ * to the resulting flow.
*/
public fun LongArray.asFlow(): Flow<Long> = flow {
forEach { value ->
@@ -194,8 +204,8 @@
@FlowPreview
@Deprecated(
message = "Use channelFlow with awaitClose { } instead of flowViaChannel and invokeOnClose { }.",
- level = DeprecationLevel.WARNING
-)
+ level = DeprecationLevel.ERROR
+) // To be removed in 1.4.x
@Suppress("DeprecatedCallableAddReplaceWith")
public fun <T> flowViaChannel(
bufferSize: Int = BUFFERED,
@@ -208,7 +218,7 @@
}
/**
- * Creates an instance of the cold [Flow] with elements that are sent to a [SendChannel]
+ * Creates an instance of a _cold_ [Flow] with elements that are sent to a [SendChannel]
* provided to the builder's [block] of code via [ProducerScope]. It allows elements to be
* produced by code that is running in a different context or concurrently.
* The resulting flow is _cold_, which means that [block] is called every time a terminal operator
@@ -256,7 +266,7 @@
ChannelFlowBuilder(block)
/**
- * Creates an instance of the cold [Flow] with elements that are sent to a [SendChannel]
+ * Creates an instance of a _cold_ [Flow] with elements that are sent to a [SendChannel]
* provided to the builder's [block] of code via [ProducerScope]. It allows elements to be
* produced by code that is running in a different context or concurrently.
*
@@ -283,11 +293,12 @@
* Adjacent applications of [callbackFlow], [flowOn], [buffer], [produceIn], and [broadcastIn] are
* always fused so that only one properly configured channel is used for execution.
*
- * Example of usage:
+ * Example of usage that converts a multi-short callback API to a flow.
+ * For single-shot callbacks use [suspendCancellableCoroutine].
*
* ```
* fun flowFrom(api: CallbackBasedApi): Flow<T> = callbackFlow {
- * val callback = object : Callback { // implementation of some callback interface
+ * val callback = object : Callback { // Implementation of some callback interface
* override fun onNextValue(value: T) {
* // To avoid blocking you can configure channel capacity using
* // either buffer(Channel.CONFLATED) or buffer(Channel.UNLIMITED) to avoid overfill
@@ -311,6 +322,10 @@
* awaitClose { api.unregister(callback) }
* }
* ```
+ *
+ * > The callback `register`/`unregister` methods provided by an external API must be thread-safe, because
+ * > `awaitClose` block can be called at any time due to asynchronous nature of cancellation, even
+ * > concurrently with the call of the callback.
*/
@ExperimentalCoroutinesApi
public fun <T> callbackFlow(@BuilderInference block: suspend ProducerScope<T>.() -> Unit): Flow<T> = CallbackFlowBuilder(block)
@@ -319,10 +334,11 @@
private open class ChannelFlowBuilder<T>(
private val block: suspend ProducerScope<T>.() -> Unit,
context: CoroutineContext = EmptyCoroutineContext,
- capacity: Int = BUFFERED
-) : ChannelFlow<T>(context, capacity) {
- override fun create(context: CoroutineContext, capacity: Int): ChannelFlow<T> =
- ChannelFlowBuilder(block, context, capacity)
+ capacity: Int = BUFFERED,
+ onBufferOverflow: BufferOverflow = BufferOverflow.SUSPEND
+) : ChannelFlow<T>(context, capacity, onBufferOverflow) {
+ override fun create(context: CoroutineContext, capacity: Int, onBufferOverflow: BufferOverflow): ChannelFlow<T> =
+ ChannelFlowBuilder(block, context, capacity, onBufferOverflow)
override suspend fun collectTo(scope: ProducerScope<T>) =
block(scope)
@@ -334,8 +350,9 @@
private class CallbackFlowBuilder<T>(
private val block: suspend ProducerScope<T>.() -> Unit,
context: CoroutineContext = EmptyCoroutineContext,
- capacity: Int = BUFFERED
-) : ChannelFlowBuilder<T>(block, context, capacity) {
+ capacity: Int = BUFFERED,
+ onBufferOverflow: BufferOverflow = BufferOverflow.SUSPEND
+) : ChannelFlowBuilder<T>(block, context, capacity, onBufferOverflow) {
override suspend fun collectTo(scope: ProducerScope<T>) {
super.collectTo(scope)
@@ -355,6 +372,6 @@
}
}
- override fun create(context: CoroutineContext, capacity: Int): ChannelFlow<T> =
- CallbackFlowBuilder(block, context, capacity)
+ override fun create(context: CoroutineContext, capacity: Int, onBufferOverflow: BufferOverflow): ChannelFlow<T> =
+ CallbackFlowBuilder(block, context, capacity, onBufferOverflow)
}
diff --git a/kotlinx-coroutines-core/common/src/flow/Channels.kt b/kotlinx-coroutines-core/common/src/flow/Channels.kt
index 2d3ef95..762cdca 100644
--- a/kotlinx-coroutines-core/common/src/flow/Channels.kt
+++ b/kotlinx-coroutines-core/common/src/flow/Channels.kt
@@ -20,6 +20,9 @@
* the channel afterwards. If you need to iterate over the channel without consuming it,
* a regular `for` loop should be used instead.
*
+ * Note, that emitting values from a channel into a flow is not atomic. A value that was received from the
+ * channel many not reach the flow collector if it was cancelled and will be lost.
+ *
* This function provides a more efficient shorthand for `channel.consumeEach { value -> emit(value) }`.
* See [consumeEach][ReceiveChannel.consumeEach].
*/
@@ -116,8 +119,9 @@
private val channel: ReceiveChannel<T>,
private val consume: Boolean,
context: CoroutineContext = EmptyCoroutineContext,
- capacity: Int = Channel.OPTIONAL_CHANNEL
-) : ChannelFlow<T>(context, capacity) {
+ capacity: Int = Channel.OPTIONAL_CHANNEL,
+ onBufferOverflow: BufferOverflow = BufferOverflow.SUSPEND
+) : ChannelFlow<T>(context, capacity, onBufferOverflow) {
private val consumed = atomic(false)
private fun markConsumed() {
@@ -126,8 +130,11 @@
}
}
- override fun create(context: CoroutineContext, capacity: Int): ChannelFlow<T> =
- ChannelAsFlow(channel, consume, context, capacity)
+ override fun create(context: CoroutineContext, capacity: Int, onBufferOverflow: BufferOverflow): ChannelFlow<T> =
+ ChannelAsFlow(channel, consume, context, capacity, onBufferOverflow)
+
+ override fun dropChannelOperators(): Flow<T>? =
+ ChannelAsFlow(channel, consume)
override suspend fun collectTo(scope: ProducerScope<T>) =
SendingCollector(scope).emitAllImpl(channel, consume) // use efficient channel receiving code from emitAll
@@ -154,7 +161,7 @@
}
}
- override fun additionalToStringProps(): String = "channel=$channel, "
+ override fun additionalToStringProps(): String = "channel=$channel"
}
/**
@@ -181,8 +188,22 @@
* Use [buffer] operator on the flow before calling `broadcastIn` to specify a value other than
* default and to control what happens when data is produced faster than it is consumed,
* that is to control backpressure behavior.
+ *
+ * ### Deprecated
+ *
+ * **This API is deprecated.** The [BroadcastChannel] provides a complex channel-like API for hot flows.
+ * [SharedFlow] is a easier-to-use and more flow-centric API for the same purposes, so using
+ * [shareIn] operator is preferred. It is not a direct replacement, so please
+ * study [shareIn] documentation to see what kind of shared flow fits your use-case. As a rule of thumb:
+ *
+ * * Replace `broadcastIn(scope)` and `broadcastIn(scope, CoroutineStart.LAZY)` with `shareIn(scope, 0, SharingStarted.Lazily)`.
+ * * Replace `broadcastIn(scope, CoroutineStart.DEFAULT)` with `shareIn(scope, 0, SharingStarted.Eagerly)`.
*/
-@FlowPreview
+@Deprecated(
+ message = "Use shareIn operator and the resulting SharedFlow as a replacement for BroadcastChannel",
+ replaceWith = ReplaceWith("shareIn(scope, 0, SharingStarted.Lazily)"),
+ level = DeprecationLevel.WARNING
+)
public fun <T> Flow<T>.broadcastIn(
scope: CoroutineScope,
start: CoroutineStart = CoroutineStart.LAZY
diff --git a/kotlinx-coroutines-core/common/src/flow/Flow.kt b/kotlinx-coroutines-core/common/src/flow/Flow.kt
index b7e2518..19a5b43 100644
--- a/kotlinx-coroutines-core/common/src/flow/Flow.kt
+++ b/kotlinx-coroutines-core/common/src/flow/Flow.kt
@@ -9,8 +9,7 @@
import kotlin.coroutines.*
/**
- * A cold asynchronous data stream that sequentially emits values
- * and completes normally or with an exception.
+ * An asynchronous data stream that sequentially emits values and completes normally or with an exception.
*
* _Intermediate operators_ on the flow such as [map], [filter], [take], [zip], etc are functions that are
* applied to the _upstream_ flow or flows and return a _downstream_ flow where further operators can be applied to.
@@ -39,11 +38,12 @@
* with an exception for a few operations specifically designed to introduce concurrency into flow
* execution such as [buffer] and [flatMapMerge]. See their documentation for details.
*
- * The `Flow` interface does not carry information whether a flow truly is a cold stream that can be collected repeatedly and
- * triggers execution of the same code every time it is collected, or if it is a hot stream that emits different
- * values from the same running source on each collection. However, conventionally flows represent cold streams.
- * Transitions between hot and cold streams are supported via channels and the corresponding API:
- * [channelFlow], [produceIn], [broadcastIn].
+ * The `Flow` interface does not carry information whether a flow is a _cold_ stream that can be collected repeatedly and
+ * triggers execution of the same code every time it is collected, or if it is a _hot_ stream that emits different
+ * values from the same running source on each collection. Usually flows represent _cold_ streams, but
+ * there is a [SharedFlow] subtype that represents _hot_ streams. In addition to that, any flow can be turned
+ * into a _hot_ one by the [stateIn] and [shareIn] operators, or by converting the flow into a hot channel
+ * via the [produceIn] operator.
*
* ### Flow builders
*
@@ -55,6 +55,8 @@
* sequential calls to [emit][FlowCollector.emit] function.
* * [channelFlow { ... }][channelFlow] builder function to construct arbitrary flows from
* potentially concurrent calls to the [send][kotlinx.coroutines.channels.SendChannel.send] function.
+ * * [MutableStateFlow] and [MutableSharedFlow] define the corresponding constructor functions to create
+ * a _hot_ flow that can be directly updated.
*
* ### Flow constraints
*
@@ -159,9 +161,9 @@
*
* ### Not stable for inheritance
*
- * **`Flow` interface is not stable for inheritance in 3rd party libraries**, as new methods
+ * **The `Flow` interface is not stable for inheritance in 3rd party libraries**, as new methods
* might be added to this interface in the future, but is stable for use.
- * Use `flow { ... }` builder function to create an implementation.
+ * Use the `flow { ... }` builder function to create an implementation.
*/
public interface Flow<out T> {
/**
@@ -201,7 +203,7 @@
* ```
*/
@FlowPreview
-public abstract class AbstractFlow<T> : Flow<T> {
+public abstract class AbstractFlow<T> : Flow<T>, CancellableFlow<T> {
@InternalCoroutinesApi
public final override suspend fun collect(collector: FlowCollector<T>) {
diff --git a/kotlinx-coroutines-core/common/src/flow/Migration.kt b/kotlinx-coroutines-core/common/src/flow/Migration.kt
index bb2f584..11969a4 100644
--- a/kotlinx-coroutines-core/common/src/flow/Migration.kt
+++ b/kotlinx-coroutines-core/common/src/flow/Migration.kt
@@ -9,8 +9,6 @@
package kotlinx.coroutines.flow
import kotlinx.coroutines.*
-import kotlinx.coroutines.flow.internal.*
-import kotlinx.coroutines.flow.internal.unsafeFlow
import kotlin.coroutines.*
import kotlin.jvm.*
@@ -99,7 +97,7 @@
* Opposed to subscribeOn, it it **possible** to use multiple `flowOn` operators in the one flow
* @suppress
*/
-@Deprecated(message = "Use flowOn instead", level = DeprecationLevel.ERROR)
+@Deprecated(message = "Use 'flowOn' instead", level = DeprecationLevel.ERROR)
public fun <T> Flow<T>.subscribeOn(context: CoroutineContext): Flow<T> = noImpl()
/**
@@ -151,7 +149,7 @@
* @suppress
*/
@Deprecated(
- message = "Use launchIn with onEach, onCompletion and catch operators instead",
+ message = "Use 'launchIn' with 'onEach', 'onCompletion' and 'catch' instead",
level = DeprecationLevel.ERROR
)
public fun <T> Flow<T>.subscribe(): Unit = noImpl()
@@ -161,7 +159,7 @@
* @suppress
*/
@Deprecated(
- message = "Use launchIn with onEach, onCompletion and catch operators instead",
+ message = "Use 'launchIn' with 'onEach', 'onCompletion' and 'catch' instead",
level = DeprecationLevel.ERROR
)public fun <T> Flow<T>.subscribe(onEach: suspend (T) -> Unit): Unit = noImpl()
@@ -170,7 +168,7 @@
* @suppress
*/
@Deprecated(
- message = "Use launchIn with onEach, onCompletion and catch operators instead",
+ message = "Use 'launchIn' with 'onEach', 'onCompletion' and 'catch' instead",
level = DeprecationLevel.ERROR
)public fun <T> Flow<T>.subscribe(onEach: suspend (T) -> Unit, onError: suspend (Throwable) -> Unit): Unit = noImpl()
@@ -181,7 +179,7 @@
*/
@Deprecated(
level = DeprecationLevel.ERROR,
- message = "Flow analogue is named flatMapConcat",
+ message = "Flow analogue is 'flatMapConcat'",
replaceWith = ReplaceWith("flatMapConcat(mapper)")
)
public fun <T, R> Flow<T>.flatMap(mapper: suspend (T) -> Flow<R>): Flow<R> = noImpl()
@@ -369,10 +367,10 @@
message = "Flow analogue of 'combineLatest' is 'combine'",
replaceWith = ReplaceWith("combine(this, other, other2, transform)")
)
-public inline fun <T1, T2, T3, R> Flow<T1>.combineLatest(
+public fun <T1, T2, T3, R> Flow<T1>.combineLatest(
other: Flow<T2>,
other2: Flow<T3>,
- crossinline transform: suspend (T1, T2, T3) -> R
+ transform: suspend (T1, T2, T3) -> R
) = combine(this, other, other2, transform)
@Deprecated(
@@ -380,11 +378,11 @@
message = "Flow analogue of 'combineLatest' is 'combine'",
replaceWith = ReplaceWith("combine(this, other, other2, other3, transform)")
)
-public inline fun <T1, T2, T3, T4, R> Flow<T1>.combineLatest(
+public fun <T1, T2, T3, T4, R> Flow<T1>.combineLatest(
other: Flow<T2>,
other2: Flow<T3>,
other3: Flow<T4>,
- crossinline transform: suspend (T1, T2, T3, T4) -> R
+ transform: suspend (T1, T2, T3, T4) -> R
) = combine(this, other, other2, other3, transform)
@Deprecated(
@@ -392,12 +390,12 @@
message = "Flow analogue of 'combineLatest' is 'combine'",
replaceWith = ReplaceWith("combine(this, other, other2, other3, transform)")
)
-public inline fun <T1, T2, T3, T4, T5, R> Flow<T1>.combineLatest(
+public fun <T1, T2, T3, T4, T5, R> Flow<T1>.combineLatest(
other: Flow<T2>,
other2: Flow<T3>,
other3: Flow<T4>,
other4: Flow<T5>,
- crossinline transform: suspend (T1, T2, T3, T4, T5) -> R
+ transform: suspend (T1, T2, T3, T4, T5) -> R
): Flow<R> = combine(this, other, other2, other3, other4, transform)
/**
@@ -436,5 +434,51 @@
message = "'scanReduce' was renamed to 'runningReduce' to be consistent with Kotlin standard library",
replaceWith = ReplaceWith("runningReduce(operation)")
)
-@ExperimentalCoroutinesApi
public fun <T> Flow<T>.scanReduce(operation: suspend (accumulator: T, value: T) -> T): Flow<T> = runningReduce(operation)
+
+@Deprecated(
+ level = DeprecationLevel.ERROR,
+ message = "Flow analogue of 'publish()' is 'shareIn'. \n" +
+ "publish().connect() is the default strategy (no extra call is needed), \n" +
+ "publish().autoConnect() translates to 'started = SharingStared.Lazily' argument, \n" +
+ "publish().refCount() translates to 'started = SharingStared.WhileSubscribed()' argument.",
+ replaceWith = ReplaceWith("this.shareIn(scope, 0)")
+)
+public fun <T> Flow<T>.publish(): Flow<T> = noImpl()
+
+@Deprecated(
+ level = DeprecationLevel.ERROR,
+ message = "Flow analogue of 'publish(bufferSize)' is 'buffer' followed by 'shareIn'. \n" +
+ "publish().connect() is the default strategy (no extra call is needed), \n" +
+ "publish().autoConnect() translates to 'started = SharingStared.Lazily' argument, \n" +
+ "publish().refCount() translates to 'started = SharingStared.WhileSubscribed()' argument.",
+ replaceWith = ReplaceWith("this.buffer(bufferSize).shareIn(scope, 0)")
+)
+public fun <T> Flow<T>.publish(bufferSize: Int): Flow<T> = noImpl()
+
+@Deprecated(
+ level = DeprecationLevel.ERROR,
+ message = "Flow analogue of 'replay()' is 'shareIn' with unlimited replay. \n" +
+ "replay().connect() is the default strategy (no extra call is needed), \n" +
+ "replay().autoConnect() translates to 'started = SharingStared.Lazily' argument, \n" +
+ "replay().refCount() translates to 'started = SharingStared.WhileSubscribed()' argument.",
+ replaceWith = ReplaceWith("this.shareIn(scope, Int.MAX_VALUE)")
+)
+public fun <T> Flow<T>.replay(): Flow<T> = noImpl()
+
+@Deprecated(
+ level = DeprecationLevel.ERROR,
+ message = "Flow analogue of 'replay(bufferSize)' is 'shareIn' with the specified replay parameter. \n" +
+ "replay().connect() is the default strategy (no extra call is needed), \n" +
+ "replay().autoConnect() translates to 'started = SharingStared.Lazily' argument, \n" +
+ "replay().refCount() translates to 'started = SharingStared.WhileSubscribed()' argument.",
+ replaceWith = ReplaceWith("this.shareIn(scope, bufferSize)")
+)
+public fun <T> Flow<T>.replay(bufferSize: Int): Flow<T> = noImpl()
+
+@Deprecated(
+ level = DeprecationLevel.ERROR,
+ message = "Flow analogue of 'cache()' is 'shareIn' with unlimited replay and 'started = SharingStared.Lazily' argument'",
+ replaceWith = ReplaceWith("this.shareIn(scope, Int.MAX_VALUE, started = SharingStared.Lazily)")
+)
+public fun <T> Flow<T>.cache(): Flow<T> = noImpl()
diff --git a/kotlinx-coroutines-core/common/src/flow/SharedFlow.kt b/kotlinx-coroutines-core/common/src/flow/SharedFlow.kt
new file mode 100644
index 0000000..feb2749
--- /dev/null
+++ b/kotlinx-coroutines-core/common/src/flow/SharedFlow.kt
@@ -0,0 +1,664 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.flow
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.channels.*
+import kotlinx.coroutines.flow.internal.*
+import kotlinx.coroutines.internal.*
+import kotlin.coroutines.*
+import kotlin.jvm.*
+import kotlin.native.concurrent.*
+
+/**
+ * A _hot_ [Flow] that shares emitted values among all its collectors in a broadcast fashion, so that all collectors
+ * get all emitted values. A shared flow is called _hot_ because its active instance exists independently of the
+ * presence of collectors. This is opposed to a regular [Flow], such as defined by the [`flow { ... }`][flow] function,
+ * which is _cold_ and is started separately for each collector.
+ *
+ * **Shared flow never completes**. A call to [Flow.collect] on a shared flow never completes normally, and
+ * neither does a coroutine started by the [Flow.launchIn] function. An active collector of a shared flow is called a _subscriber_.
+ *
+ * A subscriber of a shared flow can be cancelled. This usually happens when the scope in which the coroutine is running
+ * is cancelled. A subscriber to a shared flow is always [cancellable][Flow.cancellable], and checks for
+ * cancellation before each emission. Note that most terminal operators like [Flow.toList] would also not complete,
+ * when applied to a shared flow, but flow-truncating operators like [Flow.take] and [Flow.takeWhile] can be used on a
+ * shared flow to turn it into a completing one.
+ *
+ * A [mutable shared flow][MutableSharedFlow] is created using the [MutableSharedFlow(...)] constructor function.
+ * Its state can be updated by [emitting][MutableSharedFlow.emit] values to it and performing other operations.
+ * See the [MutableSharedFlow] documentation for details.
+ *
+ * [SharedFlow] is useful for broadcasting events that happen inside an application to subscribers that can come and go.
+ * For example, the following class encapsulates an event bus that distributes events to all subscribers
+ * in a _rendezvous_ manner, suspending until all subscribers process each event:
+ *
+ * ```
+ * class EventBus {
+ * private val _events = MutableSharedFlow<Event>() // private mutable shared flow
+ * val events = _events.asSharedFlow() // publicly exposed as read-only shared flow
+ *
+ * suspend fun produceEvent(event: Event) {
+ * _events.emit(event) // suspends until all subscribers receive it
+ * }
+ * }
+ * ```
+ *
+ * As an alternative to the above usage with the `MutableSharedFlow(...)` constructor function,
+ * any _cold_ [Flow] can be converted to a shared flow using the [shareIn] operator.
+ *
+ * There is a specialized implementation of shared flow for the case where the most recent state value needs
+ * to be shared. See [StateFlow] for details.
+ *
+ * ### Replay cache and buffer
+ *
+ * A shared flow keeps a specific number of the most recent values in its _replay cache_. Every new subscriber first
+ * gets the values from the replay cache and then gets new emitted values. The maximum size of the replay cache is
+ * specified when the shared flow is created by the `replay` parameter. A snapshot of the current replay cache
+ * is available via the [replayCache] property and it can be reset with the [MutableSharedFlow.resetReplayCache] function.
+ *
+ * A replay cache also provides buffer for emissions to the shared flow, allowing slow subscribers to
+ * get values from the buffer without suspending emitters. The buffer space determines how much slow subscribers
+ * can lag from the fast ones. When creating a shared flow, additional buffer capacity beyond replay can be reserved
+ * using the `extraBufferCapacity` parameter.
+ *
+ * A shared flow with a buffer can be configured to avoid suspension of emitters on buffer overflow using
+ * the `onBufferOverflow` parameter, which is equal to one of the entries of the [BufferOverflow] enum. When a strategy other
+ * than [SUSPENDED][BufferOverflow.SUSPEND] is configured, emissions to the shared flow never suspend.
+ *
+ * ### SharedFlow vs BroadcastChannel
+ *
+ * Conceptually shared flow is similar to [BroadcastChannel][BroadcastChannel]
+ * and is designed to completely replace `BroadcastChannel` in the future.
+ * It has the following important differences:
+ *
+ * * `SharedFlow` is simpler, because it does not have to implement all the [Channel] APIs, which allows
+ * for faster and simpler implementation.
+ * * `SharedFlow` supports configurable replay and buffer overflow strategy.
+ * * `SharedFlow` has a clear separation into a read-only `SharedFlow` interface and a [MutableSharedFlow].
+ * * `SharedFlow` cannot be closed like `BroadcastChannel` and can never represent a failure.
+ * All errors and completion signals should be explicitly _materialized_ if needed.
+ *
+ * To migrate [BroadcastChannel] usage to [SharedFlow], start by replacing usages of the `BroadcastChannel(capacity)`
+ * constructor with `MutableSharedFlow(0, extraBufferCapacity=capacity)` (broadcast channel does not replay
+ * values to new subscribers). Replace [send][BroadcastChannel.send] and [offer][BroadcastChannel.offer] calls
+ * with [emit][MutableStateFlow.emit] and [tryEmit][MutableStateFlow.tryEmit], and convert subscribers' code to flow operators.
+ *
+ * ### Concurrency
+ *
+ * All methods of shared flow are **thread-safe** and can be safely invoked from concurrent coroutines without
+ * external synchronization.
+ *
+ * ### Operator fusion
+ *
+ * Application of [flowOn][Flow.flowOn], [buffer] with [RENDEZVOUS][Channel.RENDEZVOUS] capacity,
+ * or [cancellable] operators to a shared flow has no effect.
+ *
+ * ### Implementation notes
+ *
+ * Shared flow implementation uses a lock to ensure thread-safety, but suspending collector and emitter coroutines are
+ * resumed outside of this lock to avoid dead-locks when using unconfined coroutines. Adding new subscribers
+ * has `O(1)` amortized cost, but emitting has `O(N)` cost, where `N` is the number of subscribers.
+ *
+ * ### Not stable for inheritance
+ *
+ * **The `SharedFlow` interface is not stable for inheritance in 3rd party libraries**, as new methods
+ * might be added to this interface in the future, but is stable for use.
+ * Use the `MutableSharedFlow(replay, ...)` constructor function to create an implementation.
+ */
+public interface SharedFlow<out T> : Flow<T> {
+ /**
+ * A snapshot of the replay cache.
+ */
+ public val replayCache: List<T>
+}
+
+/**
+ * A mutable [SharedFlow] that provides functions to [emit] values to the flow.
+ * An instance of `MutableSharedFlow` with the given configuration parameters can be created using `MutableSharedFlow(...)`
+ * constructor function.
+ *
+ * See the [SharedFlow] documentation for details on shared flows.
+ *
+ * `MutableSharedFlow` is a [SharedFlow] that also provides the abilities to [emit] a value,
+ * to [tryEmit] without suspension if possible, to track the [subscriptionCount],
+ * and to [resetReplayCache].
+ *
+ * ### Concurrency
+ *
+ * All methods of shared flow are **thread-safe** and can be safely invoked from concurrent coroutines without
+ * external synchronization.
+ *
+ * ### Not stable for inheritance
+ *
+ * **The `MutableSharedFlow` interface is not stable for inheritance in 3rd party libraries**, as new methods
+ * might be added to this interface in the future, but is stable for use.
+ * Use the `MutableSharedFlow(...)` constructor function to create an implementation.
+ */
+public interface MutableSharedFlow<T> : SharedFlow<T>, FlowCollector<T> {
+ /**
+ * Tries to emit a [value] to this shared flow without suspending. It returns `true` if the value was
+ * emitted successfully. When this function returns `false`, it means that the call to a plain [emit]
+ * function will suspend until there is a buffer space available.
+ *
+ * A shared flow configured with a [BufferOverflow] strategy other than [SUSPEND][BufferOverflow.SUSPEND]
+ * (either [DROP_OLDEST][BufferOverflow.DROP_OLDEST] or [DROP_LATEST][BufferOverflow.DROP_LATEST]) never
+ * suspends on [emit], and thus `tryEmit` to such a shared flow always returns `true`.
+ */
+ public fun tryEmit(value: T): Boolean
+
+ /**
+ * The number of subscribers (active collectors) to this shared flow.
+ *
+ * The integer in the resulting [StateFlow] is not negative and starts with zero for a freshly created
+ * shared flow.
+ *
+ * This state can be used to react to changes in the number of subscriptions to this shared flow.
+ * For example, if you need to call `onActive` when the first subscriber appears and `onInactive`
+ * when the last one disappears, you can set it up like this:
+ *
+ * ```
+ * sharedFlow.subscriptionCount
+ * .map { count -> count > 0 } // map count into active/inactive flag
+ * .distinctUntilChanged() // only react to true<->false changes
+ * .onEach { isActive -> // configure an action
+ * if (isActive) onActive() else onInactive()
+ * }
+ * .launchIn(scope) // launch it
+ * ```
+ */
+ public val subscriptionCount: StateFlow<Int>
+
+ /**
+ * Resets the [replayCache] of this shared flow to an empty state.
+ * New subscribers will be receiving only the values that were emitted after this call,
+ * while old subscribers will still be receiving previously buffered values.
+ * To reset a shared flow to an initial value, emit the value after this call.
+ *
+ * On a [MutableStateFlow], which always contains a single value, this function is not
+ * supported, and throws an [UnsupportedOperationException]. To reset a [MutableStateFlow]
+ * to an initial value, just update its [value][MutableStateFlow.value].
+ *
+ * **Note: This is an experimental api.** This function may be removed or renamed in the future.
+ */
+ @ExperimentalCoroutinesApi
+ public fun resetReplayCache()
+}
+
+/**
+ * Creates a [MutableSharedFlow] with the given configuration parameters.
+ *
+ * This function throws [IllegalArgumentException] on unsupported values of parameters or combinations thereof.
+ *
+ * @param replay the number of values replayed to new subscribers (cannot be negative, defaults to zero).
+ * @param extraBufferCapacity the number of values buffered in addition to `replay`.
+ * [emit][MutableSharedFlow.emit] does not suspend while there is a buffer space remaining (optional, cannot be negative, defaults to zero).
+ * @param onBufferOverflow configures an action on buffer overflow (optional, defaults to
+ * [suspending][BufferOverflow.SUSPEND] attempts to [emit][MutableSharedFlow.emit] a value,
+ * supported only when `replay > 0` or `extraBufferCapacity > 0`).
+ */
+@Suppress("FunctionName", "UNCHECKED_CAST")
+public fun <T> MutableSharedFlow(
+ replay: Int = 0,
+ extraBufferCapacity: Int = 0,
+ onBufferOverflow: BufferOverflow = BufferOverflow.SUSPEND
+): MutableSharedFlow<T> {
+ require(replay >= 0) { "replay cannot be negative, but was $replay" }
+ require(extraBufferCapacity >= 0) { "extraBufferCapacity cannot be negative, but was $extraBufferCapacity" }
+ require(replay > 0 || extraBufferCapacity > 0 || onBufferOverflow == BufferOverflow.SUSPEND) {
+ "replay or extraBufferCapacity must be positive with non-default onBufferOverflow strategy $onBufferOverflow"
+ }
+ val bufferCapacity0 = replay + extraBufferCapacity
+ val bufferCapacity = if (bufferCapacity0 < 0) Int.MAX_VALUE else bufferCapacity0 // coerce to MAX_VALUE on overflow
+ return SharedFlowImpl(replay, bufferCapacity, onBufferOverflow)
+}
+
+// ------------------------------------ Implementation ------------------------------------
+
+private class SharedFlowSlot : AbstractSharedFlowSlot<SharedFlowImpl<*>>() {
+ @JvmField
+ var index = -1L // current "to-be-emitted" index, -1 means the slot is free now
+
+ @JvmField
+ var cont: Continuation<Unit>? = null // collector waiting for new value
+
+ override fun allocateLocked(flow: SharedFlowImpl<*>): Boolean {
+ if (index >= 0) return false // not free
+ index = flow.updateNewCollectorIndexLocked()
+ return true
+ }
+
+ override fun freeLocked(flow: SharedFlowImpl<*>): Array<Continuation<Unit>?> {
+ assert { index >= 0 }
+ val oldIndex = index
+ index = -1L
+ cont = null // cleanup continuation reference
+ return flow.updateCollectorIndexLocked(oldIndex)
+ }
+}
+
+private class SharedFlowImpl<T>(
+ private val replay: Int,
+ private val bufferCapacity: Int,
+ private val onBufferOverflow: BufferOverflow
+) : AbstractSharedFlow<SharedFlowSlot>(), MutableSharedFlow<T>, CancellableFlow<T>, FusibleFlow<T> {
+ /*
+ Logical structure of the buffer
+
+ buffered values
+ /-----------------------\
+ replayCache queued emitters
+ /----------\/----------------------\
+ +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
+ | | 1 | 2 | 3 | 4 | 5 | 6 | E | E | E | E | E | E | | | |
+ +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
+ ^ ^ ^ ^
+ | | | |
+ head | head + bufferSize head + totalSize
+ | | |
+ index of the slowest | index of the fastest
+ possible collector | possible collector
+ | |
+ | replayIndex == new collector's index
+ \---------------------- /
+ range of possible minCollectorIndex
+
+ head == minOf(minCollectorIndex, replayIndex) // by definition
+ totalSize == bufferSize + queueSize // by definition
+
+ INVARIANTS:
+ minCollectorIndex = activeSlots.minOf { it.index } ?: (head + bufferSize)
+ replayIndex <= head + bufferSize
+ */
+
+ // Stored state
+ private var buffer: Array<Any?>? = null // allocated when needed, allocated size always power of two
+ private var replayIndex = 0L // minimal index from which new collector gets values
+ private var minCollectorIndex = 0L // minimal index of active collectors, equal to replayIndex if there are none
+ private var bufferSize = 0 // number of buffered values
+ private var queueSize = 0 // number of queued emitters
+
+ // Computed state
+ private val head: Long get() = minOf(minCollectorIndex, replayIndex)
+ private val replaySize: Int get() = (head + bufferSize - replayIndex).toInt()
+ private val totalSize: Int get() = bufferSize + queueSize
+ private val bufferEndIndex: Long get() = head + bufferSize
+ private val queueEndIndex: Long get() = head + bufferSize + queueSize
+
+ override val replayCache: List<T>
+ get() = synchronized(this) {
+ val replaySize = this.replaySize
+ if (replaySize == 0) return emptyList()
+ val result = ArrayList<T>(replaySize)
+ val buffer = buffer!! // must be allocated, because replaySize > 0
+ @Suppress("UNCHECKED_CAST")
+ for (i in 0 until replaySize) result += buffer.getBufferAt(replayIndex + i) as T
+ result
+ }
+
+ @Suppress("UNCHECKED_CAST")
+ override suspend fun collect(collector: FlowCollector<T>) {
+ val slot = allocateSlot()
+ try {
+ if (collector is SubscribedFlowCollector) collector.onSubscription()
+ val collectorJob = currentCoroutineContext()[Job]
+ while (true) {
+ var newValue: Any?
+ while (true) {
+ newValue = tryTakeValue(slot) // attempt no-suspend fast path first
+ if (newValue !== NO_VALUE) break
+ awaitValue(slot) // await signal that the new value is available
+ }
+ collectorJob?.ensureActive()
+ collector.emit(newValue as T)
+ }
+ } finally {
+ freeSlot(slot)
+ }
+ }
+
+ override fun tryEmit(value: T): Boolean {
+ var resumes: Array<Continuation<Unit>?> = EMPTY_RESUMES
+ val emitted = synchronized(this) {
+ if (tryEmitLocked(value)) {
+ resumes = findSlotsToResumeLocked(resumes)
+ true
+ } else {
+ false
+ }
+ }
+ for (cont in resumes) cont?.resume(Unit)
+ return emitted
+ }
+
+ override suspend fun emit(value: T) {
+ if (tryEmit(value)) return // fast-path
+ emitSuspend(value)
+ }
+
+ @Suppress("UNCHECKED_CAST")
+ private fun tryEmitLocked(value: T): Boolean {
+ // Fast path without collectors -> no buffering
+ if (nCollectors == 0) return tryEmitNoCollectorsLocked(value) // always returns true
+ // With collectors we'll have to buffer
+ // cannot emit now if buffer is full & blocked by slow collectors
+ if (bufferSize >= bufferCapacity && minCollectorIndex <= replayIndex) {
+ when (onBufferOverflow) {
+ BufferOverflow.SUSPEND -> return false // will suspend
+ BufferOverflow.DROP_LATEST -> return true // just drop incoming
+ BufferOverflow.DROP_OLDEST -> {} // force enqueue & drop oldest instead
+ }
+ }
+ enqueueLocked(value)
+ bufferSize++ // value was added to buffer
+ // drop oldest from the buffer if it became more than bufferCapacity
+ if (bufferSize > bufferCapacity) dropOldestLocked()
+ // keep replaySize not larger that needed
+ if (replaySize > replay) { // increment replayIndex by one
+ updateBufferLocked(replayIndex + 1, minCollectorIndex, bufferEndIndex, queueEndIndex)
+ }
+ return true
+ }
+
+ private fun tryEmitNoCollectorsLocked(value: T): Boolean {
+ assert { nCollectors == 0 }
+ if (replay == 0) return true // no need to replay, just forget it now
+ enqueueLocked(value) // enqueue to replayCache
+ bufferSize++ // value was added to buffer
+ // drop oldest from the buffer if it became more than replay
+ if (bufferSize > replay) dropOldestLocked()
+ minCollectorIndex = head + bufferSize // a default value (max allowed)
+ return true
+ }
+
+ private fun dropOldestLocked() {
+ buffer!!.setBufferAt(head, null)
+ bufferSize--
+ val newHead = head + 1
+ if (replayIndex < newHead) replayIndex = newHead
+ if (minCollectorIndex < newHead) correctCollectorIndexesOnDropOldest(newHead)
+ assert { head == newHead } // since head = minOf(minCollectorIndex, replayIndex) it should have updated
+ }
+
+ private fun correctCollectorIndexesOnDropOldest(newHead: Long) {
+ forEachSlotLocked { slot ->
+ @Suppress("ConvertTwoComparisonsToRangeCheck") // Bug in JS backend
+ if (slot.index >= 0 && slot.index < newHead) {
+ slot.index = newHead // force move it up (this collector was too slow and missed the value at its index)
+ }
+ }
+ minCollectorIndex = newHead
+ }
+
+ // enqueues item to buffer array, caller shall increment either bufferSize or queueSize
+ private fun enqueueLocked(item: Any?) {
+ val curSize = totalSize
+ val buffer = when (val curBuffer = buffer) {
+ null -> growBuffer(null, 0, 2)
+ else -> if (curSize >= curBuffer.size) growBuffer(curBuffer, curSize,curBuffer.size * 2) else curBuffer
+ }
+ buffer.setBufferAt(head + curSize, item)
+ }
+
+ private fun growBuffer(curBuffer: Array<Any?>?, curSize: Int, newSize: Int): Array<Any?> {
+ check(newSize > 0) { "Buffer size overflow" }
+ val newBuffer = arrayOfNulls<Any?>(newSize).also { buffer = it }
+ if (curBuffer == null) return newBuffer
+ val head = head
+ for (i in 0 until curSize) {
+ newBuffer.setBufferAt(head + i, curBuffer.getBufferAt(head + i))
+ }
+ return newBuffer
+ }
+
+ private suspend fun emitSuspend(value: T) = suspendCancellableCoroutine<Unit> sc@{ cont ->
+ var resumes: Array<Continuation<Unit>?> = EMPTY_RESUMES
+ val emitter = synchronized(this) lock@{
+ // recheck buffer under lock again (make sure it is really full)
+ if (tryEmitLocked(value)) {
+ cont.resume(Unit)
+ resumes = findSlotsToResumeLocked(resumes)
+ return@lock null
+ }
+ // add suspended emitter to the buffer
+ Emitter(this, head + totalSize, value, cont).also {
+ enqueueLocked(it)
+ queueSize++ // added to queue of waiting emitters
+ // synchronous shared flow might rendezvous with waiting emitter
+ if (bufferCapacity == 0) resumes = findSlotsToResumeLocked(resumes)
+ }
+ }
+ // outside of the lock: register dispose on cancellation
+ emitter?.let { cont.disposeOnCancellation(it) }
+ // outside of the lock: resume slots if needed
+ for (cont in resumes) cont?.resume(Unit)
+ }
+
+ private fun cancelEmitter(emitter: Emitter) = synchronized(this) {
+ if (emitter.index < head) return // already skipped past this index
+ val buffer = buffer!!
+ if (buffer.getBufferAt(emitter.index) !== emitter) return // already resumed
+ buffer.setBufferAt(emitter.index, NO_VALUE)
+ cleanupTailLocked()
+ }
+
+ internal fun updateNewCollectorIndexLocked(): Long {
+ val index = replayIndex
+ if (index < minCollectorIndex) minCollectorIndex = index
+ return index
+ }
+
+ // Is called when a collector disappears or changes index, returns a list of continuations to resume after lock
+ internal fun updateCollectorIndexLocked(oldIndex: Long): Array<Continuation<Unit>?> {
+ assert { oldIndex >= minCollectorIndex }
+ if (oldIndex > minCollectorIndex) return EMPTY_RESUMES // nothing changes, it was not min
+ // start computing new minimal index of active collectors
+ val head = head
+ var newMinCollectorIndex = head + bufferSize
+ // take into account a special case of sync shared flow that can go past 1st queued emitter
+ if (bufferCapacity == 0 && queueSize > 0) newMinCollectorIndex++
+ forEachSlotLocked { slot ->
+ @Suppress("ConvertTwoComparisonsToRangeCheck") // Bug in JS backend
+ if (slot.index >= 0 && slot.index < newMinCollectorIndex) newMinCollectorIndex = slot.index
+ }
+ assert { newMinCollectorIndex >= minCollectorIndex } // can only grow
+ if (newMinCollectorIndex <= minCollectorIndex) return EMPTY_RESUMES // nothing changes
+ // Compute new buffer size if we drop items we no longer need and no emitter is resumed:
+ // We must keep all the items from newMinIndex to the end of buffer
+ var newBufferEndIndex = bufferEndIndex // var to grow when waiters are resumed
+ val maxResumeCount = if (nCollectors > 0) {
+ // If we have collectors we can resume up to maxResumeCount waiting emitters
+ // a) queueSize -> that's how many waiting emitters we have
+ // b) bufferCapacity - newBufferSize0 -> that's how many we can afford to resume to add w/o exceeding bufferCapacity
+ val newBufferSize0 = (newBufferEndIndex - newMinCollectorIndex).toInt()
+ minOf(queueSize, bufferCapacity - newBufferSize0)
+ } else {
+ // If we don't have collectors anymore we must resume all waiting emitters
+ queueSize // that's how many waiting emitters we have (at most)
+ }
+ var resumes: Array<Continuation<Unit>?> = EMPTY_RESUMES
+ val newQueueEndIndex = newBufferEndIndex + queueSize
+ if (maxResumeCount > 0) { // collect emitters to resume if we have them
+ resumes = arrayOfNulls(maxResumeCount)
+ var resumeCount = 0
+ val buffer = buffer!!
+ for (curEmitterIndex in newBufferEndIndex until newQueueEndIndex) {
+ val emitter = buffer.getBufferAt(curEmitterIndex)
+ if (emitter !== NO_VALUE) {
+ emitter as Emitter // must have Emitter class
+ resumes[resumeCount++] = emitter.cont
+ buffer.setBufferAt(curEmitterIndex, NO_VALUE) // make as canceled if we moved ahead
+ buffer.setBufferAt(newBufferEndIndex, emitter.value)
+ newBufferEndIndex++
+ if (resumeCount >= maxResumeCount) break // enough resumed, done
+ }
+ }
+ }
+ // Compute new buffer size -> how many values we now actually have after resume
+ val newBufferSize1 = (newBufferEndIndex - head).toInt()
+ // Note: When nCollectors == 0 we resume ALL queued emitters and we might have resumed more than bufferCapacity,
+ // and newMinCollectorIndex might pointing the wrong place because of that. The easiest way to fix it is by
+ // forcing newMinCollectorIndex = newBufferEndIndex. We do not needed to update newBufferSize1 (which could be
+ // too big), because the only use of newBufferSize1 in the below code is in the minOf(replay, newBufferSize1)
+ // expression, which coerces values that are too big anyway.
+ if (nCollectors == 0) newMinCollectorIndex = newBufferEndIndex
+ // Compute new replay size -> limit to replay the number of items we need, take into account that it can only grow
+ var newReplayIndex = maxOf(replayIndex, newBufferEndIndex - minOf(replay, newBufferSize1))
+ // adjustment for synchronous case with cancelled emitter (NO_VALUE)
+ if (bufferCapacity == 0 && newReplayIndex < newQueueEndIndex && buffer!!.getBufferAt(newReplayIndex) == NO_VALUE) {
+ newBufferEndIndex++
+ newReplayIndex++
+ }
+ // Update buffer state
+ updateBufferLocked(newReplayIndex, newMinCollectorIndex, newBufferEndIndex, newQueueEndIndex)
+ // just in case we've moved all buffered emitters and have NO_VALUE's at the tail now
+ cleanupTailLocked()
+ // We need to waken up suspended collectors if any emitters were resumed here
+ if (resumes.isNotEmpty()) resumes = findSlotsToResumeLocked(resumes)
+ return resumes
+ }
+
+ private fun updateBufferLocked(
+ newReplayIndex: Long,
+ newMinCollectorIndex: Long,
+ newBufferEndIndex: Long,
+ newQueueEndIndex: Long
+ ) {
+ // Compute new head value
+ val newHead = minOf(newMinCollectorIndex, newReplayIndex)
+ assert { newHead >= head }
+ // cleanup items we don't have to buffer anymore (because head is about to move)
+ for (index in head until newHead) buffer!!.setBufferAt(index, null)
+ // update all state variables to newly computed values
+ replayIndex = newReplayIndex
+ minCollectorIndex = newMinCollectorIndex
+ bufferSize = (newBufferEndIndex - newHead).toInt()
+ queueSize = (newQueueEndIndex - newBufferEndIndex).toInt()
+ // check our key invariants (just in case)
+ assert { bufferSize >= 0 }
+ assert { queueSize >= 0 }
+ assert { replayIndex <= this.head + bufferSize }
+ }
+
+ // Removes all the NO_VALUE items from the end of the queue and reduces its size
+ private fun cleanupTailLocked() {
+ // If we have synchronous case, then keep one emitter queued
+ if (bufferCapacity == 0 && queueSize <= 1) return // return, don't clear it
+ val buffer = buffer!!
+ while (queueSize > 0 && buffer.getBufferAt(head + totalSize - 1) === NO_VALUE) {
+ queueSize--
+ buffer.setBufferAt(head + totalSize, null)
+ }
+ }
+
+ // returns NO_VALUE if cannot take value without suspension
+ private fun tryTakeValue(slot: SharedFlowSlot): Any? {
+ var resumes: Array<Continuation<Unit>?> = EMPTY_RESUMES
+ val value = synchronized(this) {
+ val index = tryPeekLocked(slot)
+ if (index < 0) {
+ NO_VALUE
+ } else {
+ val oldIndex = slot.index
+ val newValue = getPeekedValueLockedAt(index)
+ slot.index = index + 1 // points to the next index after peeked one
+ resumes = updateCollectorIndexLocked(oldIndex)
+ newValue
+ }
+ }
+ for (resume in resumes) resume?.resume(Unit)
+ return value
+ }
+
+ // returns -1 if cannot peek value without suspension
+ private fun tryPeekLocked(slot: SharedFlowSlot): Long {
+ // return buffered value if possible
+ val index = slot.index
+ if (index < bufferEndIndex) return index
+ if (bufferCapacity > 0) return -1L // if there's a buffer, never try to rendezvous with emitters
+ // Synchronous shared flow (bufferCapacity == 0) tries to rendezvous
+ if (index > head) return -1L // ... but only with the first emitter (never look forward)
+ if (queueSize == 0) return -1L // nothing there to rendezvous with
+ return index // rendezvous with the first emitter
+ }
+
+ private fun getPeekedValueLockedAt(index: Long): Any? =
+ when (val item = buffer!!.getBufferAt(index)) {
+ is Emitter -> item.value
+ else -> item
+ }
+
+ private suspend fun awaitValue(slot: SharedFlowSlot): Unit = suspendCancellableCoroutine { cont ->
+ synchronized(this) lock@{
+ val index = tryPeekLocked(slot) // recheck under this lock
+ if (index < 0) {
+ slot.cont = cont // Ok -- suspending
+ } else {
+ cont.resume(Unit) // has value, no need to suspend
+ return@lock
+ }
+ slot.cont = cont // suspend, waiting
+ }
+ }
+
+ private fun findSlotsToResumeLocked(resumesIn: Array<Continuation<Unit>?>): Array<Continuation<Unit>?> {
+ var resumes: Array<Continuation<Unit>?> = resumesIn
+ var resumeCount = resumesIn.size
+ forEachSlotLocked loop@{ slot ->
+ val cont = slot.cont ?: return@loop // only waiting slots
+ if (tryPeekLocked(slot) < 0) return@loop // only slots that can peek a value
+ if (resumeCount >= resumes.size) resumes = resumes.copyOf(maxOf(2, 2 * resumes.size))
+ resumes[resumeCount++] = cont
+ slot.cont = null // not waiting anymore
+ }
+ return resumes
+ }
+
+ override fun createSlot() = SharedFlowSlot()
+ override fun createSlotArray(size: Int): Array<SharedFlowSlot?> = arrayOfNulls(size)
+
+ override fun resetReplayCache() = synchronized(this) {
+ // Update buffer state
+ updateBufferLocked(
+ newReplayIndex = bufferEndIndex,
+ newMinCollectorIndex = minCollectorIndex,
+ newBufferEndIndex = bufferEndIndex,
+ newQueueEndIndex = queueEndIndex
+ )
+ }
+
+ override fun fuse(context: CoroutineContext, capacity: Int, onBufferOverflow: BufferOverflow) =
+ fuseSharedFlow(context, capacity, onBufferOverflow)
+
+ private class Emitter(
+ @JvmField val flow: SharedFlowImpl<*>,
+ @JvmField var index: Long,
+ @JvmField val value: Any?,
+ @JvmField val cont: Continuation<Unit>
+ ) : DisposableHandle {
+ override fun dispose() = flow.cancelEmitter(this)
+ }
+}
+
+@SharedImmutable
+@JvmField
+internal val NO_VALUE = Symbol("NO_VALUE")
+
+private fun Array<Any?>.getBufferAt(index: Long) = get(index.toInt() and (size - 1))
+private fun Array<Any?>.setBufferAt(index: Long, item: Any?) = set(index.toInt() and (size - 1), item)
+
+internal fun <T> SharedFlow<T>.fuseSharedFlow(
+ context: CoroutineContext,
+ capacity: Int,
+ onBufferOverflow: BufferOverflow
+): Flow<T> {
+ // context is irrelevant for shared flow and making additional rendezvous is meaningless
+ // however, additional non-trivial buffering after shared flow could make sense for very slow subscribers
+ if ((capacity == Channel.RENDEZVOUS || capacity == Channel.OPTIONAL_CHANNEL) && onBufferOverflow == BufferOverflow.SUSPEND) {
+ return this
+ }
+ // Apply channel flow operator as usual
+ return ChannelFlowOperatorImpl(this, context, capacity, onBufferOverflow)
+}
diff --git a/kotlinx-coroutines-core/common/src/flow/SharingStarted.kt b/kotlinx-coroutines-core/common/src/flow/SharingStarted.kt
new file mode 100644
index 0000000..19e5fa3
--- /dev/null
+++ b/kotlinx-coroutines-core/common/src/flow/SharingStarted.kt
@@ -0,0 +1,210 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.flow
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.internal.*
+import kotlin.time.*
+
+/**
+ * A command emitted by [SharingStarted] implementations to control the sharing coroutine in
+ * the [shareIn] and [stateIn] operators.
+ */
+public enum class SharingCommand {
+ /**
+ * Starts sharing, launching collection of the upstream flow.
+ *
+ * Emitting this command again does not do anything. Emit [STOP] and then [START] to restart an
+ * upstream flow.
+ */
+ START,
+
+ /**
+ * Stops sharing, cancelling collection of the upstream flow.
+ */
+ STOP,
+
+ /**
+ * Stops sharing, cancelling collection of the upstream flow, and resets the [SharedFlow.replayCache]
+ * to its initial state.
+ * The [shareIn] operator calls [MutableSharedFlow.resetReplayCache];
+ * the [stateIn] operator resets the value to its original `initialValue`.
+ */
+ STOP_AND_RESET_REPLAY_CACHE
+}
+
+/**
+ * A strategy for starting and stopping the sharing coroutine in [shareIn] and [stateIn] operators.
+ *
+ * This interface provides a set of built-in strategies: [Eagerly], [Lazily], [WhileSubscribed], and
+ * supports custom strategies by implementing this interface's [command] function.
+ *
+ * For example, it is possible to define a custom strategy that starts the upstream only when the number
+ * of subscribers exceeds the given `threshold` and make it an extension on [SharingStarted.Companion] so
+ * that it looks like a built-in strategy on the use-site:
+ *
+ * ```
+ * fun SharingStarted.Companion.WhileSubscribedAtLeast(threshold: Int): SharingStarted =
+ * object : SharingStarted {
+ * override fun command(subscriptionCount: StateFlow<Int>): Flow<SharingCommand> =
+ * subscriptionCount
+ * .map { if (it >= threshold) SharingCommand.START else SharingCommand.STOP }
+ * }
+ * ```
+ *
+ * ### Commands
+ *
+ * The `SharingStarted` strategy works by emitting [commands][SharingCommand] that control upstream flow from its
+ * [`command`][command] flow implementation function. Back-to-back emissions of the same command have no effect.
+ * Only emission of a different command has effect:
+ *
+ * * [START][SharingCommand.START] — the upstream flow is stared.
+ * * [STOP][SharingCommand.STOP] — the upstream flow is stopped.
+ * * [STOP_AND_RESET_REPLAY_CACHE][SharingCommand.STOP_AND_RESET_REPLAY_CACHE] —
+ * the upstream flow is stopped and the [SharedFlow.replayCache] is reset to its initial state.
+ * The [shareIn] operator calls [MutableSharedFlow.resetReplayCache];
+ * the [stateIn] operator resets the value to its original `initialValue`.
+ *
+ * Initially, the upstream flow is stopped and is in the initial state, so the emission of additional
+ * [STOP][SharingCommand.STOP] and [STOP_AND_RESET_REPLAY_CACHE][SharingCommand.STOP_AND_RESET_REPLAY_CACHE] commands will
+ * have no effect.
+ *
+ * The completion of the `command` flow normally has no effect (the upstream flow keeps running if it was running).
+ * The failure of the `command` flow cancels the sharing coroutine and the upstream flow.
+ */
+public interface SharingStarted {
+ public companion object {
+ /**
+ * Sharing is started immediately and never stops.
+ */
+ public val Eagerly: SharingStarted = StartedEagerly()
+
+ /**
+ * Sharing is started when the first subscriber appears and never stops.
+ */
+ public val Lazily: SharingStarted = StartedLazily()
+
+ /**
+ * Sharing is started when the first subscriber appears, immediately stops when the last
+ * subscriber disappears (by default), keeping the replay cache forever (by default).
+ *
+ * It has the following optional parameters:
+ *
+ * * [stopTimeoutMillis] — configures a delay (in milliseconds) between the disappearance of the last
+ * subscriber and the stopping of the sharing coroutine. It defaults to zero (stop immediately).
+ * * [replayExpirationMillis] — configures a delay (in milliseconds) between the stopping of
+ * the sharing coroutine and the resetting of the replay cache (which makes the cache empty for the [shareIn] operator
+ * and resets the cached value to the original `initialValue` for the [stateIn] operator).
+ * It defaults to `Long.MAX_VALUE` (keep replay cache forever, never reset buffer).
+ * Use zero value to expire the cache immediately.
+ *
+ * This function throws [IllegalArgumentException] when either [stopTimeoutMillis] or [replayExpirationMillis]
+ * are negative.
+ */
+ @Suppress("FunctionName")
+ public fun WhileSubscribed(
+ stopTimeoutMillis: Long = 0,
+ replayExpirationMillis: Long = Long.MAX_VALUE
+ ): SharingStarted =
+ StartedWhileSubscribed(stopTimeoutMillis, replayExpirationMillis)
+ }
+
+ /**
+ * Transforms the [subscriptionCount][MutableSharedFlow.subscriptionCount] state of the shared flow into the
+ * flow of [commands][SharingCommand] that control the sharing coroutine. See the [SharingStarted] interface
+ * documentation for details.
+ */
+ public fun command(subscriptionCount: StateFlow<Int>): Flow<SharingCommand>
+}
+
+/**
+ * Sharing is started when the first subscriber appears, immediately stops when the last
+ * subscriber disappears (by default), keeping the replay cache forever (by default).
+ *
+ * It has the following optional parameters:
+ *
+ * * [stopTimeout] — configures a delay between the disappearance of the last
+ * subscriber and the stopping of the sharing coroutine. It defaults to zero (stop immediately).
+ * * [replayExpiration] — configures a delay between the stopping of
+ * the sharing coroutine and the resetting of the replay cache (which makes the cache empty for the [shareIn] operator
+ * and resets the cached value to the original `initialValue` for the [stateIn] operator).
+ * It defaults to [Duration.INFINITE] (keep replay cache forever, never reset buffer).
+ * Use [Duration.ZERO] value to expire the cache immediately.
+ *
+ * This function throws [IllegalArgumentException] when either [stopTimeout] or [replayExpiration]
+ * are negative.
+ */
+@Suppress("FunctionName")
+@ExperimentalTime
+public fun SharingStarted.Companion.WhileSubscribed(
+ stopTimeout: Duration = Duration.ZERO,
+ replayExpiration: Duration = Duration.INFINITE
+): SharingStarted =
+ StartedWhileSubscribed(stopTimeout.toLongMilliseconds(), replayExpiration.toLongMilliseconds())
+
+// -------------------------------- implementation --------------------------------
+
+private class StartedEagerly : SharingStarted {
+ override fun command(subscriptionCount: StateFlow<Int>): Flow<SharingCommand> =
+ flowOf(SharingCommand.START)
+ override fun toString(): String = "SharingStarted.Eagerly"
+}
+
+private class StartedLazily : SharingStarted {
+ override fun command(subscriptionCount: StateFlow<Int>): Flow<SharingCommand> = flow {
+ var started = false
+ subscriptionCount.collect { count ->
+ if (count > 0 && !started) {
+ started = true
+ emit(SharingCommand.START)
+ }
+ }
+ }
+
+ override fun toString(): String = "SharingStarted.Lazily"
+}
+
+private class StartedWhileSubscribed(
+ private val stopTimeout: Long,
+ private val replayExpiration: Long
+) : SharingStarted {
+ init {
+ require(stopTimeout >= 0) { "stopTimeout($stopTimeout ms) cannot be negative" }
+ require(replayExpiration >= 0) { "replayExpiration($replayExpiration ms) cannot be negative" }
+ }
+
+ override fun command(subscriptionCount: StateFlow<Int>): Flow<SharingCommand> = subscriptionCount
+ .transformLatest { count ->
+ if (count > 0) {
+ emit(SharingCommand.START)
+ } else {
+ delay(stopTimeout)
+ if (replayExpiration > 0) {
+ emit(SharingCommand.STOP)
+ delay(replayExpiration)
+ }
+ emit(SharingCommand.STOP_AND_RESET_REPLAY_CACHE)
+ }
+ }
+ .dropWhile { it != SharingCommand.START } // don't emit any STOP/RESET_BUFFER to start with, only START
+ .distinctUntilChanged() // just in case somebody forgets it, don't leak our multiple sending of START
+
+ @OptIn(ExperimentalStdlibApi::class)
+ override fun toString(): String {
+ val params = buildList(2) {
+ if (stopTimeout > 0) add("stopTimeout=${stopTimeout}ms")
+ if (replayExpiration < Long.MAX_VALUE) add("replayExpiration=${replayExpiration}ms")
+ }
+ return "SharingStarted.WhileSubscribed(${params.joinToString()})"
+ }
+
+ // equals & hashcode to facilitate testing, not documented in public contract
+ override fun equals(other: Any?): Boolean =
+ other is StartedWhileSubscribed &&
+ stopTimeout == other.stopTimeout &&
+ replayExpiration == other.replayExpiration
+
+ override fun hashCode(): Int = stopTimeout.hashCode() * 31 + replayExpiration.hashCode()
+}
diff --git a/kotlinx-coroutines-core/common/src/flow/StateFlow.kt b/kotlinx-coroutines-core/common/src/flow/StateFlow.kt
index b2bbb6d..a9a4ed3 100644
--- a/kotlinx-coroutines-core/common/src/flow/StateFlow.kt
+++ b/kotlinx-coroutines-core/common/src/flow/StateFlow.kt
@@ -13,9 +13,12 @@
import kotlin.native.concurrent.*
/**
- * A [Flow] that represents a read-only state with a single updatable data [value] that emits updates
- * to the value to its collectors. The current value can be retrieved via [value] property.
- * The flow of future updates to the value can be observed by collecting values from this flow.
+ * A [SharedFlow] that represents a read-only state with a single updatable data [value] that emits updates
+ * to the value to its collectors. A state flow is a _hot_ flow because its active instance exists independently
+ * of the presence of collectors. Its current value can be retrieved via the [value] property.
+ *
+ * **State flow never completes**. A call to [Flow.collect] on a state flow never completes normally, and
+ * neither does a coroutine started by the [Flow.launchIn] function. An active collector of a state flow is called a _subscriber_.
*
* A [mutable state flow][MutableStateFlow] is created using `MutableStateFlow(value)` constructor function with
* the initial value. The value of mutable state flow can be updated by setting its [value] property.
@@ -31,7 +34,7 @@
* ```
* class CounterModel {
* private val _counter = MutableStateFlow(0) // private mutable state flow
- * val counter: StateFlow<Int> get() = _counter // publicly exposed as read-only state flow
+ * val counter = _counter.asStateFlow() // publicly exposed as read-only state flow
*
* fun inc() {
* _counter.value++
@@ -47,6 +50,9 @@
* val sumFlow: Flow<Int> = aModel.counter.combine(bModel.counter) { a, b -> a + b }
* ```
*
+ * As an alternative to the above usage with the `MutableStateFlow(...)` constructor function,
+ * any _cold_ [Flow] can be converted to a state flow using the [stateIn] operator.
+ *
* ### Strong equality-based conflation
*
* Values in state flow are conflated using [Any.equals] comparison in a similar way to
@@ -55,12 +61,35 @@
* when new value is equal to the previously emitted one. State flow behavior with classes that violate
* the contract for [Any.equals] is unspecified.
*
+ * ### State flow is a shared flow
+ *
+ * State flow is a special-purpose, high-performance, and efficient implementation of [SharedFlow] for the narrow,
+ * but widely used case of sharing a state. See the [SharedFlow] documentation for the basic rules,
+ * constraints, and operators that are applicable to all shared flows.
+ *
+ * State flow always has an initial value, replays one most recent value to new subscribers, does not buffer any
+ * more values, but keeps the last emitted one, and does not support [resetReplayCache][MutableSharedFlow.resetReplayCache].
+ * A state flow behaves identically to a shared flow when it is created
+ * with the following parameters and the [distinctUntilChanged] operator is applied to it:
+ *
+ * ```
+ * // MutableStateFlow(initialValue) is a shared flow with the following parameters:
+ * val shared = MutableSharedFlow(
+ * replay = 1,
+ * onBufferOverflow = BufferOverflow.DROP_OLDEST
+ * )
+ * shared.tryEmit(initialValue) // emit the initial value
+ * val state = shared.distinctUntilChanged() // get StateFlow-like behavior
+ * ```
+ *
+ * Use [SharedFlow] when you need a [StateFlow] with tweaks in its behavior such as extra buffering, replaying more
+ * values, or omitting the initial value.
+ *
* ### StateFlow vs ConflatedBroadcastChannel
*
- * Conceptually state flow is similar to
- * [ConflatedBroadcastChannel][kotlinx.coroutines.channels.ConflatedBroadcastChannel]
+ * Conceptually, state flow is similar to [ConflatedBroadcastChannel]
* and is designed to completely replace `ConflatedBroadcastChannel` in the future.
- * It has the following important difference:
+ * It has the following important differences:
*
* * `StateFlow` is simpler, because it does not have to implement all the [Channel] APIs, which allows
* for faster, garbage-free implementation, unlike `ConflatedBroadcastChannel` implementation that
@@ -70,38 +99,43 @@
* * `StateFlow` has a clear separation into a read-only `StateFlow` interface and a [MutableStateFlow].
* * `StateFlow` conflation is based on equality like [distinctUntilChanged] operator,
* unlike conflation in `ConflatedBroadcastChannel` that is based on reference identity.
- * * `StateFlow` cannot be currently closed like `ConflatedBroadcastChannel` and can never represent a failure.
- * This feature might be added in the future if enough compelling use-cases are found.
+ * * `StateFlow` cannot be closed like `ConflatedBroadcastChannel` and can never represent a failure.
+ * All errors and completion signals should be explicitly _materialized_ if needed.
*
* `StateFlow` is designed to better cover typical use-cases of keeping track of state changes in time, taking
* more pragmatic design choices for the sake of convenience.
*
+ * To migrate [ConflatedBroadcastChannel] usage to [StateFlow], start by replacing usages of the `ConflatedBroadcastChannel()`
+ * constructor with `MutableStateFlow(initialValue)`, using `null` as an initial value if you don't have one.
+ * Replace [send][ConflatedBroadcastChannel.send] and [offer][ConflatedBroadcastChannel.offer] calls
+ * with updates to the state flow's [MutableStateFlow.value], and convert subscribers' code to flow operators.
+ * You can use the [filterNotNull] operator to mimic behavior of a `ConflatedBroadcastChannel` without initial value.
+ *
* ### Concurrency
*
- * All methods of data flow are **thread-safe** and can be safely invoked from concurrent coroutines without
+ * All methods of state flow are **thread-safe** and can be safely invoked from concurrent coroutines without
* external synchronization.
*
* ### Operator fusion
*
* Application of [flowOn][Flow.flowOn], [conflate][Flow.conflate],
* [buffer] with [CONFLATED][Channel.CONFLATED] or [RENDEZVOUS][Channel.RENDEZVOUS] capacity,
- * or a [distinctUntilChanged][Flow.distinctUntilChanged] operator has no effect on the state flow.
+ * [distinctUntilChanged][Flow.distinctUntilChanged], or [cancellable] operators to a state flow has no effect.
*
* ### Implementation notes
*
* State flow implementation is optimized for memory consumption and allocation-freedom. It uses a lock to ensure
* thread-safety, but suspending collector coroutines are resumed outside of this lock to avoid dead-locks when
- * using unconfined coroutines. Adding new collectors has `O(1)` amortized cost, but updating a [value] has `O(N)`
- * cost, where `N` is the number of active collectors.
+ * using unconfined coroutines. Adding new subscribers has `O(1)` amortized cost, but updating a [value] has `O(N)`
+ * cost, where `N` is the number of active subscribers.
*
* ### Not stable for inheritance
*
- * **`StateFlow` interface is not stable for inheritance in 3rd party libraries**, as new methods
+ * **`The StateFlow` interface is not stable for inheritance in 3rd party libraries**, as new methods
* might be added to this interface in the future, but is stable for use.
- * Use `MutableStateFlow()` constructor function to create an implementation.
+ * Use the `MutableStateFlow(value)` constructor function to create an implementation.
*/
-@ExperimentalCoroutinesApi
-public interface StateFlow<out T> : Flow<T> {
+public interface StateFlow<out T> : SharedFlow<T> {
/**
* The current value of this state flow.
*/
@@ -110,30 +144,40 @@
/**
* A mutable [StateFlow] that provides a setter for [value].
+ * An instance of `MutableStateFlow` with the given initial `value` can be created using
+ * `MutableStateFlow(value)` constructor function.
*
- * See [StateFlow] documentation for details.
+ * See the [StateFlow] documentation for details on state flows.
*
* ### Not stable for inheritance
*
- * **`MutableStateFlow` interface is not stable for inheritance in 3rd party libraries**, as new methods
+ * **The `MutableStateFlow` interface is not stable for inheritance in 3rd party libraries**, as new methods
* might be added to this interface in the future, but is stable for use.
- * Use `MutableStateFlow()` constructor function to create an implementation.
+ * Use the `MutableStateFlow()` constructor function to create an implementation.
*/
-@ExperimentalCoroutinesApi
-public interface MutableStateFlow<T> : StateFlow<T> {
+public interface MutableStateFlow<T> : StateFlow<T>, MutableSharedFlow<T> {
/**
* The current value of this state flow.
*
* Setting a value that is [equal][Any.equals] to the previous one does nothing.
*/
public override var value: T
+
+ /**
+ * Atomically compares the current [value] with [expect] and sets it to [update] if it is equal to [expect].
+ * The result is `true` if the [value] was set to [update] and `false` otherwise.
+ *
+ * This function use a regular comparison using [Any.equals]. If both [expect] and [update] are equal to the
+ * current [value], this function returns `true`, but it does not actually change the reference that is
+ * stored in the [value].
+ */
+ public fun compareAndSet(expect: T, update: T): Boolean
}
/**
* Creates a [MutableStateFlow] with the given initial [value].
*/
@Suppress("FunctionName")
-@ExperimentalCoroutinesApi
public fun <T> MutableStateFlow(value: T): MutableStateFlow<T> = StateFlowImpl(value ?: NULL)
// ------------------------------------ Implementation ------------------------------------
@@ -144,14 +188,12 @@
@SharedImmutable
private val PENDING = Symbol("PENDING")
-private const val INITIAL_SIZE = 2 // optimized for just a few collectors
-
// StateFlow slots are allocated for its collectors
-private class StateFlowSlot {
+private class StateFlowSlot : AbstractSharedFlowSlot<StateFlowImpl<*>>() {
/**
* Each slot can have one of the following states:
*
- * * `null` -- it is not used right now. Can [allocate] to new collector.
+ * * `null` -- it is not used right now. Can [allocateLocked] to new collector.
* * `NONE` -- used by a collector, but neither suspended nor has pending value.
* * `PENDING` -- pending to process new value.
* * `CancellableContinuationImpl<Unit>` -- suspended waiting for new value.
@@ -161,15 +203,16 @@
*/
private val _state = atomic<Any?>(null)
- fun allocate(): Boolean {
+ override fun allocateLocked(flow: StateFlowImpl<*>): Boolean {
// No need for atomic check & update here, since allocated happens under StateFlow lock
if (_state.value != null) return false // not free
_state.value = NONE // allocated
return true
}
- fun free() {
+ override fun freeLocked(flow: StateFlowImpl<*>): Array<Continuation<Unit>?> {
_state.value = null // free now
+ return EMPTY_RESUMES // nothing more to do
}
@Suppress("UNCHECKED_CAST")
@@ -207,72 +250,97 @@
}
}
-private class StateFlowImpl<T>(initialValue: Any) : SynchronizedObject(), MutableStateFlow<T>, FusibleFlow<T> {
- private val _state = atomic(initialValue) // T | NULL
+private class StateFlowImpl<T>(
+ initialState: Any // T | NULL
+) : AbstractSharedFlow<StateFlowSlot>(), MutableStateFlow<T>, CancellableFlow<T>, FusibleFlow<T> {
+ private val _state = atomic(initialState) // T | NULL
private var sequence = 0 // serializes updates, value update is in process when sequence is odd
- private var slots = arrayOfNulls<StateFlowSlot?>(INITIAL_SIZE)
- private var nSlots = 0 // number of allocated (!free) slots
- private var nextIndex = 0 // oracle for the next free slot index
@Suppress("UNCHECKED_CAST")
public override var value: T
get() = NULL.unbox(_state.value)
- set(value) {
- var curSequence = 0
- var curSlots: Array<StateFlowSlot?> = this.slots // benign race, we will not use it
- val newState = value ?: NULL
- synchronized(this) {
- val oldState = _state.value
- if (oldState == newState) return // Don't do anything if value is not changing
- _state.value = newState
- curSequence = sequence
- if (curSequence and 1 == 0) { // even sequence means quiescent state flow (no ongoing update)
- curSequence++ // make it odd
- sequence = curSequence
- } else {
- // update is already in process, notify it, and return
- sequence = curSequence + 2 // change sequence to notify, keep it odd
- return
- }
- curSlots = slots // read current reference to collectors under lock
+ set(value) { updateState(null, value ?: NULL) }
+
+ override fun compareAndSet(expect: T, update: T): Boolean =
+ updateState(expect ?: NULL, update ?: NULL)
+
+ private fun updateState(expectedState: Any?, newState: Any): Boolean {
+ var curSequence = 0
+ var curSlots: Array<StateFlowSlot?>? = this.slots // benign race, we will not use it
+ synchronized(this) {
+ val oldState = _state.value
+ if (expectedState != null && oldState != expectedState) return false // CAS support
+ if (oldState == newState) return true // Don't do anything if value is not changing, but CAS -> true
+ _state.value = newState
+ curSequence = sequence
+ if (curSequence and 1 == 0) { // even sequence means quiescent state flow (no ongoing update)
+ curSequence++ // make it odd
+ sequence = curSequence
+ } else {
+ // update is already in process, notify it, and return
+ sequence = curSequence + 2 // change sequence to notify, keep it odd
+ return true // updated
}
- /*
- Fire value updates outside of the lock to avoid deadlocks with unconfined coroutines
- Loop until we're done firing all the changes. This is sort of simple flat combining that
- ensures sequential firing of concurrent updates and avoids the storm of collector resumes
- when updates happen concurrently from many threads.
- */
- while (true) {
- // Benign race on element read from array
- for (col in curSlots) {
- col?.makePending()
+ curSlots = slots // read current reference to collectors under lock
+ }
+ /*
+ Fire value updates outside of the lock to avoid deadlocks with unconfined coroutines.
+ Loop until we're done firing all the changes. This is a sort of simple flat combining that
+ ensures sequential firing of concurrent updates and avoids the storm of collector resumes
+ when updates happen concurrently from many threads.
+ */
+ while (true) {
+ // Benign race on element read from array
+ curSlots?.forEach {
+ it?.makePending()
+ }
+ // check if the value was updated again while we were updating the old one
+ synchronized(this) {
+ if (sequence == curSequence) { // nothing changed, we are done
+ sequence = curSequence + 1 // make sequence even again
+ return true // done, updated
}
- // check if the value was updated again while we were updating the old one
- synchronized(this) {
- if (sequence == curSequence) { // nothing changed, we are done
- sequence = curSequence + 1 // make sequence even again
- return // done
- }
- // reread everything for the next loop under the lock
- curSequence = sequence
- curSlots = slots
- }
+ // reread everything for the next loop under the lock
+ curSequence = sequence
+ curSlots = slots
}
}
+ }
+
+ override val replayCache: List<T>
+ get() = listOf(value)
+
+ override fun tryEmit(value: T): Boolean {
+ this.value = value
+ return true
+ }
+
+ override suspend fun emit(value: T) {
+ this.value = value
+ }
+
+ @Suppress("UNCHECKED_CAST")
+ override fun resetReplayCache() {
+ throw UnsupportedOperationException("MutableStateFlow.resetReplayCache is not supported")
+ }
override suspend fun collect(collector: FlowCollector<T>) {
val slot = allocateSlot()
- var prevState: Any? = null // previously emitted T!! | NULL (null -- nothing emitted yet)
try {
+ if (collector is SubscribedFlowCollector) collector.onSubscription()
+ val collectorJob = currentCoroutineContext()[Job]
+ var oldState: Any? = null // previously emitted T!! | NULL (null -- nothing emitted yet)
// The loop is arranged so that it starts delivering current value without waiting first
while (true) {
// Here the coroutine could have waited for a while to be dispatched,
// so we use the most recent state here to ensure the best possible conflation of stale values
val newState = _state.value
+ // always check for cancellation
+ collectorJob?.ensureActive()
// Conflate value emissions using equality
- if (prevState == null || newState != prevState) {
+ if (oldState == null || oldState != newState) {
collector.emit(NULL.unbox(newState))
- prevState = newState
+ oldState = newState
}
// Note: if awaitPending is cancelled, then it bails out of this loop and calls freeSlot
if (!slot.takePending()) { // try fast-path without suspending first
@@ -284,33 +352,29 @@
}
}
- private fun allocateSlot(): StateFlowSlot = synchronized(this) {
- val size = slots.size
- if (nSlots >= size) slots = slots.copyOf(2 * size)
- var index = nextIndex
- var slot: StateFlowSlot
- while (true) {
- slot = slots[index] ?: StateFlowSlot().also { slots[index] = it }
- index++
- if (index >= slots.size) index = 0
- if (slot.allocate()) break // break when found and allocated free slot
- }
- nextIndex = index
- nSlots++
- slot
- }
+ override fun createSlot() = StateFlowSlot()
+ override fun createSlotArray(size: Int): Array<StateFlowSlot?> = arrayOfNulls(size)
- private fun freeSlot(slot: StateFlowSlot): Unit = synchronized(this) {
- slot.free()
- nSlots--
- }
+ override fun fuse(context: CoroutineContext, capacity: Int, onBufferOverflow: BufferOverflow) =
+ fuseStateFlow(context, capacity, onBufferOverflow)
+}
- override fun fuse(context: CoroutineContext, capacity: Int): FusibleFlow<T> {
- // context is irrelevant for state flow and it is always conflated
- // so it should not do anything unless buffering is requested
- return when (capacity) {
- Channel.CONFLATED, Channel.RENDEZVOUS -> this
- else -> ChannelFlowOperatorImpl(this, context, capacity)
- }
+internal fun MutableStateFlow<Int>.increment(delta: Int) {
+ while (true) { // CAS loop
+ val current = value
+ if (compareAndSet(current, current + delta)) return
}
}
+
+internal fun <T> StateFlow<T>.fuseStateFlow(
+ context: CoroutineContext,
+ capacity: Int,
+ onBufferOverflow: BufferOverflow
+): Flow<T> {
+ // state flow is always conflated so additional conflation does not have any effect
+ assert { capacity != Channel.CONFLATED } // should be desugared by callers
+ if ((capacity in 0..1 || capacity == Channel.BUFFERED) && onBufferOverflow == BufferOverflow.DROP_OLDEST) {
+ return this
+ }
+ return fuseSharedFlow(context, capacity, onBufferOverflow)
+}
diff --git a/kotlinx-coroutines-core/common/src/flow/internal/AbstractSharedFlow.kt b/kotlinx-coroutines-core/common/src/flow/internal/AbstractSharedFlow.kt
new file mode 100644
index 0000000..ccb5343
--- /dev/null
+++ b/kotlinx-coroutines-core/common/src/flow/internal/AbstractSharedFlow.kt
@@ -0,0 +1,101 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.flow.internal
+
+import kotlinx.coroutines.flow.*
+import kotlinx.coroutines.internal.*
+import kotlin.coroutines.*
+import kotlin.jvm.*
+import kotlin.native.concurrent.*
+
+@JvmField
+@SharedImmutable
+internal val EMPTY_RESUMES = arrayOfNulls<Continuation<Unit>?>(0)
+
+internal abstract class AbstractSharedFlowSlot<F> {
+ abstract fun allocateLocked(flow: F): Boolean
+ abstract fun freeLocked(flow: F): Array<Continuation<Unit>?> // returns continuations to resume after lock
+}
+
+internal abstract class AbstractSharedFlow<S : AbstractSharedFlowSlot<*>> : SynchronizedObject() {
+ @Suppress("UNCHECKED_CAST")
+ protected var slots: Array<S?>? = null // allocated when needed
+ private set
+ protected var nCollectors = 0 // number of allocated (!free) slots
+ private set
+ private var nextIndex = 0 // oracle for the next free slot index
+ private var _subscriptionCount: MutableStateFlow<Int>? = null // init on first need
+
+ val subscriptionCount: StateFlow<Int>
+ get() = synchronized(this) {
+ // allocate under lock in sync with nCollectors variable
+ _subscriptionCount ?: MutableStateFlow(nCollectors).also {
+ _subscriptionCount = it
+ }
+ }
+
+ protected abstract fun createSlot(): S
+
+ protected abstract fun createSlotArray(size: Int): Array<S?>
+
+ @Suppress("UNCHECKED_CAST")
+ protected fun allocateSlot(): S {
+ // Actually create slot under lock
+ var subscriptionCount: MutableStateFlow<Int>? = null
+ val slot = synchronized(this) {
+ val slots = when (val curSlots = slots) {
+ null -> createSlotArray(2).also { slots = it }
+ else -> if (nCollectors >= curSlots.size) {
+ curSlots.copyOf(2 * curSlots.size).also { slots = it }
+ } else {
+ curSlots
+ }
+ }
+ var index = nextIndex
+ var slot: S
+ while (true) {
+ slot = slots[index] ?: createSlot().also { slots[index] = it }
+ index++
+ if (index >= slots.size) index = 0
+ if ((slot as AbstractSharedFlowSlot<Any>).allocateLocked(this)) break // break when found and allocated free slot
+ }
+ nextIndex = index
+ nCollectors++
+ subscriptionCount = _subscriptionCount // retrieve under lock if initialized
+ slot
+ }
+ // increments subscription count
+ subscriptionCount?.increment(1)
+ return slot
+ }
+
+ @Suppress("UNCHECKED_CAST")
+ protected fun freeSlot(slot: S) {
+ // Release slot under lock
+ var subscriptionCount: MutableStateFlow<Int>? = null
+ val resumes = synchronized(this) {
+ nCollectors--
+ subscriptionCount = _subscriptionCount // retrieve under lock if initialized
+ // Reset next index oracle if we have no more active collectors for more predictable behavior next time
+ if (nCollectors == 0) nextIndex = 0
+ (slot as AbstractSharedFlowSlot<Any>).freeLocked(this)
+ }
+ /*
+ Resume suspended coroutines.
+ This can happens when the subscriber that was freed was a slow one and was holding up buffer.
+ When this subscriber was freed, previously queued emitted can now wake up and are resumed here.
+ */
+ for (cont in resumes) cont?.resume(Unit)
+ // decrement subscription count
+ subscriptionCount?.increment(-1)
+ }
+
+ protected inline fun forEachSlotLocked(block: (S) -> Unit) {
+ if (nCollectors == 0) return
+ slots?.forEach { slot ->
+ if (slot != null) block(slot)
+ }
+ }
+}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/common/src/flow/internal/ChannelFlow.kt b/kotlinx-coroutines-core/common/src/flow/internal/ChannelFlow.kt
index 994d380..f3730cc 100644
--- a/kotlinx-coroutines-core/common/src/flow/internal/ChannelFlow.kt
+++ b/kotlinx-coroutines-core/common/src/flow/internal/ChannelFlow.kt
@@ -16,7 +16,7 @@
this as? ChannelFlow ?: ChannelFlowOperatorImpl(this)
/**
- * Operators that can fuse with [buffer] and [flowOn] operators implement this interface.
+ * Operators that can fuse with **downstream** [buffer] and [flowOn] operators implement this interface.
*
* @suppress **This an internal API and should not be used from general code.**
*/
@@ -24,16 +24,18 @@
public interface FusibleFlow<T> : Flow<T> {
/**
* This function is called by [flowOn] (with context) and [buffer] (with capacity) operators
- * that are applied to this flow.
+ * that are applied to this flow. Should not be used with [capacity] of [Channel.CONFLATED]
+ * (it shall be desugared to `capacity = 0, onBufferOverflow = DROP_OLDEST`).
*/
public fun fuse(
context: CoroutineContext = EmptyCoroutineContext,
- capacity: Int = Channel.OPTIONAL_CHANNEL
- ): FusibleFlow<T>
+ capacity: Int = Channel.OPTIONAL_CHANNEL,
+ onBufferOverflow: BufferOverflow = BufferOverflow.SUSPEND
+ ): Flow<T>
}
/**
- * Operators that use channels extend this `ChannelFlow` and are always fused with each other.
+ * Operators that use channels as their "output" extend this `ChannelFlow` and are always fused with each other.
* This class servers as a skeleton implementation of [FusibleFlow] and provides other cross-cutting
* methods like ability to [produceIn] and [broadcastIn] the corresponding flow, thus making it
* possible to directly use the backing channel if it exists (hence the `ChannelFlow` name).
@@ -45,8 +47,13 @@
// upstream context
@JvmField public val context: CoroutineContext,
// buffer capacity between upstream and downstream context
- @JvmField public val capacity: Int
+ @JvmField public val capacity: Int,
+ // buffer overflow strategy
+ @JvmField public val onBufferOverflow: BufferOverflow
) : FusibleFlow<T> {
+ init {
+ assert { capacity != Channel.CONFLATED } // CONFLATED must be desugared to 0, DROP_OLDEST by callers
+ }
// shared code to create a suspend lambda from collectTo function in one place
internal val collectToFun: suspend (ProducerScope<T>) -> Unit
@@ -55,35 +62,62 @@
private val produceCapacity: Int
get() = if (capacity == Channel.OPTIONAL_CHANNEL) Channel.BUFFERED else capacity
- public override fun fuse(context: CoroutineContext, capacity: Int): FusibleFlow<T> {
+ /**
+ * When this [ChannelFlow] implementation can work without a channel (supports [Channel.OPTIONAL_CHANNEL]),
+ * then it should return a non-null value from this function, so that a caller can use it without the effect of
+ * additional [flowOn] and [buffer] operators, by incorporating its
+ * [context], [capacity], and [onBufferOverflow] into its own implementation.
+ */
+ public open fun dropChannelOperators(): Flow<T>? = null
+
+ public override fun fuse(context: CoroutineContext, capacity: Int, onBufferOverflow: BufferOverflow): Flow<T> {
+ assert { capacity != Channel.CONFLATED } // CONFLATED must be desugared to (0, DROP_OLDEST) by callers
// note: previous upstream context (specified before) takes precedence
val newContext = context + this.context
- val newCapacity = when {
- this.capacity == Channel.OPTIONAL_CHANNEL -> capacity
- capacity == Channel.OPTIONAL_CHANNEL -> this.capacity
- this.capacity == Channel.BUFFERED -> capacity
- capacity == Channel.BUFFERED -> this.capacity
- this.capacity == Channel.CONFLATED -> Channel.CONFLATED
- capacity == Channel.CONFLATED -> Channel.CONFLATED
- else -> {
- // sanity checks
- assert { this.capacity >= 0 }
- assert { capacity >= 0 }
- // combine capacities clamping to UNLIMITED on overflow
- val sum = this.capacity + capacity
- if (sum >= 0) sum else Channel.UNLIMITED // unlimited on int overflow
+ val newCapacity: Int
+ val newOverflow: BufferOverflow
+ if (onBufferOverflow != BufferOverflow.SUSPEND) {
+ // this additional buffer never suspends => overwrite preceding buffering configuration
+ newCapacity = capacity
+ newOverflow = onBufferOverflow
+ } else {
+ // combine capacities, keep previous overflow strategy
+ newCapacity = when {
+ this.capacity == Channel.OPTIONAL_CHANNEL -> capacity
+ capacity == Channel.OPTIONAL_CHANNEL -> this.capacity
+ this.capacity == Channel.BUFFERED -> capacity
+ capacity == Channel.BUFFERED -> this.capacity
+ else -> {
+ // sanity checks
+ assert { this.capacity >= 0 }
+ assert { capacity >= 0 }
+ // combine capacities clamping to UNLIMITED on overflow
+ val sum = this.capacity + capacity
+ if (sum >= 0) sum else Channel.UNLIMITED // unlimited on int overflow
+ }
}
+ newOverflow = this.onBufferOverflow
}
- if (newContext == this.context && newCapacity == this.capacity) return this
- return create(newContext, newCapacity)
+ if (newContext == this.context && newCapacity == this.capacity && newOverflow == this.onBufferOverflow)
+ return this
+ return create(newContext, newCapacity, newOverflow)
}
- protected abstract fun create(context: CoroutineContext, capacity: Int): ChannelFlow<T>
+ protected abstract fun create(context: CoroutineContext, capacity: Int, onBufferOverflow: BufferOverflow): ChannelFlow<T>
protected abstract suspend fun collectTo(scope: ProducerScope<T>)
- public open fun broadcastImpl(scope: CoroutineScope, start: CoroutineStart): BroadcastChannel<T> =
- scope.broadcast(context, produceCapacity, start, block = collectToFun)
+ // broadcastImpl is used in broadcastIn operator which is obsolete and replaced by SharedFlow.
+ // BroadcastChannel does not support onBufferOverflow beyond simple conflation
+ public open fun broadcastImpl(scope: CoroutineScope, start: CoroutineStart): BroadcastChannel<T> {
+ val broadcastCapacity = when (onBufferOverflow) {
+ BufferOverflow.SUSPEND -> produceCapacity
+ BufferOverflow.DROP_OLDEST -> Channel.CONFLATED
+ BufferOverflow.DROP_LATEST ->
+ throw IllegalArgumentException("Broadcast channel does not support BufferOverflow.DROP_LATEST")
+ }
+ return scope.broadcast(context, broadcastCapacity, start, block = collectToFun)
+ }
/**
* Here we use ATOMIC start for a reason (#1825).
@@ -94,26 +128,33 @@
* Thus `onCompletion` and `finally` blocks won't be executed and it may lead to a different kinds of memory leaks.
*/
public open fun produceImpl(scope: CoroutineScope): ReceiveChannel<T> =
- scope.produce(context, produceCapacity, start = CoroutineStart.ATOMIC, block = collectToFun)
+ scope.produce(context, produceCapacity, onBufferOverflow, start = CoroutineStart.ATOMIC, block = collectToFun)
override suspend fun collect(collector: FlowCollector<T>): Unit =
coroutineScope {
collector.emitAll(produceImpl(this))
}
- public open fun additionalToStringProps(): String = ""
+ protected open fun additionalToStringProps(): String? = null
// debug toString
- override fun toString(): String =
- "$classSimpleName[${additionalToStringProps()}context=$context, capacity=$capacity]"
+ override fun toString(): String {
+ val props = ArrayList<String>(4)
+ additionalToStringProps()?.let { props.add(it) }
+ if (context !== EmptyCoroutineContext) props.add("context=$context")
+ if (capacity != Channel.OPTIONAL_CHANNEL) props.add("capacity=$capacity")
+ if (onBufferOverflow != BufferOverflow.SUSPEND) props.add("onBufferOverflow=$onBufferOverflow")
+ return "$classSimpleName[${props.joinToString(", ")}]"
+ }
}
// ChannelFlow implementation that operates on another flow before it
internal abstract class ChannelFlowOperator<S, T>(
- @JvmField val flow: Flow<S>,
+ @JvmField protected val flow: Flow<S>,
context: CoroutineContext,
- capacity: Int
-) : ChannelFlow<T>(context, capacity) {
+ capacity: Int,
+ onBufferOverflow: BufferOverflow
+) : ChannelFlow<T>(context, capacity, onBufferOverflow) {
protected abstract suspend fun flowCollect(collector: FlowCollector<T>)
// Changes collecting context upstream to the specified newContext, while collecting in the original context
@@ -148,14 +189,19 @@
override fun toString(): String = "$flow -> ${super.toString()}"
}
-// Simple channel flow operator: flowOn, buffer, or their fused combination
+/**
+ * Simple channel flow operator: [flowOn], [buffer], or their fused combination.
+ */
internal class ChannelFlowOperatorImpl<T>(
flow: Flow<T>,
context: CoroutineContext = EmptyCoroutineContext,
- capacity: Int = Channel.OPTIONAL_CHANNEL
-) : ChannelFlowOperator<T, T>(flow, context, capacity) {
- override fun create(context: CoroutineContext, capacity: Int): ChannelFlow<T> =
- ChannelFlowOperatorImpl(flow, context, capacity)
+ capacity: Int = Channel.OPTIONAL_CHANNEL,
+ onBufferOverflow: BufferOverflow = BufferOverflow.SUSPEND
+) : ChannelFlowOperator<T, T>(flow, context, capacity, onBufferOverflow) {
+ override fun create(context: CoroutineContext, capacity: Int, onBufferOverflow: BufferOverflow): ChannelFlow<T> =
+ ChannelFlowOperatorImpl(flow, context, capacity, onBufferOverflow)
+
+ override fun dropChannelOperators(): Flow<T>? = flow
override suspend fun flowCollect(collector: FlowCollector<T>) =
flow.collect(collector)
@@ -178,19 +224,33 @@
private val emitRef: suspend (T) -> Unit = { downstream.emit(it) } // allocate suspend function ref once on creation
override suspend fun emit(value: T): Unit =
- withContextUndispatched(emitContext, countOrElement, emitRef, value)
+ withContextUndispatched(emitContext, value, countOrElement, emitRef)
}
// Efficiently computes block(value) in the newContext
-private suspend fun <T, V> withContextUndispatched(
+internal suspend fun <T, V> withContextUndispatched(
newContext: CoroutineContext,
+ value: V,
countOrElement: Any = threadContextElements(newContext), // can be precomputed for speed
- block: suspend (V) -> T, value: V
+ block: suspend (V) -> T
): T =
suspendCoroutineUninterceptedOrReturn { uCont ->
withCoroutineContext(newContext, countOrElement) {
- block.startCoroutineUninterceptedOrReturn(value, Continuation(newContext) {
- uCont.resumeWith(it)
- })
+ block.startCoroutineUninterceptedOrReturn(value, StackFrameContinuation(uCont, newContext))
}
}
+
+// Continuation that links the caller with uCont with walkable CoroutineStackFrame
+private class StackFrameContinuation<T>(
+ private val uCont: Continuation<T>, override val context: CoroutineContext
+) : Continuation<T>, CoroutineStackFrame {
+
+ override val callerFrame: CoroutineStackFrame?
+ get() = uCont as? CoroutineStackFrame
+
+ override fun resumeWith(result: Result<T>) {
+ uCont.resumeWith(result)
+ }
+
+ override fun getStackTraceElement(): StackTraceElement? = null
+}
diff --git a/kotlinx-coroutines-core/common/src/flow/internal/Combine.kt b/kotlinx-coroutines-core/common/src/flow/internal/Combine.kt
index 67da32c..bbdebd0 100644
--- a/kotlinx-coroutines-core/common/src/flow/internal/Combine.kt
+++ b/kotlinx-coroutines-core/common/src/flow/internal/Combine.kt
@@ -9,133 +9,135 @@
import kotlinx.coroutines.channels.*
import kotlinx.coroutines.flow.*
import kotlinx.coroutines.internal.*
-import kotlinx.coroutines.selects.*
+import kotlin.coroutines.*
+import kotlin.coroutines.intrinsics.*
-internal fun getNull(): Symbol = NULL // Workaround for JS BE bug
-
-internal suspend fun <T1, T2, R> FlowCollector<R>.combineTransformInternal(
- first: Flow<T1>, second: Flow<T2>,
- transform: suspend FlowCollector<R>.(a: T1, b: T2) -> Unit
-) {
- coroutineScope {
- val firstChannel = asFairChannel(first)
- val secondChannel = asFairChannel(second)
- var firstValue: Any? = null
- var secondValue: Any? = null
- var firstIsClosed = false
- var secondIsClosed = false
- while (!firstIsClosed || !secondIsClosed) {
- select<Unit> {
- onReceive(firstIsClosed, firstChannel, { firstIsClosed = true }) { value ->
- firstValue = value
- if (secondValue !== null) {
- transform(getNull().unbox(firstValue), getNull().unbox(secondValue) as T2)
- }
- }
-
- onReceive(secondIsClosed, secondChannel, { secondIsClosed = true }) { value ->
- secondValue = value
- if (firstValue !== null) {
- transform(getNull().unbox(firstValue) as T1, getNull().unbox(secondValue) as T2)
- }
- }
- }
- }
- }
-}
+private typealias Update = IndexedValue<Any?>
@PublishedApi
internal suspend fun <R, T> FlowCollector<R>.combineInternal(
flows: Array<out Flow<T>>,
- arrayFactory: () -> Array<T?>,
+ arrayFactory: () -> Array<T?>?, // Array factory is required to workaround array typing on JVM
transform: suspend FlowCollector<R>.(Array<T>) -> Unit
-): Unit = coroutineScope {
+): Unit = flowScope { // flow scope so any cancellation within the source flow will cancel the whole scope
val size = flows.size
- val channels = Array(size) { asFairChannel(flows[it]) }
+ if (size == 0) return@flowScope // bail-out for empty input
val latestValues = arrayOfNulls<Any?>(size)
- val isClosed = Array(size) { false }
- var nonClosed = size
- var remainingNulls = size
- // See flow.combine(other) for explanation.
- while (nonClosed != 0) {
- select<Unit> {
- for (i in 0 until size) {
- onReceive(isClosed[i], channels[i], { isClosed[i] = true; --nonClosed }) { value ->
- if (latestValues[i] == null) --remainingNulls
- latestValues[i] = value
- if (remainingNulls != 0) return@onReceive
- val arguments = arrayFactory()
- for (index in 0 until size) {
- arguments[index] = NULL.unbox(latestValues[index])
+ latestValues.fill(UNINITIALIZED) // Smaller bytecode & faster that Array(size) { UNINITIALIZED }
+ val resultChannel = Channel<Update>(size)
+ val nonClosed = LocalAtomicInt(size)
+ var remainingAbsentValues = size
+ for (i in 0 until size) {
+ // Coroutine per flow that keeps track of its value and sends result to downstream
+ launch {
+ try {
+ flows[i].collect { value ->
+ resultChannel.send(Update(i, value))
+ yield() // Emulate fairness, giving each flow chance to emit
+ }
+ } finally {
+ // Close the channel when there is no more flows
+ if (nonClosed.decrementAndGet() == 0) {
+ resultChannel.close()
+ }
+ }
+ }
+ }
+
+ /*
+ * Batch-receive optimization: read updates in batches, but bail-out
+ * as soon as we encountered two values from the same source
+ */
+ val lastReceivedEpoch = ByteArray(size)
+ var currentEpoch: Byte = 0
+ while (true) {
+ ++currentEpoch
+ // Start batch
+ // The very first receive in epoch should be suspending
+ var element = resultChannel.receiveOrNull() ?: break // Channel is closed, nothing to do here
+ while (true) {
+ val index = element.index
+ // Update values
+ val previous = latestValues[index]
+ latestValues[index] = element.value
+ if (previous === UNINITIALIZED) --remainingAbsentValues
+ // Check epoch
+ // Received the second value from the same flow in the same epoch -- bail out
+ if (lastReceivedEpoch[index] == currentEpoch) break
+ lastReceivedEpoch[index] = currentEpoch
+ element = resultChannel.poll() ?: break
+ }
+
+ // Process batch result if there is enough data
+ if (remainingAbsentValues == 0) {
+ /*
+ * If arrayFactory returns null, then we can avoid array copy because
+ * it's our own safe transformer that immediately deconstructs the array
+ */
+ val results = arrayFactory()
+ if (results == null) {
+ transform(latestValues as Array<T>)
+ } else {
+ (latestValues as Array<T?>).copyInto(results)
+ transform(results as Array<T>)
+ }
+ }
+ }
+}
+
+internal fun <T1, T2, R> zipImpl(flow: Flow<T1>, flow2: Flow<T2>, transform: suspend (T1, T2) -> R): Flow<R> =
+ unsafeFlow {
+ coroutineScope {
+ val second = produce<Any> {
+ flow2.collect { value ->
+ return@collect channel.send(value ?: NULL)
+ }
+ }
+
+ /*
+ * This approach only works with rendezvous channel and is required to enforce correctness
+ * in the following scenario:
+ * ```
+ * val f1 = flow { emit(1); delay(Long.MAX_VALUE) }
+ * val f2 = flowOf(1)
+ * f1.zip(f2) { ... }
+ * ```
+ *
+ * Invariant: this clause is invoked only when all elements from the channel were processed (=> rendezvous restriction).
+ */
+ val collectJob = Job()
+ (second as SendChannel<*>).invokeOnClose {
+ // Optimization to avoid AFE allocation when the other flow is done
+ if (collectJob.isActive) collectJob.cancel(AbortFlowException(this@unsafeFlow))
+ }
+
+ try {
+ /*
+ * Non-trivial undispatched (because we are in the right context and there is no structured concurrency)
+ * hierarchy:
+ * -Outer coroutineScope that owns the whole zip process
+ * - First flow is collected by the child of coroutineScope, collectJob.
+ * So it can be safely cancelled as soon as the second flow is done
+ * - **But** the downstream MUST NOT be cancelled when the second flow is done,
+ * so we emit to downstream from coroutineScope job.
+ * Typically, such hierarchy requires coroutine for collector that communicates
+ * with coroutines scope via a channel, but it's way too expensive, so
+ * we are using this trick instead.
+ */
+ val scopeContext = coroutineContext
+ val cnt = threadContextElements(scopeContext)
+ withContextUndispatched(coroutineContext + collectJob, Unit) {
+ flow.collect { value ->
+ withContextUndispatched(scopeContext, Unit, cnt) {
+ val otherValue = second.receiveOrNull() ?: throw AbortFlowException(this@unsafeFlow)
+ emit(transform(value, NULL.unbox(otherValue)))
+ }
}
- transform(arguments as Array<T>)
}
+ } catch (e: AbortFlowException) {
+ e.checkOwnership(owner = this@unsafeFlow)
+ } finally {
+ if (!second.isClosedForReceive) second.cancel()
}
}
}
-}
-
-private inline fun SelectBuilder<Unit>.onReceive(
- isClosed: Boolean,
- channel: ReceiveChannel<Any>,
- crossinline onClosed: () -> Unit,
- noinline onReceive: suspend (value: Any) -> Unit
-) {
- if (isClosed) return
- @Suppress("DEPRECATION")
- channel.onReceiveOrNull {
- // TODO onReceiveOrClosed when boxing issues are fixed
- if (it === null) onClosed()
- else onReceive(it)
- }
-}
-
-// Channel has any type due to onReceiveOrNull. This will be fixed after receiveOrClosed
-private fun CoroutineScope.asFairChannel(flow: Flow<*>): ReceiveChannel<Any> = produce {
- val channel = channel as ChannelCoroutine<Any>
- flow.collect { value ->
- return@collect channel.sendFair(value ?: NULL)
- }
-}
-
-internal fun <T1, T2, R> zipImpl(flow: Flow<T1>, flow2: Flow<T2>, transform: suspend (T1, T2) -> R): Flow<R> = unsafeFlow {
- coroutineScope {
- val first = asChannel(flow)
- val second = asChannel(flow2)
- /*
- * This approach only works with rendezvous channel and is required to enforce correctness
- * in the following scenario:
- * ```
- * val f1 = flow { emit(1); delay(Long.MAX_VALUE) }
- * val f2 = flowOf(1)
- * f1.zip(f2) { ... }
- * ```
- *
- * Invariant: this clause is invoked only when all elements from the channel were processed (=> rendezvous restriction).
- */
- (second as SendChannel<*>).invokeOnClose {
- if (!first.isClosedForReceive) first.cancel(AbortFlowException(this@unsafeFlow))
- }
-
- val otherIterator = second.iterator()
- try {
- first.consumeEach { value ->
- if (!otherIterator.hasNext()) {
- return@consumeEach
- }
- emit(transform(NULL.unbox(value), NULL.unbox(otherIterator.next())))
- }
- } catch (e: AbortFlowException) {
- e.checkOwnership(owner = this@unsafeFlow)
- } finally {
- if (!second.isClosedForReceive) second.cancel(AbortFlowException(this@unsafeFlow))
- }
- }
-}
-
-// Channel has any type due to onReceiveOrNull. This will be fixed after receiveOrClosed
-private fun CoroutineScope.asChannel(flow: Flow<*>): ReceiveChannel<Any> = produce {
- flow.collect { value ->
- return@collect channel.send(value ?: NULL)
- }
-}
diff --git a/kotlinx-coroutines-core/common/src/flow/internal/Merge.kt b/kotlinx-coroutines-core/common/src/flow/internal/Merge.kt
index 798f38b..530bcc1 100644
--- a/kotlinx-coroutines-core/common/src/flow/internal/Merge.kt
+++ b/kotlinx-coroutines-core/common/src/flow/internal/Merge.kt
@@ -14,10 +14,11 @@
private val transform: suspend FlowCollector<R>.(value: T) -> Unit,
flow: Flow<T>,
context: CoroutineContext = EmptyCoroutineContext,
- capacity: Int = Channel.BUFFERED
-) : ChannelFlowOperator<T, R>(flow, context, capacity) {
- override fun create(context: CoroutineContext, capacity: Int): ChannelFlow<R> =
- ChannelFlowTransformLatest(transform, flow, context, capacity)
+ capacity: Int = Channel.BUFFERED,
+ onBufferOverflow: BufferOverflow = BufferOverflow.SUSPEND
+) : ChannelFlowOperator<T, R>(flow, context, capacity, onBufferOverflow) {
+ override fun create(context: CoroutineContext, capacity: Int, onBufferOverflow: BufferOverflow): ChannelFlow<R> =
+ ChannelFlowTransformLatest(transform, flow, context, capacity, onBufferOverflow)
override suspend fun flowCollect(collector: FlowCollector<R>) {
assert { collector is SendingCollector } // So cancellation behaviour is not leaking into the downstream
@@ -41,10 +42,11 @@
private val flow: Flow<Flow<T>>,
private val concurrency: Int,
context: CoroutineContext = EmptyCoroutineContext,
- capacity: Int = Channel.BUFFERED
-) : ChannelFlow<T>(context, capacity) {
- override fun create(context: CoroutineContext, capacity: Int): ChannelFlow<T> =
- ChannelFlowMerge(flow, concurrency, context, capacity)
+ capacity: Int = Channel.BUFFERED,
+ onBufferOverflow: BufferOverflow = BufferOverflow.SUSPEND
+) : ChannelFlow<T>(context, capacity, onBufferOverflow) {
+ override fun create(context: CoroutineContext, capacity: Int, onBufferOverflow: BufferOverflow): ChannelFlow<T> =
+ ChannelFlowMerge(flow, concurrency, context, capacity, onBufferOverflow)
override fun produceImpl(scope: CoroutineScope): ReceiveChannel<T> {
return scope.flowProduce(context, capacity, block = collectToFun)
@@ -72,17 +74,17 @@
}
}
- override fun additionalToStringProps(): String =
- "concurrency=$concurrency, "
+ override fun additionalToStringProps(): String = "concurrency=$concurrency"
}
internal class ChannelLimitedFlowMerge<T>(
private val flows: Iterable<Flow<T>>,
context: CoroutineContext = EmptyCoroutineContext,
- capacity: Int = Channel.BUFFERED
-) : ChannelFlow<T>(context, capacity) {
- override fun create(context: CoroutineContext, capacity: Int): ChannelFlow<T> =
- ChannelLimitedFlowMerge(flows, context, capacity)
+ capacity: Int = Channel.BUFFERED,
+ onBufferOverflow: BufferOverflow = BufferOverflow.SUSPEND
+) : ChannelFlow<T>(context, capacity, onBufferOverflow) {
+ override fun create(context: CoroutineContext, capacity: Int, onBufferOverflow: BufferOverflow): ChannelFlow<T> =
+ ChannelLimitedFlowMerge(flows, context, capacity, onBufferOverflow)
override fun produceImpl(scope: CoroutineScope): ReceiveChannel<T> {
return scope.flowProduce(context, capacity, block = collectToFun)
diff --git a/kotlinx-coroutines-core/common/src/flow/internal/NullSurrogate.kt b/kotlinx-coroutines-core/common/src/flow/internal/NullSurrogate.kt
index 22e1957..f20deb2 100644
--- a/kotlinx-coroutines-core/common/src/flow/internal/NullSurrogate.kt
+++ b/kotlinx-coroutines-core/common/src/flow/internal/NullSurrogate.kt
@@ -11,11 +11,20 @@
/**
* This value is used a a surrogate `null` value when needed.
* It should never leak to the outside world.
+ * Its usage typically are paired with [Symbol.unbox] usages.
*/
@JvmField
@SharedImmutable
internal val NULL = Symbol("NULL")
+/**
+ * Symbol to indicate that the value is not yet initialized.
+ * It should never leak to the outside world.
+ */
+@JvmField
+@SharedImmutable
+internal val UNINITIALIZED = Symbol("UNINITIALIZED")
+
/*
* Symbol used to indicate that the flow is complete.
* It should never leak to the outside world.
diff --git a/kotlinx-coroutines-core/common/src/flow/operators/Context.kt b/kotlinx-coroutines-core/common/src/flow/operators/Context.kt
index 010d781..a6d6b76 100644
--- a/kotlinx-coroutines-core/common/src/flow/operators/Context.kt
+++ b/kotlinx-coroutines-core/common/src/flow/operators/Context.kt
@@ -60,13 +60,23 @@
* Q : -->---------- [2A] -- [2B] -- [2C] -->-- // collect
* ```
*
- * When operator's code takes time to execute this decreases the total execution time of the flow.
+ * When the operator's code takes some time to execute, this decreases the total execution time of the flow.
* A [channel][Channel] is used between the coroutines to send elements emitted by the coroutine `P` to
* the coroutine `Q`. If the code before `buffer` operator (in the coroutine `P`) is faster than the code after
* `buffer` operator (in the coroutine `Q`), then this channel will become full at some point and will suspend
* the producer coroutine `P` until the consumer coroutine `Q` catches up.
* The [capacity] parameter defines the size of this buffer.
*
+ * ### Buffer overflow
+ *
+ * By default, the emitter is suspended when the buffer overflows, to let collector catch up. This strategy can be
+ * overridden with an optional [onBufferOverflow] parameter so that the emitter is never suspended. In this
+ * case, on buffer overflow either the oldest value in the buffer is dropped with the [DROP_OLDEST][BufferOverflow.DROP_OLDEST]
+ * strategy and the latest emitted value is added to the buffer,
+ * or the latest value that is being emitted is dropped with the [DROP_LATEST][BufferOverflow.DROP_LATEST] strategy,
+ * keeping the buffer intact.
+ * To implement either of the custom strategies, a buffer of at least one element is used.
+ *
* ### Operator fusion
*
* Adjacent applications of [channelFlow], [flowOn], [buffer], [produceIn], and [broadcastIn] are
@@ -76,9 +86,12 @@
* which effectively requests a buffer of any size. Multiple requests with a specified buffer
* size produce a buffer with the sum of the requested buffer sizes.
*
+ * A `buffer` call with a non-default value of the [onBufferOverflow] parameter overrides all immediately preceding
+ * buffering operators, because it never suspends its upstream, and thus no upstream buffer would ever be used.
+ *
* ### Conceptual implementation
*
- * The actual implementation of `buffer` is not trivial due to the fusing, but conceptually its
+ * The actual implementation of `buffer` is not trivial due to the fusing, but conceptually its basic
* implementation is equivalent to the following code that can be written using [produce]
* coroutine builder to produce a channel and [consumeEach][ReceiveChannel.consumeEach] extension to consume it:
*
@@ -96,24 +109,43 @@
*
* ### Conflation
*
- * Usage of this function with [capacity] of [Channel.CONFLATED][Channel.CONFLATED] is provided as a shortcut via
- * [conflate] operator. See its documentation for details.
+ * Usage of this function with [capacity] of [Channel.CONFLATED][Channel.CONFLATED] is a shortcut to
+ * `buffer(onBufferOverflow = `[`BufferOverflow.DROP_OLDEST`][BufferOverflow.DROP_OLDEST]`)`, and is available via
+ * a separate [conflate] operator. See its documentation for details.
*
* @param capacity type/capacity of the buffer between coroutines. Allowed values are the same as in `Channel(...)`
- * factory function: [BUFFERED][Channel.BUFFERED] (by default), [CONFLATED][Channel.CONFLATED],
- * [RENDEZVOUS][Channel.RENDEZVOUS], [UNLIMITED][Channel.UNLIMITED] or a non-negative value indicating
- * an explicitly requested size.
+ * factory function: [BUFFERED][Channel.BUFFERED] (by default), [CONFLATED][Channel.CONFLATED],
+ * [RENDEZVOUS][Channel.RENDEZVOUS], [UNLIMITED][Channel.UNLIMITED] or a non-negative value indicating
+ * an explicitly requested size.
+ * @param onBufferOverflow configures an action on buffer overflow (optional, defaults to
+ * [SUSPEND][BufferOverflow.SUSPEND], supported only when `capacity >= 0` or `capacity == Channel.BUFFERED`,
+ * implicitly creates a channel with at least one buffered element).
*/
-public fun <T> Flow<T>.buffer(capacity: Int = BUFFERED): Flow<T> {
+@Suppress("NAME_SHADOWING")
+public fun <T> Flow<T>.buffer(capacity: Int = BUFFERED, onBufferOverflow: BufferOverflow = BufferOverflow.SUSPEND): Flow<T> {
require(capacity >= 0 || capacity == BUFFERED || capacity == CONFLATED) {
"Buffer size should be non-negative, BUFFERED, or CONFLATED, but was $capacity"
}
+ require(capacity != CONFLATED || onBufferOverflow == BufferOverflow.SUSPEND) {
+ "CONFLATED capacity cannot be used with non-default onBufferOverflow"
+ }
+ // desugar CONFLATED capacity to (0, DROP_OLDEST)
+ var capacity = capacity
+ var onBufferOverflow = onBufferOverflow
+ if (capacity == CONFLATED) {
+ capacity = 0
+ onBufferOverflow = BufferOverflow.DROP_OLDEST
+ }
+ // create a flow
return when (this) {
- is FusibleFlow -> fuse(capacity = capacity)
- else -> ChannelFlowOperatorImpl(this, capacity = capacity)
+ is FusibleFlow -> fuse(capacity = capacity, onBufferOverflow = onBufferOverflow)
+ else -> ChannelFlowOperatorImpl(this, capacity = capacity, onBufferOverflow = onBufferOverflow)
}
}
+@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.4.0, binary compatibility with earlier versions")
+public fun <T> Flow<T>.buffer(capacity: Int = BUFFERED): Flow<T> = buffer(capacity)
+
/**
* Conflates flow emissions via conflated channel and runs collector in a separate coroutine.
* The effect of this is that emitter is never suspended due to a slow collector, but collector
@@ -138,7 +170,9 @@
* assertEquals(listOf(1, 10, 20, 30), result)
* ```
*
- * Note that `conflate` operator is a shortcut for [buffer] with `capacity` of [Channel.CONFLATED][Channel.CONFLATED].
+ * Note that `conflate` operator is a shortcut for [buffer] with `capacity` of [Channel.CONFLATED][Channel.CONFLATED],
+ * with is, in turn, a shortcut to a buffer that only keeps the latest element as
+ * created by `buffer(onBufferOverflow = `[`BufferOverflow.DROP_OLDEST`][BufferOverflow.DROP_OLDEST]`)`.
*
* ### Operator fusion
*
@@ -172,13 +206,17 @@
*
* For more explanation of context preservation please refer to [Flow] documentation.
*
- * This operators retains a _sequential_ nature of flow if changing the context does not call for changing
+ * This operator retains a _sequential_ nature of flow if changing the context does not call for changing
* the [dispatcher][CoroutineDispatcher]. Otherwise, if changing dispatcher is required, it collects
* flow emissions in one coroutine that is run using a specified [context] and emits them from another coroutines
* with the original collector's context using a channel with a [default][Channel.BUFFERED] buffer size
* between two coroutines similarly to [buffer] operator, unless [buffer] operator is explicitly called
* before or after `flowOn`, which requests buffering behavior and specifies channel size.
*
+ * Note, that flows operating across different dispatchers might lose some in-flight elements when cancelled.
+ * In particular, this operator ensures that downstream flow does not resume on cancellation even if the element
+ * was already emitted by the upstream flow.
+ *
* ### Operator fusion
*
* Adjacent applications of [channelFlow], [flowOn], [buffer], [produceIn], and [broadcastIn] are
@@ -194,8 +232,8 @@
* .flowOn(Dispatchers.Default)
* ```
*
- * Note that an instance of [StateFlow] does not have an execution context by itself,
- * so applying `flowOn` to a `StateFlow` has not effect. See [StateFlow] documentation on Operator Fusion.
+ * Note that an instance of [SharedFlow] does not have an execution context by itself,
+ * so applying `flowOn` to a `SharedFlow` has not effect. See the [SharedFlow] documentation on Operator Fusion.
*
* @throws [IllegalArgumentException] if provided context contains [Job] instance.
*/
@@ -211,17 +249,30 @@
/**
* Returns a flow which checks cancellation status on each emission and throws
* the corresponding cancellation cause if flow collector was cancelled.
- * Note that [flow] builder is [cancellable] by default.
+ * Note that [flow] builder and all implementations of [SharedFlow] are [cancellable] by default.
*
* This operator provides a shortcut for `.onEach { currentCoroutineContext().ensureActive() }`.
* See [ensureActive][CoroutineContext.ensureActive] for details.
*/
-public fun <T> Flow<T>.cancellable(): Flow<T> {
- if (this is AbstractFlow<*>) return this // Fast-path, already cancellable
- return unsafeFlow {
- collect {
+public fun <T> Flow<T>.cancellable(): Flow<T> =
+ when (this) {
+ is CancellableFlow<*> -> this // Fast-path, already cancellable
+ else -> CancellableFlowImpl(this)
+ }
+
+/**
+ * Internal marker for flows that are [cancellable].
+ */
+internal interface CancellableFlow<out T> : Flow<T>
+
+/**
+ * Named implementation class for a flow that is defined by the [cancellable] function.
+ */
+private class CancellableFlowImpl<T>(private val flow: Flow<T>) : CancellableFlow<T> {
+ override suspend fun collect(collector: FlowCollector<T>) {
+ flow.collect {
currentCoroutineContext().ensureActive()
- emit(it)
+ collector.emit(it)
}
}
}
diff --git a/kotlinx-coroutines-core/common/src/flow/operators/Delay.kt b/kotlinx-coroutines-core/common/src/flow/operators/Delay.kt
index 5f3c900..c95b4be 100644
--- a/kotlinx-coroutines-core/common/src/flow/operators/Delay.kt
+++ b/kotlinx-coroutines-core/common/src/flow/operators/Delay.kt
@@ -14,13 +14,30 @@
import kotlin.jvm.*
import kotlin.time.*
+/* Scaffolding for Knit code examples
+<!--- TEST_NAME FlowDelayTest -->
+<!--- PREFIX .*-duration-.*
+@file:OptIn(ExperimentalTime::class)
+----- INCLUDE .*-duration-.*
+import kotlin.time.*
+----- INCLUDE .*
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+
+fun main() = runBlocking {
+----- SUFFIX .*
+.toList().joinToString().let { println(it) } }
+-->
+*/
+
/**
* Returns a flow that mirrors the original flow, but filters out values
* that are followed by the newer values within the given [timeout][timeoutMillis].
* The latest value is always emitted.
*
* Example:
- * ```
+ *
+ * ```kotlin
* flow {
* emit(1)
* delay(90)
@@ -33,51 +50,81 @@
* emit(5)
* }.debounce(1000)
* ```
- * produces `3, 4, 5`.
+ * <!--- KNIT example-delay-01.kt -->
+ *
+ * produces the following emissions
+ *
+ * ```text
+ * 3, 4, 5
+ * ```
+ * <!--- TEST -->
*
* Note that the resulting flow does not emit anything as long as the original flow emits
* items faster than every [timeoutMillis] milliseconds.
*/
@FlowPreview
public fun <T> Flow<T>.debounce(timeoutMillis: Long): Flow<T> {
- require(timeoutMillis > 0) { "Debounce timeout should be positive" }
- return scopedFlow { downstream ->
- // Actually Any, KT-30796
- val values = produce<Any?>(capacity = Channel.CONFLATED) {
- collect { value -> send(value ?: NULL) }
- }
- var lastValue: Any? = null
- while (lastValue !== DONE) {
- select<Unit> {
- // Should be receiveOrClosed when boxing issues are fixed
- values.onReceiveOrNull {
- if (it == null) {
- if (lastValue != null) downstream.emit(NULL.unbox(lastValue))
- lastValue = DONE
- } else {
- lastValue = it
- }
- }
-
- lastValue?.let { value ->
- // set timeout when lastValue != null
- onTimeout(timeoutMillis) {
- lastValue = null // Consume the value
- downstream.emit(NULL.unbox(value))
- }
- }
- }
- }
- }
+ require(timeoutMillis >= 0L) { "Debounce timeout should not be negative" }
+ if (timeoutMillis == 0L) return this
+ return debounceInternal { timeoutMillis }
}
/**
* Returns a flow that mirrors the original flow, but filters out values
+ * that are followed by the newer values within the given [timeout][timeoutMillis].
+ * The latest value is always emitted.
+ *
+ * A variation of [debounce] that allows specifying the timeout value dynamically.
+ *
+ * Example:
+ *
+ * ```kotlin
+ * flow {
+ * emit(1)
+ * delay(90)
+ * emit(2)
+ * delay(90)
+ * emit(3)
+ * delay(1010)
+ * emit(4)
+ * delay(1010)
+ * emit(5)
+ * }.debounce {
+ * if (it == 1) {
+ * 0L
+ * } else {
+ * 1000L
+ * }
+ * }
+ * ```
+ * <!--- KNIT example-delay-02.kt -->
+ *
+ * produces the following emissions
+ *
+ * ```text
+ * 1, 3, 4, 5
+ * ```
+ * <!--- TEST -->
+ *
+ * Note that the resulting flow does not emit anything as long as the original flow emits
+ * items faster than every [timeoutMillis] milliseconds.
+ *
+ * @param timeoutMillis [T] is the emitted value and the return value is timeout in milliseconds.
+ */
+@FlowPreview
+@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
+@OverloadResolutionByLambdaReturnType
+public fun <T> Flow<T>.debounce(timeoutMillis: (T) -> Long): Flow<T> =
+ debounceInternal(timeoutMillis)
+
+/**
+ * Returns a flow that mirrors the original flow, but filters out values
* that are followed by the newer values within the given [timeout].
* The latest value is always emitted.
*
* Example:
- * ```
+ *
+ * ```kotlin
* flow {
* emit(1)
* delay(90.milliseconds)
@@ -90,29 +137,141 @@
* emit(5)
* }.debounce(1000.milliseconds)
* ```
- * produces `3, 4, 5`.
+ * <!--- KNIT example-delay-duration-01.kt -->
+ *
+ * produces the following emissions
+ *
+ * ```text
+ * 3, 4, 5
+ * ```
+ * <!--- TEST -->
*
* Note that the resulting flow does not emit anything as long as the original flow emits
* items faster than every [timeout] milliseconds.
*/
@ExperimentalTime
@FlowPreview
-public fun <T> Flow<T>.debounce(timeout: Duration): Flow<T> = debounce(timeout.toDelayMillis())
+public fun <T> Flow<T>.debounce(timeout: Duration): Flow<T> =
+ debounce(timeout.toDelayMillis())
+
+/**
+ * Returns a flow that mirrors the original flow, but filters out values
+ * that are followed by the newer values within the given [timeout].
+ * The latest value is always emitted.
+ *
+ * A variation of [debounce] that allows specifying the timeout value dynamically.
+ *
+ * Example:
+ *
+ * ```kotlin
+ * flow {
+ * emit(1)
+ * delay(90.milliseconds)
+ * emit(2)
+ * delay(90.milliseconds)
+ * emit(3)
+ * delay(1010.milliseconds)
+ * emit(4)
+ * delay(1010.milliseconds)
+ * emit(5)
+ * }.debounce {
+ * if (it == 1) {
+ * 0.milliseconds
+ * } else {
+ * 1000.milliseconds
+ * }
+ * }
+ * ```
+ * <!--- KNIT example-delay-duration-02.kt -->
+ *
+ * produces the following emissions
+ *
+ * ```text
+ * 1, 3, 4, 5
+ * ```
+ * <!--- TEST -->
+ *
+ * Note that the resulting flow does not emit anything as long as the original flow emits
+ * items faster than every [timeout] unit.
+ *
+ * @param timeout [T] is the emitted value and the return value is timeout in [Duration].
+ */
+@ExperimentalTime
+@FlowPreview
+@JvmName("debounceDuration")
+@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
+@OverloadResolutionByLambdaReturnType
+public fun <T> Flow<T>.debounce(timeout: (T) -> Duration): Flow<T> =
+ debounceInternal { emittedItem ->
+ timeout(emittedItem).toDelayMillis()
+ }
+
+private fun <T> Flow<T>.debounceInternal(timeoutMillisSelector: (T) -> Long) : Flow<T> =
+ scopedFlow { downstream ->
+ // Produce the values using the default (rendezvous) channel
+ // Note: the actual type is Any, KT-30796
+ val values = produce<Any?> {
+ collect { value -> send(value ?: NULL) }
+ }
+ // Now consume the values
+ var lastValue: Any? = null
+ while (lastValue !== DONE) {
+ var timeoutMillis = 0L // will be always computed when lastValue != null
+ // Compute timeout for this value
+ if (lastValue != null) {
+ timeoutMillis = timeoutMillisSelector(NULL.unbox(lastValue))
+ require(timeoutMillis >= 0L) { "Debounce timeout should not be negative" }
+ if (timeoutMillis == 0L) {
+ downstream.emit(NULL.unbox(lastValue))
+ lastValue = null // Consume the value
+ }
+ }
+ // assert invariant: lastValue != null implies timeoutMillis > 0
+ assert { lastValue == null || timeoutMillis > 0 }
+ // wait for the next value with timeout
+ select<Unit> {
+ // Set timeout when lastValue exists and is not consumed yet
+ if (lastValue != null) {
+ onTimeout(timeoutMillis) {
+ downstream.emit(NULL.unbox(lastValue))
+ lastValue = null // Consume the value
+ }
+ }
+ // Should be receiveOrClosed when boxing issues are fixed
+ values.onReceiveOrNull { value ->
+ if (value == null) {
+ if (lastValue != null) downstream.emit(NULL.unbox(lastValue))
+ lastValue = DONE
+ } else {
+ lastValue = value
+ }
+ }
+ }
+ }
+ }
/**
* Returns a flow that emits only the latest value emitted by the original flow during the given sampling [period][periodMillis].
*
* Example:
- * ```
+ *
+ * ```kotlin
* flow {
* repeat(10) {
* emit(it)
- * delay(50)
+ * delay(110)
* }
- * }.sample(100)
+ * }.sample(200)
* ```
- * produces `1, 3, 5, 7, 9`.
- *
+ * <!--- KNIT example-delay-03.kt -->
+ *
+ * produces the following emissions
+ *
+ * ```text
+ * 1, 3, 5, 7, 9
+ * ```
+ * <!--- TEST -->
+ *
* Note that the latest element is not emitted if it does not fit into the sampling window.
*/
@FlowPreview
@@ -166,15 +325,23 @@
* Returns a flow that emits only the latest value emitted by the original flow during the given sampling [period].
*
* Example:
- * ```
+ *
+ * ```kotlin
* flow {
* repeat(10) {
* emit(it)
- * delay(50.milliseconds)
+ * delay(110.milliseconds)
* }
- * }.sample(100.milliseconds)
+ * }.sample(200.milliseconds)
* ```
- * produces `1, 3, 5, 7, 9`.
+ * <!--- KNIT example-delay-duration-03.kt -->
+ *
+ * produces the following emissions
+ *
+ * ```text
+ * 1, 3, 5, 7, 9
+ * ```
+ * <!--- TEST -->
*
* Note that the latest element is not emitted if it does not fit into the sampling window.
*/
diff --git a/kotlinx-coroutines-core/common/src/flow/operators/Distinct.kt b/kotlinx-coroutines-core/common/src/flow/operators/Distinct.kt
index 3504848..1a34af7 100644
--- a/kotlinx-coroutines-core/common/src/flow/operators/Distinct.kt
+++ b/kotlinx-coroutines-core/common/src/flow/operators/Distinct.kt
@@ -7,9 +7,10 @@
package kotlinx.coroutines.flow
+import kotlinx.coroutines.*
import kotlinx.coroutines.flow.internal.*
import kotlin.jvm.*
-import kotlinx.coroutines.flow.internal.unsafeFlow as flow
+import kotlin.native.concurrent.*
/**
* Returns flow where all subsequent repetitions of the same value are filtered out.
@@ -17,44 +18,69 @@
* Note that any instance of [StateFlow] already behaves as if `distinctUtilChanged` operator is
* applied to it, so applying `distinctUntilChanged` to a `StateFlow` has no effect.
* See [StateFlow] documentation on Operator Fusion.
+ * Also, repeated application of `distinctUntilChanged` operator on any flow has no effect.
*/
public fun <T> Flow<T>.distinctUntilChanged(): Flow<T> =
when (this) {
- is StateFlow<*> -> this
- else -> distinctUntilChangedBy { it }
+ is StateFlow<*> -> this // state flows are always distinct
+ else -> distinctUntilChangedBy(keySelector = defaultKeySelector, areEquivalent = defaultAreEquivalent)
}
/**
* Returns flow where all subsequent repetitions of the same value are filtered out, when compared
* with each other via the provided [areEquivalent] function.
+ *
+ * Note that repeated application of `distinctUntilChanged` operator with the same parameter has no effect.
*/
+@Suppress("UNCHECKED_CAST")
public fun <T> Flow<T>.distinctUntilChanged(areEquivalent: (old: T, new: T) -> Boolean): Flow<T> =
- distinctUntilChangedBy(keySelector = { it }, areEquivalent = areEquivalent)
+ distinctUntilChangedBy(keySelector = defaultKeySelector, areEquivalent = areEquivalent as (Any?, Any?) -> Boolean)
/**
* Returns flow where all subsequent repetitions of the same key are filtered out, where
* key is extracted with [keySelector] function.
+ *
+ * Note that repeated application of `distinctUntilChanged` operator with the same parameter has no effect.
*/
public fun <T, K> Flow<T>.distinctUntilChangedBy(keySelector: (T) -> K): Flow<T> =
- distinctUntilChangedBy(keySelector = keySelector, areEquivalent = { old, new -> old == new })
+ distinctUntilChangedBy(keySelector = keySelector, areEquivalent = defaultAreEquivalent)
+
+@SharedImmutable
+private val defaultKeySelector: (Any?) -> Any? = { it }
+
+@SharedImmutable
+private val defaultAreEquivalent: (Any?, Any?) -> Boolean = { old, new -> old == new }
/**
* Returns flow where all subsequent repetitions of the same key are filtered out, where
* keys are extracted with [keySelector] function and compared with each other via the
* provided [areEquivalent] function.
+ *
+ * NOTE: It is non-inline to share a single implementing class.
*/
-private inline fun <T, K> Flow<T>.distinctUntilChangedBy(
- crossinline keySelector: (T) -> K,
- crossinline areEquivalent: (old: K, new: K) -> Boolean
-): Flow<T> =
- flow {
+private fun <T> Flow<T>.distinctUntilChangedBy(
+ keySelector: (T) -> Any?,
+ areEquivalent: (old: Any?, new: Any?) -> Boolean
+): Flow<T> = when {
+ this is DistinctFlowImpl<*> && this.keySelector === keySelector && this.areEquivalent === areEquivalent -> this // same
+ else -> DistinctFlowImpl(this, keySelector, areEquivalent)
+}
+
+private class DistinctFlowImpl<T>(
+ private val upstream: Flow<T>,
+ @JvmField val keySelector: (T) -> Any?,
+ @JvmField val areEquivalent: (old: Any?, new: Any?) -> Boolean
+): Flow<T> {
+ @InternalCoroutinesApi
+ override suspend fun collect(collector: FlowCollector<T>) {
var previousKey: Any? = NULL
- collect { value ->
+ upstream.collect { value ->
val key = keySelector(value)
@Suppress("UNCHECKED_CAST")
- if (previousKey === NULL || !areEquivalent(previousKey as K, key)) {
+ if (previousKey === NULL || !areEquivalent(previousKey, key)) {
previousKey = key
- emit(value)
+ collector.emit(value)
}
}
}
+}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/common/src/flow/operators/Emitters.kt b/kotlinx-coroutines-core/common/src/flow/operators/Emitters.kt
index fb37da3..244af9a 100644
--- a/kotlinx-coroutines-core/common/src/flow/operators/Emitters.kt
+++ b/kotlinx-coroutines-core/common/src/flow/operators/Emitters.kt
@@ -55,7 +55,12 @@
}
/**
- * Invokes the given [action] when this flow starts to be collected.
+ * Returns a flow that invokes the given [action] **before** this flow starts to be collected.
+ *
+ * The [action] is called before the upstream flow is started, so if it is used with a [SharedFlow]
+ * there is **no guarantee** that emissions from the upstream flow that happen inside or immediately
+ * after this `onStart` action will be collected
+ * (see [onSubscription] for an alternative operator on shared flows).
*
* The receiver of the [action] is [FlowCollector], so `onStart` can emit additional elements.
* For example:
@@ -66,7 +71,6 @@
* .collect { println(it) } // prints Begin, a, b, c
* ```
*/
-@ExperimentalCoroutinesApi
public fun <T> Flow<T>.onStart(
action: suspend FlowCollector<T>.() -> Unit
): Flow<T> = unsafeFlow { // Note: unsafe flow is used here, but safe collector is used to invoke start action
@@ -80,7 +84,7 @@
}
/**
- * Invokes the given [action] when the given flow is completed or cancelled, passing
+ * Returns a flow that invokes the given [action] **after** the flow is completed or cancelled, passing
* the cancellation exception or failure as cause parameter of [action].
*
* Conceptually, `onCompletion` is similar to wrapping the flow collection into a `finally` block,
@@ -126,7 +130,7 @@
* ```
*
* The receiver of the [action] is [FlowCollector] and this operator can be used to emit additional
- * elements at the end if it completed successfully. For example:
+ * elements at the end **if it completed successfully**. For example:
*
* ```
* flowOf("a", "b", "c")
@@ -137,7 +141,6 @@
* In case of failure or cancellation, any attempt to emit additional elements throws the corresponding exception.
* Use [catch] if you need to suppress failure and replace it with emission of elements.
*/
-@ExperimentalCoroutinesApi
public fun <T> Flow<T>.onCompletion(
action: suspend FlowCollector<T>.(cause: Throwable?) -> Unit
): Flow<T> = unsafeFlow { // Note: unsafe flow is used here, but safe collector is used to invoke completion action
@@ -153,7 +156,12 @@
throw e
}
// Normal completion
- SafeCollector(this, currentCoroutineContext()).invokeSafely(action, null)
+ val sc = SafeCollector(this, currentCoroutineContext())
+ try {
+ sc.action(null)
+ } finally {
+ sc.releaseIntercepted()
+ }
}
/**
@@ -168,7 +176,6 @@
* }.collect { println(it) } // prints 1, 2
* ```
*/
-@ExperimentalCoroutinesApi
public fun <T> Flow<T>.onEmpty(
action: suspend FlowCollector<T>.() -> Unit
): Flow<T> = unsafeFlow {
@@ -193,12 +200,6 @@
}
}
-// It was only released in 1.3.0-M2, remove in 1.4.0
-/** @suppress */
-@Deprecated(level = DeprecationLevel.HIDDEN, message = "binary compatibility with a version w/o FlowCollector receiver")
-public fun <T> Flow<T>.onCompletion(action: suspend (cause: Throwable?) -> Unit): Flow<T> =
- onCompletion { action(it) }
-
private suspend fun <T> FlowCollector<T>.invokeSafely(
action: suspend FlowCollector<T>.(cause: Throwable?) -> Unit,
cause: Throwable?
diff --git a/kotlinx-coroutines-core/common/src/flow/operators/Lint.kt b/kotlinx-coroutines-core/common/src/flow/operators/Lint.kt
index 5500034..7a70fbf 100644
--- a/kotlinx-coroutines-core/common/src/flow/operators/Lint.kt
+++ b/kotlinx-coroutines-core/common/src/flow/operators/Lint.kt
@@ -2,71 +2,81 @@
* Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
*/
+@file:Suppress("unused")
+
package kotlinx.coroutines.flow
import kotlinx.coroutines.*
import kotlin.coroutines.*
/**
- * Returns this.
- * Applying [flowOn][Flow.flowOn] operator to [StateFlow] has no effect.
- * See [StateFlow] documentation on Operator Fusion.
+ * Applying [cancellable][Flow.cancellable] to a [SharedFlow] has no effect.
+ * See the [SharedFlow] documentation on Operator Fusion.
*/
@Deprecated(
level = DeprecationLevel.ERROR,
- message = "Applying flowOn operator to StateFlow has no effect. See StateFlow documentation on Operator Fusion.",
+ message = "Applying 'cancellable' to a SharedFlow has no effect. See the SharedFlow documentation on Operator Fusion.",
replaceWith = ReplaceWith("this")
)
-public fun <T> StateFlow<T>.flowOn(context: CoroutineContext): Flow<T> = noImpl()
+public fun <T> SharedFlow<T>.cancellable(): Flow<T> = noImpl()
/**
- * Returns this.
- * Applying [conflate][Flow.conflate] operator to [StateFlow] has no effect.
- * See [StateFlow] documentation on Operator Fusion.
+ * Applying [flowOn][Flow.flowOn] to [SharedFlow] has no effect.
+ * See the [SharedFlow] documentation on Operator Fusion.
*/
@Deprecated(
level = DeprecationLevel.ERROR,
- message = "Applying conflate operator to StateFlow has no effect. See StateFlow documentation on Operator Fusion.",
+ message = "Applying 'flowOn' to SharedFlow has no effect. See the SharedFlow documentation on Operator Fusion.",
+ replaceWith = ReplaceWith("this")
+)
+public fun <T> SharedFlow<T>.flowOn(context: CoroutineContext): Flow<T> = noImpl()
+
+/**
+ * Applying [conflate][Flow.conflate] to [StateFlow] has no effect.
+ * See the [StateFlow] documentation on Operator Fusion.
+ */
+@Deprecated(
+ level = DeprecationLevel.ERROR,
+ message = "Applying 'conflate' to StateFlow has no effect. See the StateFlow documentation on Operator Fusion.",
replaceWith = ReplaceWith("this")
)
public fun <T> StateFlow<T>.conflate(): Flow<T> = noImpl()
/**
- * Returns this.
- * Applying [distinctUntilChanged][Flow.distinctUntilChanged] operator to [StateFlow] has no effect.
- * See [StateFlow] documentation on Operator Fusion.
+ * Applying [distinctUntilChanged][Flow.distinctUntilChanged] to [StateFlow] has no effect.
+ * See the [StateFlow] documentation on Operator Fusion.
*/
@Deprecated(
level = DeprecationLevel.ERROR,
- message = "Applying distinctUntilChanged operator to StateFlow has no effect. See StateFlow documentation on Operator Fusion.",
+ message = "Applying 'distinctUntilChanged' to StateFlow has no effect. See the StateFlow documentation on Operator Fusion.",
replaceWith = ReplaceWith("this")
)
public fun <T> StateFlow<T>.distinctUntilChanged(): Flow<T> = noImpl()
-//@Deprecated(
-// message = "isActive is resolved into the extension of outer CoroutineScope which is likely to be an error." +
-// "Use currentCoroutineContext().isActive or cancellable() operator instead " +
-// "or specify the receiver of isActive explicitly. " +
-// "Additionally, flow {} builder emissions are cancellable by default.",
-// level = DeprecationLevel.WARNING, // ERROR in 1.4
-// replaceWith = ReplaceWith("currentCoroutineContext().isActive")
-//)
-//public val FlowCollector<*>.isActive: Boolean
-// get() = noImpl()
-//
-//@Deprecated(
-// message = "cancel() is resolved into the extension of outer CoroutineScope which is likely to be an error." +
-// "Use currentCoroutineContext().cancel() instead or specify the receiver of cancel() explicitly",
-// level = DeprecationLevel.WARNING, // ERROR in 1.4
-// replaceWith = ReplaceWith("currentCoroutineContext().cancel(cause)")
-//)
-//public fun FlowCollector<*>.cancel(cause: CancellationException? = null): Unit = noImpl()
-//
-//@Deprecated(
-// message = "coroutineContext is resolved into the property of outer CoroutineScope which is likely to be an error." +
-// "Use currentCoroutineContext() instead or specify the receiver of coroutineContext explicitly",
-// level = DeprecationLevel.WARNING, // ERROR in 1.4
-// replaceWith = ReplaceWith("currentCoroutineContext()")
-//)
-//public val FlowCollector<*>.coroutineContext: CoroutineContext
-// get() = noImpl()
\ No newline at end of file
+@Deprecated(
+ message = "isActive is resolved into the extension of outer CoroutineScope which is likely to be an error." +
+ "Use currentCoroutineContext().isActive or cancellable() operator instead " +
+ "or specify the receiver of isActive explicitly. " +
+ "Additionally, flow {} builder emissions are cancellable by default.",
+ level = DeprecationLevel.ERROR,
+ replaceWith = ReplaceWith("currentCoroutineContext().isActive")
+)
+public val FlowCollector<*>.isActive: Boolean
+ get() = noImpl()
+
+@Deprecated(
+ message = "cancel() is resolved into the extension of outer CoroutineScope which is likely to be an error." +
+ "Use currentCoroutineContext().cancel() instead or specify the receiver of cancel() explicitly",
+ level = DeprecationLevel.ERROR,
+ replaceWith = ReplaceWith("currentCoroutineContext().cancel(cause)")
+)
+public fun FlowCollector<*>.cancel(cause: CancellationException? = null): Unit = noImpl()
+
+@Deprecated(
+ message = "coroutineContext is resolved into the property of outer CoroutineScope which is likely to be an error." +
+ "Use currentCoroutineContext() instead or specify the receiver of coroutineContext explicitly",
+ level = DeprecationLevel.ERROR,
+ replaceWith = ReplaceWith("currentCoroutineContext()")
+)
+public val FlowCollector<*>.coroutineContext: CoroutineContext
+ get() = noImpl()
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/common/src/flow/operators/Share.kt b/kotlinx-coroutines-core/common/src/flow/operators/Share.kt
new file mode 100644
index 0000000..fe737a5
--- /dev/null
+++ b/kotlinx-coroutines-core/common/src/flow/operators/Share.kt
@@ -0,0 +1,413 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+@file:JvmMultifileClass
+@file:JvmName("FlowKt")
+
+package kotlinx.coroutines.flow
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.channels.*
+import kotlinx.coroutines.flow.internal.*
+import kotlin.coroutines.*
+import kotlin.jvm.*
+
+// -------------------------------- shareIn --------------------------------
+
+/**
+ * Converts a _cold_ [Flow] into a _hot_ [SharedFlow] that is started in the given coroutine [scope],
+ * sharing emissions from a single running instance of the upstream flow with multiple downstream subscribers,
+ * and replaying a specified number of [replay] values to new subscribers. See the [SharedFlow] documentation
+ * for the general concepts of shared flows.
+ *
+ * The starting of the sharing coroutine is controlled by the [started] parameter. The following options
+ * are supported.
+ *
+ * * [Eagerly][SharingStarted.Eagerly] — the upstream flow is started even before the first subscriber appears. Note
+ * that in this case all values emitted by the upstream beyond the most recent values as specified by
+ * [replay] parameter **will be immediately discarded**.
+ * * [Lazily][SharingStarted.Lazily] — starts the upstream flow after the first subscriber appears, which guarantees
+ * that this first subscriber gets all the emitted values, while subsequent subscribers are only guaranteed to
+ * get the most recent [replay] values. The upstream flow continues to be active even when all subscribers
+ * disappear, but only the most recent [replay] values are cached without subscribers.
+ * * [WhileSubscribed()][SharingStarted.WhileSubscribed] — starts the upstream flow when the first subscriber
+ * appears, immediately stops when the last subscriber disappears, keeping the replay cache forever.
+ * It has additional optional configuration parameters as explained in its documentation.
+ * * A custom strategy can be supplied by implementing the [SharingStarted] interface.
+ *
+ * The `shareIn` operator is useful in situations when there is a _cold_ flow that is expensive to create and/or
+ * to maintain, but there are multiple subscribers that need to collect its values. For example, consider a
+ * flow of messages coming from a backend over the expensive network connection, taking a lot of
+ * time to establish. Conceptually, it might be implemented like this:
+ *
+ * ```
+ * val backendMessages: Flow<Message> = flow {
+ * connectToBackend() // takes a lot of time
+ * try {
+ * while (true) {
+ * emit(receiveMessageFromBackend())
+ * }
+ * } finally {
+ * disconnectFromBackend()
+ * }
+ * }
+ * ```
+ *
+ * If this flow is directly used in the application, then every time it is collected a fresh connection is
+ * established, and it will take a while before messages start flowing. However, we can share a single connection
+ * and establish it eagerly like this:
+ *
+ * ```
+ * val messages: SharedFlow<Message> = backendMessages.shareIn(scope, SharingStarted.Eagerly)
+ * ```
+ *
+ * Now a single connection is shared between all collectors from `messages`, and there is a chance that the connection
+ * is already established by the time it is needed.
+ *
+ * ### Upstream completion and error handling
+ *
+ * **Normal completion of the upstream flow has no effect on subscribers**, and the sharing coroutine continues to run. If a
+ * a strategy like [SharingStarted.WhileSubscribed] is used, then the upstream can get restarted again. If a special
+ * action on upstream completion is needed, then an [onCompletion] operator can be used before the
+ * `shareIn` operator to emit a special value in this case, like this:
+ *
+ * ```
+ * backendMessages
+ * .onCompletion { cause -> if (cause == null) emit(UpstreamHasCompletedMessage) }
+ * .shareIn(scope, SharingStarted.Eagerly)
+ * ```
+ *
+ * Any exception in the upstream flow terminates the sharing coroutine without affecting any of the subscribers,
+ * and will be handled by the [scope] in which the sharing coroutine is launched. Custom exception handling
+ * can be configured by using the [catch] or [retry] operators before the `shareIn` operator.
+ * For example, to retry connection on any `IOException` with 1 second delay between attempts, use:
+ *
+ * ```
+ * val messages = backendMessages
+ * .retry { e ->
+ * val shallRetry = e is IOException // other exception are bugs - handle them
+ * if (shallRetry) delay(1000)
+ * shallRetry
+ * }
+ * .shareIn(scope, SharingStarted.Eagerly)
+ * ```
+ *
+ * ### Initial value
+ *
+ * When a special initial value is needed to signal to subscribers that the upstream is still loading the data,
+ * use the [onStart] operator on the upstream flow. For example:
+ *
+ * ```
+ * backendMessages
+ * .onStart { emit(UpstreamIsStartingMessage) }
+ * .shareIn(scope, SharingStarted.Eagerly, 1) // replay one most recent message
+ * ```
+ *
+ * ### Buffering and conflation
+ *
+ * The `shareIn` operator runs the upstream flow in a separate coroutine, and buffers emissions from upstream as explained
+ * in the [buffer] operator's description, using a buffer of [replay] size or the default (whichever is larger).
+ * This default buffering can be overridden with an explicit buffer configuration by preceding the `shareIn` call
+ * with [buffer] or [conflate], for example:
+ *
+ * * `buffer(0).shareIn(scope, started, 0)` — overrides the default buffer size and creates a [SharedFlow] without a buffer.
+ * Effectively, it configures sequential processing between the upstream emitter and subscribers,
+ * as the emitter is suspended until all subscribers process the value. Note, that the value is still immediately
+ * discarded when there are no subscribers.
+ * * `buffer(b).shareIn(scope, started, r)` — creates a [SharedFlow] with `replay = r` and `extraBufferCapacity = b`.
+ * * `conflate().shareIn(scope, started, r)` — creates a [SharedFlow] with `replay = r`, `onBufferOverflow = DROP_OLDEST`,
+ * and `extraBufferCapacity = 1` when `replay == 0` to support this strategy.
+ *
+ * ### Operator fusion
+ *
+ * Application of [flowOn][Flow.flowOn], [buffer] with [RENDEZVOUS][Channel.RENDEZVOUS] capacity,
+ * or [cancellable] operators to the resulting shared flow has no effect.
+ *
+ * ### Exceptions
+ *
+ * This function throws [IllegalArgumentException] on unsupported values of parameters or combinations thereof.
+ *
+ * @param scope the coroutine scope in which sharing is started.
+ * @param started the strategy that controls when sharing is started and stopped.
+ * @param replay the number of values replayed to new subscribers (cannot be negative, defaults to zero).
+ */
+public fun <T> Flow<T>.shareIn(
+ scope: CoroutineScope,
+ started: SharingStarted,
+ replay: Int = 0
+): SharedFlow<T> {
+ val config = configureSharing(replay)
+ val shared = MutableSharedFlow<T>(
+ replay = replay,
+ extraBufferCapacity = config.extraBufferCapacity,
+ onBufferOverflow = config.onBufferOverflow
+ )
+ @Suppress("UNCHECKED_CAST")
+ scope.launchSharing(config.context, config.upstream, shared, started, NO_VALUE as T)
+ return shared.asSharedFlow()
+}
+
+private class SharingConfig<T>(
+ @JvmField val upstream: Flow<T>,
+ @JvmField val extraBufferCapacity: Int,
+ @JvmField val onBufferOverflow: BufferOverflow,
+ @JvmField val context: CoroutineContext
+)
+
+// Decomposes upstream flow to fuse with it when possible
+private fun <T> Flow<T>.configureSharing(replay: Int): SharingConfig<T> {
+ assert { replay >= 0 }
+ val defaultExtraCapacity = replay.coerceAtLeast(Channel.CHANNEL_DEFAULT_CAPACITY) - replay
+ // Combine with preceding buffer/flowOn and channel-using operators
+ if (this is ChannelFlow) {
+ // Check if this ChannelFlow can operate without a channel
+ val upstream = dropChannelOperators()
+ if (upstream != null) { // Yes, it can => eliminate the intermediate channel
+ return SharingConfig(
+ upstream = upstream,
+ extraBufferCapacity = when (capacity) {
+ Channel.OPTIONAL_CHANNEL, Channel.BUFFERED, 0 -> // handle special capacities
+ when {
+ onBufferOverflow == BufferOverflow.SUSPEND -> // buffer was configured with suspension
+ if (capacity == 0) 0 else defaultExtraCapacity // keep explicitly configured 0 or use default
+ replay == 0 -> 1 // no suspension => need at least buffer of one
+ else -> 0 // replay > 0 => no need for extra buffer beyond replay because we don't suspend
+ }
+ else -> capacity // otherwise just use the specified capacity as extra capacity
+ },
+ onBufferOverflow = onBufferOverflow,
+ context = context
+ )
+ }
+ }
+ // Add sharing operator on top with a default buffer
+ return SharingConfig(
+ upstream = this,
+ extraBufferCapacity = defaultExtraCapacity,
+ onBufferOverflow = BufferOverflow.SUSPEND,
+ context = EmptyCoroutineContext
+ )
+}
+
+// Launches sharing coroutine
+private fun <T> CoroutineScope.launchSharing(
+ context: CoroutineContext,
+ upstream: Flow<T>,
+ shared: MutableSharedFlow<T>,
+ started: SharingStarted,
+ initialValue: T
+) {
+ launch(context) { // the single coroutine to rule the sharing
+ // Optimize common built-in started strategies
+ when {
+ started === SharingStarted.Eagerly -> {
+ // collect immediately & forever
+ upstream.collect(shared)
+ }
+ started === SharingStarted.Lazily -> {
+ // start collecting on the first subscriber - wait for it first
+ shared.subscriptionCount.first { it > 0 }
+ upstream.collect(shared)
+ }
+ else -> {
+ // other & custom strategies
+ started.command(shared.subscriptionCount)
+ .distinctUntilChanged() // only changes in command have effect
+ .collectLatest { // cancels block on new emission
+ when (it) {
+ SharingCommand.START -> upstream.collect(shared) // can be cancelled
+ SharingCommand.STOP -> { /* just cancel and do nothing else */ }
+ SharingCommand.STOP_AND_RESET_REPLAY_CACHE -> {
+ if (initialValue === NO_VALUE) {
+ shared.resetReplayCache() // regular shared flow -> reset cache
+ } else {
+ shared.tryEmit(initialValue) // state flow -> reset to initial value
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+}
+
+// -------------------------------- stateIn --------------------------------
+
+/**
+ * Converts a _cold_ [Flow] into a _hot_ [StateFlow] that is started in the given coroutine [scope],
+ * sharing the most recently emitted value from a single running instance of the upstream flow with multiple
+ * downstream subscribers. See the [StateFlow] documentation for the general concepts of state flows.
+ *
+ * The starting of the sharing coroutine is controlled by the [started] parameter, as explained in the
+ * documentation for [shareIn] operator.
+ *
+ * The `stateIn` operator is useful in situations when there is a _cold_ flow that provides updates to the
+ * value of some state and is expensive to create and/or to maintain, but there are multiple subscribers
+ * that need to collect the most recent state value. For example, consider a
+ * flow of state updates coming from a backend over the expensive network connection, taking a lot of
+ * time to establish. Conceptually it might be implemented like this:
+ *
+ * ```
+ * val backendState: Flow<State> = flow {
+ * connectToBackend() // takes a lot of time
+ * try {
+ * while (true) {
+ * emit(receiveStateUpdateFromBackend())
+ * }
+ * } finally {
+ * disconnectFromBackend()
+ * }
+ * }
+ * ```
+ *
+ * If this flow is directly used in the application, then every time it is collected a fresh connection is
+ * established, and it will take a while before state updates start flowing. However, we can share a single connection
+ * and establish it eagerly like this:
+ *
+ * ```
+ * val state: StateFlow<State> = backendMessages.stateIn(scope, SharingStarted.Eagerly, State.LOADING)
+ * ```
+ *
+ * Now, a single connection is shared between all collectors from `state`, and there is a chance that the connection
+ * is already established by the time it is needed.
+ *
+ * ### Upstream completion and error handling
+ *
+ * **Normal completion of the upstream flow has no effect on subscribers**, and the sharing coroutine continues to run. If a
+ * a strategy like [SharingStarted.WhileSubscribed] is used, then the upstream can get restarted again. If a special
+ * action on upstream completion is needed, then an [onCompletion] operator can be used before
+ * the `stateIn` operator to emit a special value in this case. See the [shareIn] operator's documentation for an example.
+ *
+ * Any exception in the upstream flow terminates the sharing coroutine without affecting any of the subscribers,
+ * and will be handled by the [scope] in which the sharing coroutine is launched. Custom exception handling
+ * can be configured by using the [catch] or [retry] operators before the `stateIn` operator, similarly to
+ * the [shareIn] operator.
+ *
+ * ### Operator fusion
+ *
+ * Application of [flowOn][Flow.flowOn], [conflate][Flow.conflate],
+ * [buffer] with [CONFLATED][Channel.CONFLATED] or [RENDEZVOUS][Channel.RENDEZVOUS] capacity,
+ * [distinctUntilChanged][Flow.distinctUntilChanged], or [cancellable] operators to a state flow has no effect.
+ *
+ * @param scope the coroutine scope in which sharing is started.
+ * @param started the strategy that controls when sharing is started and stopped.
+ * @param initialValue the initial value of the state flow.
+ * This value is also used when the state flow is reset using the [SharingStarted.WhileSubscribed] strategy
+ * with the `replayExpirationMillis` parameter.
+ */
+public fun <T> Flow<T>.stateIn(
+ scope: CoroutineScope,
+ started: SharingStarted,
+ initialValue: T
+): StateFlow<T> {
+ val config = configureSharing(1)
+ val state = MutableStateFlow(initialValue)
+ scope.launchSharing(config.context, config.upstream, state, started, initialValue)
+ return state.asStateFlow()
+}
+
+/**
+ * Starts the upstream flow in a given [scope], suspends until the first value is emitted, and returns a _hot_
+ * [StateFlow] of future emissions, sharing the most recently emitted value from this running instance of the upstream flow
+ * with multiple downstream subscribers. See the [StateFlow] documentation for the general concepts of state flows.
+ *
+ * @param scope the coroutine scope in which sharing is started.
+ */
+public suspend fun <T> Flow<T>.stateIn(scope: CoroutineScope): StateFlow<T> {
+ val config = configureSharing(1)
+ val result = CompletableDeferred<StateFlow<T>>()
+ scope.launchSharingDeferred(config.context, config.upstream, result)
+ return result.await()
+}
+
+private fun <T> CoroutineScope.launchSharingDeferred(
+ context: CoroutineContext,
+ upstream: Flow<T>,
+ result: CompletableDeferred<StateFlow<T>>
+) {
+ launch(context) {
+ try {
+ var state: MutableStateFlow<T>? = null
+ upstream.collect { value ->
+ state?.let { it.value = value } ?: run {
+ state = MutableStateFlow(value).also {
+ result.complete(it.asStateFlow())
+ }
+ }
+ }
+ } catch (e: Throwable) {
+ // Notify the waiter that the flow has failed
+ result.completeExceptionally(e)
+ // But still cancel the scope where state was (not) produced
+ throw e
+ }
+ }
+}
+
+// -------------------------------- asSharedFlow/asStateFlow --------------------------------
+
+/**
+ * Represents this mutable shared flow as a read-only shared flow.
+ */
+public fun <T> MutableSharedFlow<T>.asSharedFlow(): SharedFlow<T> =
+ ReadonlySharedFlow(this)
+
+/**
+ * Represents this mutable state flow as a read-only state flow.
+ */
+public fun <T> MutableStateFlow<T>.asStateFlow(): StateFlow<T> =
+ ReadonlyStateFlow(this)
+
+private class ReadonlySharedFlow<T>(
+ flow: SharedFlow<T>
+) : SharedFlow<T> by flow, CancellableFlow<T>, FusibleFlow<T> {
+ override fun fuse(context: CoroutineContext, capacity: Int, onBufferOverflow: BufferOverflow) =
+ fuseSharedFlow(context, capacity, onBufferOverflow)
+}
+
+private class ReadonlyStateFlow<T>(
+ flow: StateFlow<T>
+) : StateFlow<T> by flow, CancellableFlow<T>, FusibleFlow<T> {
+ override fun fuse(context: CoroutineContext, capacity: Int, onBufferOverflow: BufferOverflow) =
+ fuseStateFlow(context, capacity, onBufferOverflow)
+}
+
+// -------------------------------- onSubscription --------------------------------
+
+/**
+ * Returns a flow that invokes the given [action] **after** this shared flow starts to be collected
+ * (after the subscription is registered).
+ *
+ * The [action] is called before any value is emitted from the upstream
+ * flow to this subscription but after the subscription is established. It is guaranteed that all emissions to
+ * the upstream flow that happen inside or immediately after this `onSubscription` action will be
+ * collected by this subscription.
+ *
+ * The receiver of the [action] is [FlowCollector], so `onSubscription` can emit additional elements.
+ */
+public fun <T> SharedFlow<T>.onSubscription(action: suspend FlowCollector<T>.() -> Unit): SharedFlow<T> =
+ SubscribedSharedFlow(this, action)
+
+private class SubscribedSharedFlow<T>(
+ private val sharedFlow: SharedFlow<T>,
+ private val action: suspend FlowCollector<T>.() -> Unit
+) : SharedFlow<T> by sharedFlow {
+ override suspend fun collect(collector: FlowCollector<T>) =
+ sharedFlow.collect(SubscribedFlowCollector(collector, action))
+}
+
+internal class SubscribedFlowCollector<T>(
+ private val collector: FlowCollector<T>,
+ private val action: suspend FlowCollector<T>.() -> Unit
+) : FlowCollector<T> by collector {
+ suspend fun onSubscription() {
+ val safeCollector = SafeCollector(collector, currentCoroutineContext())
+ try {
+ safeCollector.action()
+ } finally {
+ safeCollector.releaseIntercepted()
+ }
+ if (collector is SubscribedFlowCollector) collector.onSubscription()
+ }
+}
diff --git a/kotlinx-coroutines-core/common/src/flow/operators/Transform.kt b/kotlinx-coroutines-core/common/src/flow/operators/Transform.kt
index 520311e..e3552d2 100644
--- a/kotlinx-coroutines-core/common/src/flow/operators/Transform.kt
+++ b/kotlinx-coroutines-core/common/src/flow/operators/Transform.kt
@@ -67,7 +67,7 @@
}
/**
- * Returns a flow which performs the given [action] on each value of the original flow.
+ * Returns a flow that invokes the given [action] **before** each value of the upstream flow is emitted downstream.
*/
public fun <T> Flow<T>.onEach(action: suspend (T) -> Unit): Flow<T> = transform { value ->
action(value)
diff --git a/kotlinx-coroutines-core/common/src/flow/operators/Zip.kt b/kotlinx-coroutines-core/common/src/flow/operators/Zip.kt
index ec66181..790c089 100644
--- a/kotlinx-coroutines-core/common/src/flow/operators/Zip.kt
+++ b/kotlinx-coroutines-core/common/src/flow/operators/Zip.kt
@@ -8,7 +8,6 @@
package kotlinx.coroutines.flow
-import kotlinx.coroutines.*
import kotlinx.coroutines.flow.internal.*
import kotlin.jvm.*
import kotlinx.coroutines.flow.flow as safeFlow
@@ -31,9 +30,7 @@
*/
@JvmName("flowCombine")
public fun <T1, T2, R> Flow<T1>.combine(flow: Flow<T2>, transform: suspend (a: T1, b: T2) -> R): Flow<R> = flow {
- combineTransformInternal(this@combine, flow) { a, b ->
- emit(transform(a, b))
- }
+ combineInternal(arrayOf(this@combine, flow), nullArrayFactory(), { emit(transform(it[0] as T1, it[1] as T2)) })
}
/**
@@ -75,10 +72,11 @@
public fun <T1, T2, R> Flow<T1>.combineTransform(
flow: Flow<T2>,
@BuilderInference transform: suspend FlowCollector<R>.(a: T1, b: T2) -> Unit
-): Flow<R> = safeFlow {
- combineTransformInternal(this@combineTransform, flow) { a, b ->
- transform(a, b)
- }
+): Flow<R> = combineTransformUnsafe(this, flow) { args: Array<*> ->
+ transform(
+ args[0] as T1,
+ args[1] as T2
+ )
}
/**
@@ -102,7 +100,7 @@
flow: Flow<T1>,
flow2: Flow<T2>,
@BuilderInference transform: suspend FlowCollector<R>.(a: T1, b: T2) -> Unit
-): Flow<R> = combineTransform(flow, flow2) { args: Array<*> ->
+): Flow<R> = combineTransformUnsafe(flow, flow2) { args: Array<*> ->
transform(
args[0] as T1,
args[1] as T2
@@ -113,12 +111,12 @@
* Returns a [Flow] whose values are generated with [transform] function by combining
* the most recently emitted values by each flow.
*/
-public inline fun <T1, T2, T3, R> combine(
+public fun <T1, T2, T3, R> combine(
flow: Flow<T1>,
flow2: Flow<T2>,
flow3: Flow<T3>,
- @BuilderInference crossinline transform: suspend (T1, T2, T3) -> R
-): Flow<R> = combine(flow, flow2, flow3) { args: Array<*> ->
+ @BuilderInference transform: suspend (T1, T2, T3) -> R
+): Flow<R> = combineUnsafe(flow, flow2, flow3) { args: Array<*> ->
transform(
args[0] as T1,
args[1] as T2,
@@ -132,12 +130,12 @@
* The receiver of the [transform] is [FlowCollector] and thus `transform` is a
* generic function that may transform emitted element, skip it or emit it multiple times.
*/
-public inline fun <T1, T2, T3, R> combineTransform(
+public fun <T1, T2, T3, R> combineTransform(
flow: Flow<T1>,
flow2: Flow<T2>,
flow3: Flow<T3>,
- @BuilderInference crossinline transform: suspend FlowCollector<R>.(T1, T2, T3) -> Unit
-): Flow<R> = combineTransform(flow, flow2, flow3) { args: Array<*> ->
+ @BuilderInference transform: suspend FlowCollector<R>.(T1, T2, T3) -> Unit
+): Flow<R> = combineTransformUnsafe(flow, flow2, flow3) { args: Array<*> ->
transform(
args[0] as T1,
args[1] as T2,
@@ -149,12 +147,12 @@
* Returns a [Flow] whose values are generated with [transform] function by combining
* the most recently emitted values by each flow.
*/
-public inline fun <T1, T2, T3, T4, R> combine(
+public fun <T1, T2, T3, T4, R> combine(
flow: Flow<T1>,
flow2: Flow<T2>,
flow3: Flow<T3>,
flow4: Flow<T4>,
- crossinline transform: suspend (T1, T2, T3, T4) -> R
+ transform: suspend (T1, T2, T3, T4) -> R
): Flow<R> = combine(flow, flow2, flow3, flow4) { args: Array<*> ->
transform(
args[0] as T1,
@@ -170,13 +168,13 @@
* The receiver of the [transform] is [FlowCollector] and thus `transform` is a
* generic function that may transform emitted element, skip it or emit it multiple times.
*/
-public inline fun <T1, T2, T3, T4, R> combineTransform(
+public fun <T1, T2, T3, T4, R> combineTransform(
flow: Flow<T1>,
flow2: Flow<T2>,
flow3: Flow<T3>,
flow4: Flow<T4>,
- @BuilderInference crossinline transform: suspend FlowCollector<R>.(T1, T2, T3, T4) -> Unit
-): Flow<R> = combineTransform(flow, flow2, flow3, flow4) { args: Array<*> ->
+ @BuilderInference transform: suspend FlowCollector<R>.(T1, T2, T3, T4) -> Unit
+): Flow<R> = combineTransformUnsafe(flow, flow2, flow3, flow4) { args: Array<*> ->
transform(
args[0] as T1,
args[1] as T2,
@@ -189,14 +187,14 @@
* Returns a [Flow] whose values are generated with [transform] function by combining
* the most recently emitted values by each flow.
*/
-public inline fun <T1, T2, T3, T4, T5, R> combine(
+public fun <T1, T2, T3, T4, T5, R> combine(
flow: Flow<T1>,
flow2: Flow<T2>,
flow3: Flow<T3>,
flow4: Flow<T4>,
flow5: Flow<T5>,
- crossinline transform: suspend (T1, T2, T3, T4, T5) -> R
-): Flow<R> = combine(flow, flow2, flow3, flow4, flow5) { args: Array<*> ->
+ transform: suspend (T1, T2, T3, T4, T5) -> R
+): Flow<R> = combineUnsafe(flow, flow2, flow3, flow4, flow5) { args: Array<*> ->
transform(
args[0] as T1,
args[1] as T2,
@@ -212,14 +210,14 @@
* The receiver of the [transform] is [FlowCollector] and thus `transform` is a
* generic function that may transform emitted element, skip it or emit it multiple times.
*/
-public inline fun <T1, T2, T3, T4, T5, R> combineTransform(
+public fun <T1, T2, T3, T4, T5, R> combineTransform(
flow: Flow<T1>,
flow2: Flow<T2>,
flow3: Flow<T3>,
flow4: Flow<T4>,
flow5: Flow<T5>,
- @BuilderInference crossinline transform: suspend FlowCollector<R>.(T1, T2, T3, T4, T5) -> Unit
-): Flow<R> = combineTransform(flow, flow2, flow3, flow4, flow5) { args: Array<*> ->
+ @BuilderInference transform: suspend FlowCollector<R>.(T1, T2, T3, T4, T5) -> Unit
+): Flow<R> = combineTransformUnsafe(flow, flow2, flow3, flow4, flow5) { args: Array<*> ->
transform(
args[0] as T1,
args[1] as T2,
@@ -253,6 +251,31 @@
combineInternal(flows, { arrayOfNulls(flows.size) }, { transform(it) })
}
+/*
+ * Same as combine, but does not copy array each time, deconstructing existing
+ * array each time. Used in overloads that accept FunctionN instead of Function<Array<R>>
+ */
+private inline fun <reified T, R> combineUnsafe(
+ vararg flows: Flow<T>,
+ crossinline transform: suspend (Array<T>) -> R
+): Flow<R> = flow {
+ combineInternal(flows, nullArrayFactory(), { emit(transform(it)) })
+}
+
+/*
+ * Same as combineTransform, but does not copy array each time, deconstructing existing
+ * array each time. Used in overloads that accept FunctionN instead of Function<Array<R>>
+ */
+private inline fun <reified T, R> combineTransformUnsafe(
+ vararg flows: Flow<T>,
+ @BuilderInference crossinline transform: suspend FlowCollector<R>.(Array<T>) -> Unit
+): Flow<R> = safeFlow {
+ combineInternal(flows, nullArrayFactory(), { transform(it) })
+}
+
+// Saves bunch of anonymous classes
+private fun <T> nullArrayFactory(): () -> Array<T>? = { null }
+
/**
* Returns a [Flow] whose values are generated with [transform] function by combining
* the most recently emitted values by each flow.
@@ -298,5 +321,11 @@
* println(it) // Will print "1a 2b 3c"
* }
* ```
+ *
+ * ### Buffering
+ *
+ * The upstream flow is collected sequentially in the same coroutine without any buffering, while the
+ * [other] flow is collected concurrently as if `buffer(0)` is used. See documentation in the [buffer] operator
+ * for explanation. You can use additional calls to the [buffer] operator as needed for more concurrency.
*/
public fun <T1, T2, R> Flow<T1>.zip(other: Flow<T2>, transform: suspend (T1, T2) -> R): Flow<R> = zipImpl(this, other, transform)
diff --git a/kotlinx-coroutines-core/common/src/flow/terminal/Reduce.kt b/kotlinx-coroutines-core/common/src/flow/terminal/Reduce.kt
index d36e1bb..83f5498 100644
--- a/kotlinx-coroutines-core/common/src/flow/terminal/Reduce.kt
+++ b/kotlinx-coroutines-core/common/src/flow/terminal/Reduce.kt
@@ -9,6 +9,7 @@
package kotlinx.coroutines.flow
import kotlinx.coroutines.flow.internal.*
+import kotlinx.coroutines.internal.Symbol
import kotlin.jvm.*
/**
@@ -47,33 +48,39 @@
}
/**
- * The terminal operator, that awaits for one and only one value to be published.
+ * The terminal operator that awaits for one and only one value to be emitted.
* Throws [NoSuchElementException] for empty flow and [IllegalStateException] for flow
* that contains more than one element.
*/
public suspend fun <T> Flow<T>.single(): T {
var result: Any? = NULL
collect { value ->
- if (result !== NULL) error("Expected only one element")
+ require(result === NULL) { "Flow has more than one element" }
result = value
}
- if (result === NULL) throw NoSuchElementException("Expected at least one element")
- @Suppress("UNCHECKED_CAST")
+ if (result === NULL) throw NoSuchElementException("Flow is empty")
return result as T
}
/**
- * The terminal operator, that awaits for one and only one value to be published.
- * Throws [IllegalStateException] for flow that contains more than one element.
+ * The terminal operator that awaits for one and only one value to be emitted.
+ * Returns the single value or `null`, if the flow was empty or emitted more than one value.
*/
-public suspend fun <T: Any> Flow<T>.singleOrNull(): T? {
- var result: T? = null
- collect { value ->
- if (result != null) error("Expected only one element")
- result = value
+public suspend fun <T> Flow<T>.singleOrNull(): T? {
+ var result: Any? = NULL
+ collectWhile {
+ // No values yet, update result
+ if (result === NULL) {
+ result = it
+ true
+ } else {
+ // Second value, reset result and bail out
+ result = NULL
+ false
+ }
}
- return result
+ return if (result === NULL) null else result as T
}
/**
@@ -112,7 +119,7 @@
* The terminal operator that returns the first element emitted by the flow and then cancels flow's collection.
* Returns `null` if the flow was empty.
*/
-public suspend fun <T : Any> Flow<T>.firstOrNull(): T? {
+public suspend fun <T> Flow<T>.firstOrNull(): T? {
var result: T? = null
collectWhile {
result = it
@@ -122,10 +129,10 @@
}
/**
- * The terminal operator that returns the first element emitted by the flow matching the given [predicate] and then cancels flow's collection.
+ * The terminal operator that returns the first element emitted by the flow matching the given [predicate] and then cancels flow's collection.
* Returns `null` if the flow did not contain an element matching the [predicate].
*/
-public suspend fun <T : Any> Flow<T>.firstOrNull(predicate: suspend (T) -> Boolean): T? {
+public suspend fun <T> Flow<T>.firstOrNull(predicate: suspend (T) -> Boolean): T? {
var result: T? = null
collectWhile {
if (predicate(it)) {
diff --git a/kotlinx-coroutines-core/common/src/internal/Atomic.kt b/kotlinx-coroutines-core/common/src/internal/Atomic.kt
index 94f6ab9..a27d549 100644
--- a/kotlinx-coroutines-core/common/src/internal/Atomic.kt
+++ b/kotlinx-coroutines-core/common/src/internal/Atomic.kt
@@ -39,7 +39,8 @@
}
@SharedImmutable
-private val NO_DECISION: Any = Symbol("NO_DECISION")
+@JvmField
+internal val NO_DECISION: Any = Symbol("NO_DECISION")
/**
* Descriptor for multi-word atomic operation.
@@ -52,9 +53,13 @@
*
* @suppress **This is unstable API and it is subject to change.**
*/
+@InternalCoroutinesApi
public abstract class AtomicOp<in T> : OpDescriptor() {
private val _consensus = atomic<Any?>(NO_DECISION)
+ // Returns NO_DECISION when there is not decision yet
+ val consensus: Any? get() = _consensus.value
+
val isDecided: Boolean get() = _consensus.value !== NO_DECISION
/**
diff --git a/kotlinx-coroutines-core/common/src/internal/DispatchedContinuation.kt b/kotlinx-coroutines-core/common/src/internal/DispatchedContinuation.kt
index cf31fcf..b7b2954 100644
--- a/kotlinx-coroutines-core/common/src/internal/DispatchedContinuation.kt
+++ b/kotlinx-coroutines-core/common/src/internal/DispatchedContinuation.kt
@@ -2,10 +2,10 @@
* Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
*/
-package kotlinx.coroutines
+package kotlinx.coroutines.internal
import kotlinx.atomicfu.*
-import kotlinx.coroutines.internal.*
+import kotlinx.coroutines.*
import kotlin.coroutines.*
import kotlin.jvm.*
import kotlin.native.concurrent.*
@@ -19,7 +19,7 @@
internal class DispatchedContinuation<in T>(
@JvmField val dispatcher: CoroutineDispatcher,
@JvmField val continuation: Continuation<T>
-) : DispatchedTask<T>(MODE_ATOMIC_DEFAULT), CoroutineStackFrame, Continuation<T> by continuation {
+) : DispatchedTask<T>(MODE_UNINITIALIZED), CoroutineStackFrame, Continuation<T> by continuation {
@JvmField
@Suppress("PropertyName")
internal var _state: Any? = UNDEFINED
@@ -37,19 +37,19 @@
* 3) [REUSABLE_CLAIMED]. CC is currently being reused and its owner executes `suspend` block:
* ```
* // state == null | CC
- * suspendAtomicCancellableCoroutineReusable { cont ->
+ * suspendCancellableCoroutineReusable { cont ->
* // state == REUSABLE_CLAIMED
* block(cont)
* }
* // state == CC
* ```
- * 4) [Throwable] continuation was cancelled with this cause while being in [suspendAtomicCancellableCoroutineReusable],
+ * 4) [Throwable] continuation was cancelled with this cause while being in [suspendCancellableCoroutineReusable],
* [CancellableContinuationImpl.getResult] will check for cancellation later.
*
* [REUSABLE_CLAIMED] state is required to prevent the lost resume in the channel.
* AbstractChannel.receive method relies on the fact that the following pattern
* ```
- * suspendAtomicCancellableCoroutineReusable { cont ->
+ * suspendCancellableCoroutineReusable { cont ->
* val result = pollFastPath()
* if (result != null) cont.resume(result)
* }
@@ -67,12 +67,12 @@
/*
* Reusability control:
* `null` -> no reusability at all, false
- * If current state is not CCI, then we are within `suspendAtomicCancellableCoroutineReusable`, true
+ * If current state is not CCI, then we are within `suspendCancellableCoroutineReusable`, true
* Else, if result is CCI === requester.
* Identity check my fail for the following pattern:
* ```
* loop:
- * suspendAtomicCancellableCoroutineReusable { } // Reusable, outer coroutine stores the child handle
+ * suspendCancellableCoroutineReusable { } // Reusable, outer coroutine stores the child handle
* suspendCancellableCoroutine { } // **Not reusable**, handle should be disposed after {}, otherwise
* it will leak because it won't be freed by `releaseInterceptedContinuation`
* ```
@@ -83,7 +83,7 @@
}
/**
- * Claims the continuation for [suspendAtomicCancellableCoroutineReusable] block,
+ * Claims the continuation for [suspendCancellableCoroutineReusable] block,
* so all cancellations will be postponed.
*/
@Suppress("UNCHECKED_CAST")
@@ -119,7 +119,7 @@
* If continuation was cancelled, it becomes non-reusable.
*
* ```
- * suspendAtomicCancellableCoroutineReusable { // <- claimed
+ * suspendCancellableCoroutineReusable { // <- claimed
* // Any asynchronous cancellation is "postponed" while this block
* // is being executed
* } // postponed cancellation is checked here in `getResult`
@@ -180,10 +180,10 @@
val state = result.toState()
if (dispatcher.isDispatchNeeded(context)) {
_state = state
- resumeMode = MODE_ATOMIC_DEFAULT
+ resumeMode = MODE_ATOMIC
dispatcher.dispatch(context, this)
} else {
- executeUnconfined(state, MODE_ATOMIC_DEFAULT) {
+ executeUnconfined(state, MODE_ATOMIC) {
withCoroutineContext(this.context, countOrElement) {
continuation.resumeWith(result)
}
@@ -194,29 +194,42 @@
// We inline it to save an entry on the stack in cases where it shows (unconfined dispatcher)
// It is used only in Continuation<T>.resumeCancellableWith
@Suppress("NOTHING_TO_INLINE")
- inline fun resumeCancellableWith(result: Result<T>) {
- val state = result.toState()
+ inline fun resumeCancellableWith(
+ result: Result<T>,
+ noinline onCancellation: ((cause: Throwable) -> Unit)?
+ ) {
+ val state = result.toState(onCancellation)
if (dispatcher.isDispatchNeeded(context)) {
_state = state
resumeMode = MODE_CANCELLABLE
dispatcher.dispatch(context, this)
} else {
executeUnconfined(state, MODE_CANCELLABLE) {
- if (!resumeCancelled()) {
+ if (!resumeCancelled(state)) {
resumeUndispatchedWith(result)
}
}
}
}
+ // takeState had already cleared the state so we cancel takenState here
+ override fun cancelCompletedResult(takenState: Any?, cause: Throwable) {
+ // It is Ok to call onCancellation here without try/catch around it, since this function only faces
+ // a "bound" cancellation handler that performs the safe call to the user-specified code.
+ if (takenState is CompletedWithCancellation) {
+ takenState.onCancellation(cause)
+ }
+ }
+
@Suppress("NOTHING_TO_INLINE")
- inline fun resumeCancelled(): Boolean {
+ inline fun resumeCancelled(state: Any?): Boolean {
val job = context[Job]
if (job != null && !job.isActive) {
- resumeWithException(job.getCancellationException())
+ val cause = job.getCancellationException()
+ cancelCompletedResult(state, cause)
+ resumeWithException(cause)
return true
}
-
return false
}
@@ -245,8 +258,11 @@
* @suppress **This an internal API and should not be used from general code.**
*/
@InternalCoroutinesApi
-public fun <T> Continuation<T>.resumeCancellableWith(result: Result<T>): Unit = when (this) {
- is DispatchedContinuation -> resumeCancellableWith(result)
+public fun <T> Continuation<T>.resumeCancellableWith(
+ result: Result<T>,
+ onCancellation: ((cause: Throwable) -> Unit)? = null
+): Unit = when (this) {
+ is DispatchedContinuation -> resumeCancellableWith(result, onCancellation)
else -> resumeWith(result)
}
@@ -265,6 +281,7 @@
contState: Any?, mode: Int, doYield: Boolean = false,
block: () -> Unit
): Boolean {
+ assert { mode != MODE_UNINITIALIZED } // invalid execution mode
val eventLoop = ThreadLocalEventLoop.eventLoop
// If we are yielding and unconfined queue is empty, we can bail out as part of fast path
if (doYield && eventLoop.isUnconfinedQueueEmpty) return false
diff --git a/kotlinx-coroutines-core/common/src/internal/DispatchedTask.kt b/kotlinx-coroutines-core/common/src/internal/DispatchedTask.kt
index 32258ba..1f4942a 100644
--- a/kotlinx-coroutines-core/common/src/internal/DispatchedTask.kt
+++ b/kotlinx-coroutines-core/common/src/internal/DispatchedTask.kt
@@ -8,12 +8,44 @@
import kotlin.coroutines.*
import kotlin.jvm.*
-@PublishedApi internal const val MODE_ATOMIC_DEFAULT = 0 // schedule non-cancellable dispatch for suspendCoroutine
-@PublishedApi internal const val MODE_CANCELLABLE = 1 // schedule cancellable dispatch for suspendCancellableCoroutine
-@PublishedApi internal const val MODE_UNDISPATCHED = 2 // when the thread is right, but need to mark it with current coroutine
+/**
+ * Non-cancellable dispatch mode.
+ *
+ * **DO NOT CHANGE THE CONSTANT VALUE**. It might be inlined into legacy user code that was calling
+ * inline `suspendAtomicCancellableCoroutine` function and did not support reuse.
+ */
+internal const val MODE_ATOMIC = 0
-internal val Int.isCancellableMode get() = this == MODE_CANCELLABLE
-internal val Int.isDispatchedMode get() = this == MODE_ATOMIC_DEFAULT || this == MODE_CANCELLABLE
+/**
+ * Cancellable dispatch mode. It is used by user-facing [suspendCancellableCoroutine].
+ * Note, that implementation of cancellability checks mode via [Int.isCancellableMode] extension.
+ *
+ * **DO NOT CHANGE THE CONSTANT VALUE**. It is being into the user code from [suspendCancellableCoroutine].
+ */
+@PublishedApi
+internal const val MODE_CANCELLABLE = 1
+
+/**
+ * Cancellable dispatch mode for [suspendCancellableCoroutineReusable].
+ * Note, that implementation of cancellability checks mode via [Int.isCancellableMode] extension;
+ * implementation of reuse checks mode via [Int.isReusableMode] extension.
+ */
+internal const val MODE_CANCELLABLE_REUSABLE = 2
+
+/**
+ * Undispatched mode for [CancellableContinuation.resumeUndispatched].
+ * It is used when the thread is right, but it needs to be marked with the current coroutine.
+ */
+internal const val MODE_UNDISPATCHED = 4
+
+/**
+ * Initial mode for [DispatchedContinuation] implementation, should never be used for dispatch, because it is always
+ * overwritten when continuation is resumed with the actual resume mode.
+ */
+internal const val MODE_UNINITIALIZED = -1
+
+internal val Int.isCancellableMode get() = this == MODE_CANCELLABLE || this == MODE_CANCELLABLE_REUSABLE
+internal val Int.isReusableMode get() = this == MODE_CANCELLABLE_REUSABLE
internal abstract class DispatchedTask<in T>(
@JvmField public var resumeMode: Int
@@ -22,16 +54,32 @@
internal abstract fun takeState(): Any?
- internal open fun cancelResult(state: Any?, cause: Throwable) {}
+ /**
+ * Called when this task was cancelled while it was being dispatched.
+ */
+ internal open fun cancelCompletedResult(takenState: Any?, cause: Throwable) {}
+ /**
+ * There are two implementations of `DispatchedTask`:
+ * * [DispatchedContinuation] keeps only simple values as successfully results.
+ * * [CancellableContinuationImpl] keeps additional data with values and overrides this method to unwrap it.
+ */
@Suppress("UNCHECKED_CAST")
internal open fun <T> getSuccessfulResult(state: Any?): T =
state as T
- internal fun getExceptionalResult(state: Any?): Throwable? =
+ /**
+ * There are two implementations of `DispatchedTask`:
+ * * [DispatchedContinuation] is just an intermediate storage that stores the exception that has its stack-trace
+ * properly recovered and is ready to pass to the [delegate] continuation directly.
+ * * [CancellableContinuationImpl] stores raw cause of the failure in its state; when it needs to be dispatched
+ * its stack-trace has to be recovered, so it overrides this method for that purpose.
+ */
+ internal open fun getExceptionalResult(state: Any?): Throwable? =
(state as? CompletedExceptionally)?.cause
public final override fun run() {
+ assert { resumeMode != MODE_UNINITIALIZED } // should have been set before dispatching
val taskContext = this.taskContext
var fatalException: Throwable? = null
try {
@@ -41,19 +89,22 @@
val state = takeState() // NOTE: Must take state in any case, even if cancelled
withCoroutineContext(context, delegate.countOrElement) {
val exception = getExceptionalResult(state)
- val job = if (resumeMode.isCancellableMode) context[Job] else null
/*
* Check whether continuation was originally resumed with an exception.
* If so, it dominates cancellation, otherwise the original exception
* will be silently lost.
*/
- if (exception == null && job != null && !job.isActive) {
+ val job = if (exception == null && resumeMode.isCancellableMode) context[Job] else null
+ if (job != null && !job.isActive) {
val cause = job.getCancellationException()
- cancelResult(state, cause)
+ cancelCompletedResult(state, cause)
continuation.resumeWithStackTrace(cause)
} else {
- if (exception != null) continuation.resumeWithException(exception)
- else continuation.resume(getSuccessfulResult(state))
+ if (exception != null) {
+ continuation.resumeWithException(exception)
+ } else {
+ continuation.resume(getSuccessfulResult(state))
+ }
}
}
} catch (e: Throwable) {
@@ -97,8 +148,10 @@
}
internal fun <T> DispatchedTask<T>.dispatch(mode: Int) {
+ assert { mode != MODE_UNINITIALIZED } // invalid mode value for this method
val delegate = this.delegate
- if (mode.isDispatchedMode && delegate is DispatchedContinuation<*> && mode.isCancellableMode == resumeMode.isCancellableMode) {
+ val undispatched = mode == MODE_UNDISPATCHED
+ if (!undispatched && delegate is DispatchedContinuation<*> && mode.isCancellableMode == resumeMode.isCancellableMode) {
// dispatch directly using this instance's Runnable implementation
val dispatcher = delegate.dispatcher
val context = delegate.context
@@ -108,21 +161,21 @@
resumeUnconfined()
}
} else {
- resume(delegate, mode)
+ // delegate is coming from 3rd-party interceptor implementation (and does not support cancellation)
+ // or undispatched mode was requested
+ resume(delegate, undispatched)
}
}
@Suppress("UNCHECKED_CAST")
-internal fun <T> DispatchedTask<T>.resume(delegate: Continuation<T>, useMode: Int) {
- // slow-path - use delegate
+internal fun <T> DispatchedTask<T>.resume(delegate: Continuation<T>, undispatched: Boolean) {
+ // This resume is never cancellable. The result is always delivered to delegate continuation.
val state = takeState()
- val exception = getExceptionalResult(state)?.let { recoverStackTrace(it, delegate) }
+ val exception = getExceptionalResult(state)
val result = if (exception != null) Result.failure(exception) else Result.success(getSuccessfulResult<T>(state))
- when (useMode) {
- MODE_ATOMIC_DEFAULT -> delegate.resumeWith(result)
- MODE_CANCELLABLE -> delegate.resumeCancellableWith(result)
- MODE_UNDISPATCHED -> (delegate as DispatchedContinuation).resumeUndispatchedWith(result)
- else -> error("Invalid mode $useMode")
+ when {
+ undispatched -> (delegate as DispatchedContinuation).resumeUndispatchedWith(result)
+ else -> delegate.resumeWith(result)
}
}
@@ -134,7 +187,7 @@
} else {
// Was not active -- run event loop until all unconfined tasks are executed
runUnconfinedEventLoop(eventLoop) {
- resume(delegate, MODE_UNDISPATCHED)
+ resume(delegate, undispatched = true)
}
}
}
diff --git a/kotlinx-coroutines-core/common/src/internal/LocalAtomics.common.kt b/kotlinx-coroutines-core/common/src/internal/LocalAtomics.common.kt
new file mode 100644
index 0000000..bcfb932
--- /dev/null
+++ b/kotlinx-coroutines-core/common/src/internal/LocalAtomics.common.kt
@@ -0,0 +1,21 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.internal
+
+/*
+ * These are atomics that are used as local variables
+ * where atomicfu doesn't support its tranformations.
+ *
+ * Have `Local` prefix to avoid AFU clashes during star-imports
+ */
+internal expect class LocalAtomicInt(value: Int) {
+ fun get(): Int
+ fun set(value: Int)
+ fun decrementAndGet(): Int
+}
+
+internal inline var LocalAtomicInt.value
+ get() = get()
+ set(value) = set(value)
diff --git a/kotlinx-coroutines-core/common/src/internal/LockFreeLinkedList.common.kt b/kotlinx-coroutines-core/common/src/internal/LockFreeLinkedList.common.kt
index f1663c3..8508e39 100644
--- a/kotlinx-coroutines-core/common/src/internal/LockFreeLinkedList.common.kt
+++ b/kotlinx-coroutines-core/common/src/internal/LockFreeLinkedList.common.kt
@@ -73,6 +73,7 @@
protected open fun retry(affected: LockFreeLinkedListNode, next: Any): Boolean
public abstract fun finishPrepare(prepareOp: PrepareOp) // non-null on failure
public open fun onPrepare(prepareOp: PrepareOp): Any? // non-null on failure
+ public open fun onRemoved(affected: LockFreeLinkedListNode) // non-null on failure
protected abstract fun finishOnSuccess(affected: LockFreeLinkedListNode, next: LockFreeLinkedListNode)
}
diff --git a/kotlinx-coroutines-core/common/src/internal/OnUndeliveredElement.kt b/kotlinx-coroutines-core/common/src/internal/OnUndeliveredElement.kt
new file mode 100644
index 0000000..1744359
--- /dev/null
+++ b/kotlinx-coroutines-core/common/src/internal/OnUndeliveredElement.kt
@@ -0,0 +1,43 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.internal
+
+import kotlinx.coroutines.*
+import kotlin.coroutines.*
+
+internal typealias OnUndeliveredElement<E> = (E) -> Unit
+
+internal fun <E> OnUndeliveredElement<E>.callUndeliveredElementCatchingException(
+ element: E,
+ undeliveredElementException: UndeliveredElementException? = null
+): UndeliveredElementException? {
+ try {
+ invoke(element)
+ } catch (ex: Throwable) {
+ // undeliveredElementException.cause !== ex is an optimization in case the same exception is thrown
+ // over and over again by on OnUndeliveredElement
+ if (undeliveredElementException != null && undeliveredElementException.cause !== ex) {
+ undeliveredElementException.addSuppressedThrowable(ex)
+ } else {
+ return UndeliveredElementException("Exception in undelivered element handler for $element", ex)
+ }
+ }
+ return undeliveredElementException
+}
+
+internal fun <E> OnUndeliveredElement<E>.callUndeliveredElement(element: E, context: CoroutineContext) {
+ callUndeliveredElementCatchingException(element, null)?.let { ex ->
+ handleCoroutineException(context, ex)
+ }
+}
+
+internal fun <E> OnUndeliveredElement<E>.bindCancellationFun(element: E, context: CoroutineContext): (Throwable) -> Unit =
+ { _: Throwable -> callUndeliveredElement(element, context) }
+
+/**
+ * Internal exception that is thrown when [OnUndeliveredElement] handler in
+ * a [kotlinx.coroutines.channels.Channel] throws an exception.
+ */
+internal class UndeliveredElementException(message: String, cause: Throwable) : RuntimeException(message, cause)
diff --git a/kotlinx-coroutines-core/common/src/intrinsics/Cancellable.kt b/kotlinx-coroutines-core/common/src/intrinsics/Cancellable.kt
index 1b1c389..f814b15 100644
--- a/kotlinx-coroutines-core/common/src/intrinsics/Cancellable.kt
+++ b/kotlinx-coroutines-core/common/src/intrinsics/Cancellable.kt
@@ -5,6 +5,7 @@
package kotlinx.coroutines.intrinsics
import kotlinx.coroutines.*
+import kotlinx.coroutines.internal.*
import kotlin.coroutines.*
import kotlin.coroutines.intrinsics.*
@@ -21,9 +22,12 @@
* Use this function to start coroutine in a cancellable way, so that it can be cancelled
* while waiting to be dispatched.
*/
-internal fun <R, T> (suspend (R) -> T).startCoroutineCancellable(receiver: R, completion: Continuation<T>) =
+internal fun <R, T> (suspend (R) -> T).startCoroutineCancellable(
+ receiver: R, completion: Continuation<T>,
+ onCancellation: ((cause: Throwable) -> Unit)? = null
+) =
runSafely(completion) {
- createCoroutineUnintercepted(receiver, completion).intercepted().resumeCancellableWith(Result.success(Unit))
+ createCoroutineUnintercepted(receiver, completion).intercepted().resumeCancellableWith(Result.success(Unit), onCancellation)
}
/**
diff --git a/kotlinx-coroutines-core/common/src/selects/Select.kt b/kotlinx-coroutines-core/common/src/selects/Select.kt
index e744a0c..99c54f8 100644
--- a/kotlinx-coroutines-core/common/src/selects/Select.kt
+++ b/kotlinx-coroutines-core/common/src/selects/Select.kt
@@ -189,14 +189,8 @@
*
* This suspending function is cancellable. If the [Job] of the current coroutine is cancelled or completed while this
* function is suspended, this function immediately resumes with [CancellationException].
- *
- * Atomicity of cancellation depends on the clause: [onSend][SendChannel.onSend], [onReceive][ReceiveChannel.onReceive],
- * [onReceiveOrNull][ReceiveChannel.onReceiveOrNull], and [onLock][Mutex.onLock] clauses are
- * *atomically cancellable*. When select throws [CancellationException] it means that those clauses had not performed
- * their respective operations.
- * As a side-effect of atomic cancellation, a thread-bound coroutine (to some UI thread, for example) may
- * continue to execute even after it was cancelled from the same thread in the case when this select operation
- * was already resumed on atomically cancellable clause and the continuation was posted for execution to the thread's queue.
+ * There is a **prompt cancellation guarantee**. If the job was cancelled while this function was
+ * suspended, it will not resume successfully. See [suspendCancellableCoroutine] documentation for low-level details.
*
* Note that this function does not check for cancellation when it is not suspended.
* Use [yield] or [CoroutineScope.isActive] to periodically check for cancellation in tight loops if needed.
@@ -655,7 +649,7 @@
if (trySelect())
block.startCoroutineCancellable(completion) // shall be cancellable while waits for dispatch
}
- disposeOnSelect(context.delay.invokeOnTimeout(timeMillis, action))
+ disposeOnSelect(context.delay.invokeOnTimeout(timeMillis, action, context))
}
private class DisposeNode(
diff --git a/kotlinx-coroutines-core/common/src/sync/Mutex.kt b/kotlinx-coroutines-core/common/src/sync/Mutex.kt
index 61e046c..73aaab5 100644
--- a/kotlinx-coroutines-core/common/src/sync/Mutex.kt
+++ b/kotlinx-coroutines-core/common/src/sync/Mutex.kt
@@ -45,12 +45,10 @@
*
* This suspending function is cancellable. If the [Job] of the current coroutine is cancelled or completed while this
* function is suspended, this function immediately resumes with [CancellationException].
- *
- * *Cancellation of suspended lock invocation is atomic* -- when this function
- * throws [CancellationException] it means that the mutex was not locked.
- * As a side-effect of atomic cancellation, a thread-bound coroutine (to some UI thread, for example) may
- * continue to execute even after it was cancelled from the same thread in the case when this lock operation
- * was already resumed and the continuation was posted for execution to the thread's queue.
+ * There is a **prompt cancellation guarantee**. If the job was cancelled while this function was
+ * suspended, it will not resume successfully. See [suspendCancellableCoroutine] documentation for low-level details.
+ * This function releases the lock if it was already acquired by this function before the [CancellationException]
+ * was thrown.
*
* Note that this function does not check for cancellation when it is not suspended.
* Use [yield] or [CoroutineScope.isActive] to periodically check for cancellation in tight loops if needed.
@@ -124,8 +122,6 @@
@SharedImmutable
private val LOCK_FAIL = Symbol("LOCK_FAIL")
@SharedImmutable
-private val ENQUEUE_FAIL = Symbol("ENQUEUE_FAIL")
-@SharedImmutable
private val UNLOCK_FAIL = Symbol("UNLOCK_FAIL")
@SharedImmutable
private val SELECT_SUCCESS = Symbol("SELECT_SUCCESS")
@@ -194,7 +190,7 @@
return lockSuspend(owner)
}
- private suspend fun lockSuspend(owner: Any?) = suspendAtomicCancellableCoroutineReusable<Unit> sc@ { cont ->
+ private suspend fun lockSuspend(owner: Any?) = suspendCancellableCoroutineReusable<Unit> sc@ { cont ->
val waiter = LockCont(owner, cont)
_state.loop { state ->
when (state) {
@@ -254,7 +250,7 @@
}
is LockedQueue -> {
check(state.owner !== owner) { "Already locked by $owner" }
- val node = LockSelect(owner, this, select, block)
+ val node = LockSelect(owner, select, block)
if (state.addLastIf(node) { _state.value === state }) {
// successfully enqueued
select.disposeOnSelect(node)
@@ -352,7 +348,7 @@
override fun toString(): String = "LockedQueue[$owner]"
}
- private abstract class LockWaiter(
+ private abstract inner class LockWaiter(
@JvmField val owner: Any?
) : LockFreeLinkedListNode(), DisposableHandle {
final override fun dispose() { remove() }
@@ -360,27 +356,32 @@
abstract fun completeResumeLockWaiter(token: Any)
}
- private class LockCont(
+ private inner class LockCont(
owner: Any?,
@JvmField val cont: CancellableContinuation<Unit>
) : LockWaiter(owner) {
- override fun tryResumeLockWaiter() = cont.tryResume(Unit)
+ override fun tryResumeLockWaiter() = cont.tryResume(Unit, idempotent = null) {
+ // if this continuation gets cancelled during dispatch to the caller, then release the lock
+ unlock(owner)
+ }
override fun completeResumeLockWaiter(token: Any) = cont.completeResume(token)
- override fun toString(): String = "LockCont[$owner, $cont]"
+ override fun toString(): String = "LockCont[$owner, $cont] for ${this@MutexImpl}"
}
- private class LockSelect<R>(
+ private inner class LockSelect<R>(
owner: Any?,
- @JvmField val mutex: Mutex,
@JvmField val select: SelectInstance<R>,
@JvmField val block: suspend (Mutex) -> R
) : LockWaiter(owner) {
override fun tryResumeLockWaiter(): Any? = if (select.trySelect()) SELECT_SUCCESS else null
override fun completeResumeLockWaiter(token: Any) {
assert { token === SELECT_SUCCESS }
- block.startCoroutine(receiver = mutex, completion = select.completion)
+ block.startCoroutineCancellable(receiver = this@MutexImpl, completion = select.completion) {
+ // if this continuation gets cancelled during dispatch to the caller, then release the lock
+ unlock(owner)
+ }
}
- override fun toString(): String = "LockSelect[$owner, $mutex, $select]"
+ override fun toString(): String = "LockSelect[$owner, $select] for ${this@MutexImpl}"
}
// atomic unlock operation that checks that waiters queue is empty
diff --git a/kotlinx-coroutines-core/common/src/sync/Semaphore.kt b/kotlinx-coroutines-core/common/src/sync/Semaphore.kt
index 27c976c..84b7f4f 100644
--- a/kotlinx-coroutines-core/common/src/sync/Semaphore.kt
+++ b/kotlinx-coroutines-core/common/src/sync/Semaphore.kt
@@ -33,9 +33,10 @@
*
* This suspending function is cancellable. If the [Job] of the current coroutine is cancelled or completed while this
* function is suspended, this function immediately resumes with [CancellationException].
- *
- * *Cancellation of suspended semaphore acquisition is atomic* -- when this function
- * throws [CancellationException] it means that the semaphore was not acquired.
+ * There is a **prompt cancellation guarantee**. If the job was cancelled while this function was
+ * suspended, it will not resume successfully. See [suspendCancellableCoroutine] documentation for low-level details.
+ * This function releases the semaphore if it was already acquired by this function before the [CancellationException]
+ * was thrown.
*
* Note, that this function does not check for cancellation when it does not suspend.
* Use [CoroutineScope.isActive] or [CoroutineScope.ensureActive] to periodically
@@ -148,6 +149,8 @@
private val _availablePermits = atomic(permits - acquiredPermits)
override val availablePermits: Int get() = max(_availablePermits.value, 0)
+ private val onCancellationRelease = { _: Throwable -> release() }
+
override fun tryAcquire(): Boolean {
_availablePermits.loop { p ->
if (p <= 0) return false
@@ -164,7 +167,7 @@
acquireSlowPath()
}
- private suspend fun acquireSlowPath() = suspendAtomicCancellableCoroutineReusable<Unit> sc@ { cont ->
+ private suspend fun acquireSlowPath() = suspendCancellableCoroutineReusable<Unit> sc@ { cont ->
while (true) {
if (addAcquireToQueue(cont)) return@sc
val p = _availablePermits.getAndDecrement()
@@ -203,6 +206,8 @@
// On CAS failure -- the cell must be either PERMIT or BROKEN
// If the cell already has PERMIT from tryResumeNextFromQueue, try to grab it
if (segment.cas(i, PERMIT, TAKEN)) { // took permit thus eliminating acquire/release pair
+ // The following resume must always succeed, since continuation was not published yet and we don't have
+ // to pass onCancellationRelease handle, since the coroutine did not suspend yet and cannot be cancelled
cont.resume(Unit)
return true
}
@@ -232,15 +237,15 @@
return !segment.cas(i, PERMIT, BROKEN)
}
cellState === CANCELLED -> return false // the acquire was already cancelled
- else -> return (cellState as CancellableContinuation<Unit>).tryResume()
+ else -> return (cellState as CancellableContinuation<Unit>).tryResumeAcquire()
}
}
-}
-private fun CancellableContinuation<Unit>.tryResume(): Boolean {
- val token = tryResume(Unit) ?: return false
- completeResume(token)
- return true
+ private fun CancellableContinuation<Unit>.tryResumeAcquire(): Boolean {
+ val token = tryResume(Unit, null, onCancellationRelease) ?: return false
+ completeResume(token)
+ return true
+ }
}
private class CancelSemaphoreAcquisitionHandler(
diff --git a/kotlinx-coroutines-core/common/test/AtomicCancellationCommonTest.kt b/kotlinx-coroutines-core/common/test/AtomicCancellationCommonTest.kt
index a9f58dd..c763faf 100644
--- a/kotlinx-coroutines-core/common/test/AtomicCancellationCommonTest.kt
+++ b/kotlinx-coroutines-core/common/test/AtomicCancellationCommonTest.kt
@@ -87,23 +87,23 @@
}
@Test
- fun testLockAtomicCancel() = runTest {
+ fun testLockCancellable() = runTest {
expect(1)
val mutex = Mutex(true) // locked mutex
val job = launch(start = CoroutineStart.UNDISPATCHED) {
expect(2)
mutex.lock() // suspends
- expect(4) // should execute despite cancellation
+ expectUnreached() // should NOT execute because of cancellation
}
expect(3)
mutex.unlock() // unlock mutex first
job.cancel() // cancel the job next
yield() // now yield
- finish(5)
+ finish(4)
}
@Test
- fun testSelectLockAtomicCancel() = runTest {
+ fun testSelectLockCancellable() = runTest {
expect(1)
val mutex = Mutex(true) // locked mutex
val job = launch(start = CoroutineStart.UNDISPATCHED) {
@@ -114,13 +114,12 @@
"OK"
}
}
- assertEquals("OK", result)
- expect(5) // should execute despite cancellation
+ expectUnreached() // should NOT execute because of cancellation
}
expect(3)
mutex.unlock() // unlock mutex first
job.cancel() // cancel the job next
yield() // now yield
- finish(6)
+ finish(4)
}
}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/common/test/AwaitCancellationTest.kt b/kotlinx-coroutines-core/common/test/AwaitCancellationTest.kt
new file mode 100644
index 0000000..2fe0c91
--- /dev/null
+++ b/kotlinx-coroutines-core/common/test/AwaitCancellationTest.kt
@@ -0,0 +1,27 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines
+
+import kotlin.test.*
+
+class AwaitCancellationTest : TestBase() {
+
+ @Test
+ fun testCancellation() = runTest(expected = { it is CancellationException }) {
+ expect(1)
+ coroutineScope {
+ val deferred: Deferred<Nothing> = async {
+ expect(2)
+ awaitCancellation()
+ }
+ yield()
+ expect(3)
+ require(deferred.isActive)
+ deferred.cancel()
+ finish(4)
+ deferred.await()
+ }
+ }
+}
diff --git a/kotlinx-coroutines-core/common/test/CancellableContinuationHandlersTest.kt b/kotlinx-coroutines-core/common/test/CancellableContinuationHandlersTest.kt
index 00f719e..3c11182 100644
--- a/kotlinx-coroutines-core/common/test/CancellableContinuationHandlersTest.kt
+++ b/kotlinx-coroutines-core/common/test/CancellableContinuationHandlersTest.kt
@@ -23,10 +23,23 @@
fun testDoubleSubscriptionAfterCompletion() = runTest {
suspendCancellableCoroutine<Unit> { c ->
c.resume(Unit)
- // Nothing happened
+ // First invokeOnCancellation is Ok
c.invokeOnCancellation { expectUnreached() }
- // Cannot validate after completion
- c.invokeOnCancellation { expectUnreached() }
+ // Second invokeOnCancellation is not allowed
+ assertFailsWith<IllegalStateException> { c.invokeOnCancellation { expectUnreached() } }
+ }
+ }
+
+ @Test
+ fun testDoubleSubscriptionAfterCompletionWithException() = runTest {
+ assertFailsWith<TestException> {
+ suspendCancellableCoroutine<Unit> { c ->
+ c.resumeWithException(TestException())
+ // First invokeOnCancellation is Ok
+ c.invokeOnCancellation { expectUnreached() }
+ // Second invokeOnCancellation is not allowed
+ assertFailsWith<IllegalStateException> { c.invokeOnCancellation { expectUnreached() } }
+ }
}
}
@@ -47,6 +60,59 @@
}
@Test
+ fun testSecondSubscriptionAfterCancellation() = runTest {
+ try {
+ suspendCancellableCoroutine<Unit> { c ->
+ // Set IOC first
+ c.invokeOnCancellation {
+ assertNull(it)
+ expect(2)
+ }
+ expect(1)
+ // then cancel (it gets called)
+ c.cancel()
+ // then try to install another one
+ assertFailsWith<IllegalStateException> { c.invokeOnCancellation { expectUnreached() } }
+ }
+ } catch (e: CancellationException) {
+ finish(3)
+ }
+ }
+
+ @Test
+ fun testSecondSubscriptionAfterResumeCancelAndDispatch() = runTest {
+ var cont: CancellableContinuation<Unit>? = null
+ val job = launch(start = CoroutineStart.UNDISPATCHED) {
+ // will be cancelled during dispatch
+ assertFailsWith<CancellationException> {
+ suspendCancellableCoroutine<Unit> { c ->
+ cont = c
+ // Set IOC first -- not called (completed)
+ c.invokeOnCancellation {
+ assertTrue(it is CancellationException)
+ expect(4)
+ }
+ expect(1)
+ }
+ }
+ expect(5)
+ }
+ expect(2)
+ // then resume it
+ cont!!.resume(Unit) // schedule cancelled continuation for dispatch
+ // then cancel the job during dispatch
+ job.cancel()
+ expect(3)
+ yield() // finish dispatching (will call IOC handler here!)
+ expect(6)
+ // then try to install another one after we've done dispatching it
+ assertFailsWith<IllegalStateException> {
+ cont!!.invokeOnCancellation { expectUnreached() }
+ }
+ finish(7)
+ }
+
+ @Test
fun testDoubleSubscriptionAfterCancellationWithCause() = runTest {
try {
suspendCancellableCoroutine<Unit> { c ->
diff --git a/kotlinx-coroutines-core/common/test/CancellableContinuationTest.kt b/kotlinx-coroutines-core/common/test/CancellableContinuationTest.kt
index 38fc9ff..f9f610c 100644
--- a/kotlinx-coroutines-core/common/test/CancellableContinuationTest.kt
+++ b/kotlinx-coroutines-core/common/test/CancellableContinuationTest.kt
@@ -116,4 +116,26 @@
continuation!!.resume(Unit) // Should not fail
finish(4)
}
+
+ @Test
+ fun testCompleteJobWhileSuspended() = runTest {
+ expect(1)
+ val completableJob = Job()
+ val coroutineBlock = suspend {
+ assertFailsWith<CancellationException> {
+ suspendCancellableCoroutine<Unit> { cont ->
+ expect(2)
+ assertSame(completableJob, cont.context[Job])
+ completableJob.complete()
+ }
+ expectUnreached()
+ }
+ expect(3)
+ }
+ coroutineBlock.startCoroutine(Continuation(completableJob) {
+ assertEquals(Unit, it.getOrNull())
+ expect(4)
+ })
+ finish(5)
+ }
}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/common/test/CancellableResumeTest.kt b/kotlinx-coroutines-core/common/test/CancellableResumeTest.kt
index 39176a9..fbfa082 100644
--- a/kotlinx-coroutines-core/common/test/CancellableResumeTest.kt
+++ b/kotlinx-coroutines-core/common/test/CancellableResumeTest.kt
@@ -1,5 +1,5 @@
/*
- * Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
*/
@file:Suppress("NAMED_ARGUMENTS_NOT_ALLOWED") // KT-21913
@@ -45,6 +45,33 @@
}
@Test
+ fun testResumeImmediateAfterCancelWithHandlerFailure() = runTest(
+ expected = { it is TestException },
+ unhandled = listOf(
+ { it is CompletionHandlerException && it.cause is TestException2 },
+ { it is CompletionHandlerException && it.cause is TestException3 }
+ )
+ ) {
+ expect(1)
+ suspendCancellableCoroutine<String> { cont ->
+ expect(2)
+ cont.invokeOnCancellation {
+ expect(3)
+ throw TestException2("FAIL") // invokeOnCancellation handler fails with exception
+ }
+ cont.cancel(TestException("FAIL"))
+ expect(4)
+ cont.resume("OK") { cause ->
+ expect(5)
+ assertTrue(cause is TestException)
+ throw TestException3("FAIL") // onCancellation block fails with exception
+ }
+ finish(6)
+ }
+ expectUnreached()
+ }
+
+ @Test
fun testResumeImmediateAfterIndirectCancel() = runTest(
expected = { it is CancellationException }
) {
@@ -64,6 +91,33 @@
}
@Test
+ fun testResumeImmediateAfterIndirectCancelWithHandlerFailure() = runTest(
+ expected = { it is CancellationException },
+ unhandled = listOf(
+ { it is CompletionHandlerException && it.cause is TestException2 },
+ { it is CompletionHandlerException && it.cause is TestException3 }
+ )
+ ) {
+ expect(1)
+ val ctx = coroutineContext
+ suspendCancellableCoroutine<String> { cont ->
+ expect(2)
+ cont.invokeOnCancellation {
+ expect(3)
+ throw TestException2("FAIL") // invokeOnCancellation handler fails with exception
+ }
+ ctx.cancel()
+ expect(4)
+ cont.resume("OK") { cause ->
+ expect(5)
+ throw TestException3("FAIL") // onCancellation block fails with exception
+ }
+ finish(6)
+ }
+ expectUnreached()
+ }
+
+ @Test
fun testResumeLaterNormally() = runTest {
expect(1)
lateinit var cc: CancellableContinuation<String>
@@ -110,6 +164,42 @@
}
@Test
+ fun testResumeLaterAfterCancelWithHandlerFailure() = runTest(
+ unhandled = listOf(
+ { it is CompletionHandlerException && it.cause is TestException2 },
+ { it is CompletionHandlerException && it.cause is TestException3 }
+ )
+ ) {
+ expect(1)
+ lateinit var cc: CancellableContinuation<String>
+ val job = launch(start = CoroutineStart.UNDISPATCHED) {
+ expect(2)
+ try {
+ suspendCancellableCoroutine<String> { cont ->
+ expect(3)
+ cont.invokeOnCancellation {
+ expect(5)
+ throw TestException2("FAIL") // invokeOnCancellation handler fails with exception
+ }
+ cc = cont
+ }
+ expectUnreached()
+ } catch (e: CancellationException) {
+ finish(9)
+ }
+ }
+ expect(4)
+ job.cancel(TestCancellationException())
+ expect(6)
+ cc.resume("OK") { cause ->
+ expect(7)
+ assertTrue(cause is TestCancellationException)
+ throw TestException3("FAIL") // onCancellation block fails with exception
+ }
+ expect(8)
+ }
+
+ @Test
fun testResumeCancelWhileDispatched() = runTest {
expect(1)
lateinit var cc: CancellableContinuation<String>
@@ -118,36 +208,86 @@
try {
suspendCancellableCoroutine<String> { cont ->
expect(3)
- // resumed first, then cancelled, so no invokeOnCancellation call
- cont.invokeOnCancellation { expectUnreached() }
+ // resumed first, dispatched, then cancelled, but still got invokeOnCancellation call
+ cont.invokeOnCancellation { cause ->
+ // Note: invokeOnCancellation is called before cc.resume(value) { ... } handler
+ expect(7)
+ assertTrue(cause is TestCancellationException)
+ }
cc = cont
}
expectUnreached()
} catch (e: CancellationException) {
- expect(8)
+ expect(9)
}
}
expect(4)
cc.resume("OK") { cause ->
- expect(7)
+ // Note: this handler is called after invokeOnCancellation handler
+ expect(8)
assertTrue(cause is TestCancellationException)
}
expect(5)
job.cancel(TestCancellationException()) // cancel while execution is dispatched
expect(6)
yield() // to coroutine -- throws cancellation exception
- finish(9)
+ finish(10)
}
+ @Test
+ fun testResumeCancelWhileDispatchedWithHandlerFailure() = runTest(
+ unhandled = listOf(
+ { it is CompletionHandlerException && it.cause is TestException2 },
+ { it is CompletionHandlerException && it.cause is TestException3 }
+ )
+ ) {
+ expect(1)
+ lateinit var cc: CancellableContinuation<String>
+ val job = launch(start = CoroutineStart.UNDISPATCHED) {
+ expect(2)
+ try {
+ suspendCancellableCoroutine<String> { cont ->
+ expect(3)
+ // resumed first, dispatched, then cancelled, but still got invokeOnCancellation call
+ cont.invokeOnCancellation { cause ->
+ // Note: invokeOnCancellation is called before cc.resume(value) { ... } handler
+ expect(7)
+ assertTrue(cause is TestCancellationException)
+ throw TestException2("FAIL") // invokeOnCancellation handler fails with exception
+ }
+ cc = cont
+ }
+ expectUnreached()
+ } catch (e: CancellationException) {
+ expect(9)
+ }
+ }
+ expect(4)
+ cc.resume("OK") { cause ->
+ // Note: this handler is called after invokeOnCancellation handler
+ expect(8)
+ assertTrue(cause is TestCancellationException)
+ throw TestException3("FAIL") // onCancellation block fails with exception
+ }
+ expect(5)
+ job.cancel(TestCancellationException()) // cancel while execution is dispatched
+ expect(6)
+ yield() // to coroutine -- throws cancellation exception
+ finish(10)
+ }
@Test
fun testResumeUnconfined() = runTest {
val outerScope = this
withContext(Dispatchers.Unconfined) {
val result = suspendCancellableCoroutine<String> {
- outerScope.launch { it.resume("OK", {}) }
+ outerScope.launch {
+ it.resume("OK") {
+ expectUnreached()
+ }
+ }
}
assertEquals("OK", result)
}
}
-}
\ No newline at end of file
+}
diff --git a/kotlinx-coroutines-core/common/test/DispatchedContinuationTest.kt b/kotlinx-coroutines-core/common/test/DispatchedContinuationTest.kt
new file mode 100644
index 0000000..b69eb22
--- /dev/null
+++ b/kotlinx-coroutines-core/common/test/DispatchedContinuationTest.kt
@@ -0,0 +1,78 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines
+
+import kotlin.coroutines.*
+import kotlin.test.*
+
+/**
+ * When using [suspendCoroutine] from the standard library the continuation must be dispatched atomically,
+ * without checking for cancellation at any point in time.
+ */
+class DispatchedContinuationTest : TestBase() {
+ private lateinit var cont: Continuation<String>
+
+ @Test
+ fun testCancelThenResume() = runTest {
+ expect(1)
+ launch(start = CoroutineStart.UNDISPATCHED) {
+ expect(2)
+ coroutineContext[Job]!!.cancel()
+ // a regular suspendCoroutine will still suspend despite the fact that coroutine was cancelled
+ val value = suspendCoroutine<String> {
+ expect(3)
+ cont = it
+ }
+ expect(6)
+ assertEquals("OK", value)
+ }
+ expect(4)
+ cont.resume("OK")
+ expect(5)
+ yield() // to the launched job
+ finish(7)
+ }
+
+ @Test
+ fun testCancelThenResumeUnconfined() = runTest {
+ expect(1)
+ launch(Dispatchers.Unconfined) {
+ expect(2)
+ coroutineContext[Job]!!.cancel()
+ // a regular suspendCoroutine will still suspend despite the fact that coroutine was cancelled
+ val value = suspendCoroutine<String> {
+ expect(3)
+ cont = it
+ }
+ expect(5)
+ assertEquals("OK", value)
+ }
+ expect(4)
+ cont.resume("OK") // immediately resumes -- because unconfined
+ finish(6)
+ }
+
+ @Test
+ fun testResumeThenCancel() = runTest {
+ expect(1)
+ val job = launch(start = CoroutineStart.UNDISPATCHED) {
+ expect(2)
+ val value = suspendCoroutine<String> {
+ expect(3)
+ cont = it
+ }
+ expect(7)
+ assertEquals("OK", value)
+ }
+ expect(4)
+ cont.resume("OK")
+ expect(5)
+ // now cancel the job, which the coroutine is waiting to be dispatched
+ job.cancel()
+ expect(6)
+ yield() // to the launched job
+ finish(8)
+ }
+}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/common/test/EnsureActiveTest.kt b/kotlinx-coroutines-core/common/test/JobExtensionsTest.kt
similarity index 81%
rename from kotlinx-coroutines-core/common/test/EnsureActiveTest.kt
rename to kotlinx-coroutines-core/common/test/JobExtensionsTest.kt
index 89e749c..b335926 100644
--- a/kotlinx-coroutines-core/common/test/EnsureActiveTest.kt
+++ b/kotlinx-coroutines-core/common/test/JobExtensionsTest.kt
@@ -4,9 +4,10 @@
package kotlinx.coroutines
+import kotlin.coroutines.*
import kotlin.test.*
-class EnsureActiveTest : TestBase() {
+class JobExtensionsTest : TestBase() {
private val job = Job()
private val scope = CoroutineScope(job + CoroutineExceptionHandler { _, _ -> })
@@ -81,4 +82,14 @@
assertTrue(exception is JobCancellationException)
assertTrue(exception.cause is TestException)
}
+
+ @Test
+ fun testJobExtension() = runTest {
+ assertSame(coroutineContext[Job]!!, coroutineContext.job)
+ assertSame(NonCancellable, NonCancellable.job)
+ assertSame(job, job.job)
+ assertFailsWith<IllegalStateException> { EmptyCoroutineContext.job }
+ assertFailsWith<IllegalStateException> { Dispatchers.Default.job }
+ assertFailsWith<IllegalStateException> { (Dispatchers.Default + CoroutineName("")).job }
+ }
}
diff --git a/kotlinx-coroutines-core/common/test/channels/BasicOperationsTest.kt b/kotlinx-coroutines-core/common/test/channels/BasicOperationsTest.kt
index a6ddd81..91d941b 100644
--- a/kotlinx-coroutines-core/common/test/channels/BasicOperationsTest.kt
+++ b/kotlinx-coroutines-core/common/test/channels/BasicOperationsTest.kt
@@ -42,7 +42,7 @@
@Test
fun testInvokeOnClose() = TestChannelKind.values().forEach { kind ->
reset()
- val channel = kind.create()
+ val channel = kind.create<Int>()
channel.invokeOnClose {
if (it is AssertionError) {
expect(3)
@@ -59,7 +59,7 @@
fun testInvokeOnClosed() = TestChannelKind.values().forEach { kind ->
reset()
expect(1)
- val channel = kind.create()
+ val channel = kind.create<Int>()
channel.close()
channel.invokeOnClose { expect(2) }
assertFailsWith<IllegalStateException> { channel.invokeOnClose { expect(3) } }
@@ -69,7 +69,7 @@
@Test
fun testMultipleInvokeOnClose() = TestChannelKind.values().forEach { kind ->
reset()
- val channel = kind.create()
+ val channel = kind.create<Int>()
channel.invokeOnClose { expect(3) }
expect(1)
assertFailsWith<IllegalStateException> { channel.invokeOnClose { expect(4) } }
@@ -81,7 +81,7 @@
@Test
fun testIterator() = runTest {
TestChannelKind.values().forEach { kind ->
- val channel = kind.create()
+ val channel = kind.create<Int>()
val iterator = channel.iterator()
assertFailsWith<IllegalStateException> { iterator.next() }
channel.close()
@@ -91,7 +91,7 @@
}
private suspend fun testReceiveOrNull(kind: TestChannelKind) = coroutineScope {
- val channel = kind.create()
+ val channel = kind.create<Int>()
val d = async(NonCancellable) {
channel.receive()
}
@@ -108,7 +108,7 @@
}
private suspend fun testReceiveOrNullException(kind: TestChannelKind) = coroutineScope {
- val channel = kind.create()
+ val channel = kind.create<Int>()
val d = async(NonCancellable) {
channel.receive()
}
@@ -132,7 +132,7 @@
@Suppress("ReplaceAssertBooleanWithAssertEquality")
private suspend fun testReceiveOrClosed(kind: TestChannelKind) = coroutineScope {
reset()
- val channel = kind.create()
+ val channel = kind.create<Int>()
launch {
expect(2)
channel.send(1)
@@ -159,7 +159,7 @@
}
private suspend fun testOffer(kind: TestChannelKind) = coroutineScope {
- val channel = kind.create()
+ val channel = kind.create<Int>()
val d = async { channel.send(42) }
yield()
channel.close()
@@ -184,7 +184,7 @@
private suspend fun testSendAfterClose(kind: TestChannelKind) {
assertFailsWith<ClosedSendChannelException> {
coroutineScope {
- val channel = kind.create()
+ val channel = kind.create<Int>()
channel.close()
launch {
@@ -195,7 +195,7 @@
}
private suspend fun testSendReceive(kind: TestChannelKind, iterations: Int) = coroutineScope {
- val channel = kind.create()
+ val channel = kind.create<Int>()
launch {
repeat(iterations) { channel.send(it) }
channel.close()
diff --git a/kotlinx-coroutines-core/common/test/channels/BroadcastTest.kt b/kotlinx-coroutines-core/common/test/channels/BroadcastTest.kt
index bb3142e..ab1a85d 100644
--- a/kotlinx-coroutines-core/common/test/channels/BroadcastTest.kt
+++ b/kotlinx-coroutines-core/common/test/channels/BroadcastTest.kt
@@ -63,7 +63,7 @@
val a = produce {
expect(3)
send("MSG")
- expect(5)
+ expectUnreached() // is not executed, because send is cancelled
}
expect(2)
yield() // to produce
@@ -72,7 +72,7 @@
expect(4)
yield() // to abort produce
assertTrue(a.isClosedForReceive) // the source channel was consumed
- finish(6)
+ finish(5)
}
@Test
diff --git a/kotlinx-coroutines-core/common/test/channels/ChannelBufferOverflowTest.kt b/kotlinx-coroutines-core/common/test/channels/ChannelBufferOverflowTest.kt
new file mode 100644
index 0000000..41f6047
--- /dev/null
+++ b/kotlinx-coroutines-core/common/test/channels/ChannelBufferOverflowTest.kt
@@ -0,0 +1,40 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.channels
+
+import kotlinx.coroutines.*
+import kotlin.test.*
+
+class ChannelBufferOverflowTest : TestBase() {
+ @Test
+ fun testDropLatest() = runTest {
+ val c = Channel<Int>(2, BufferOverflow.DROP_LATEST)
+ assertTrue(c.offer(1))
+ assertTrue(c.offer(2))
+ assertTrue(c.offer(3)) // overflows, dropped
+ c.send(4) // overflows dropped
+ assertEquals(1, c.receive())
+ assertTrue(c.offer(5))
+ assertTrue(c.offer(6)) // overflows, dropped
+ assertEquals(2, c.receive())
+ assertEquals(5, c.receive())
+ assertEquals(null, c.poll())
+ }
+
+ @Test
+ fun testDropOldest() = runTest {
+ val c = Channel<Int>(2, BufferOverflow.DROP_OLDEST)
+ assertTrue(c.offer(1))
+ assertTrue(c.offer(2))
+ assertTrue(c.offer(3)) // overflows, keeps 2, 3
+ c.send(4) // overflows, keeps 3, 4
+ assertEquals(3, c.receive())
+ assertTrue(c.offer(5))
+ assertTrue(c.offer(6)) // overflows, keeps 5, 6
+ assertEquals(5, c.receive())
+ assertEquals(6, c.receive())
+ assertEquals(null, c.poll())
+ }
+}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/common/test/channels/ChannelFactoryTest.kt b/kotlinx-coroutines-core/common/test/channels/ChannelFactoryTest.kt
index 72ba315..413c91f 100644
--- a/kotlinx-coroutines-core/common/test/channels/ChannelFactoryTest.kt
+++ b/kotlinx-coroutines-core/common/test/channels/ChannelFactoryTest.kt
@@ -1,5 +1,5 @@
/*
- * Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
*/
package kotlinx.coroutines.channels
@@ -9,7 +9,6 @@
class ChannelFactoryTest : TestBase() {
-
@Test
fun testRendezvousChannel() {
assertTrue(Channel<Int>() is RendezvousChannel)
@@ -19,21 +18,31 @@
@Test
fun testLinkedListChannel() {
assertTrue(Channel<Int>(Channel.UNLIMITED) is LinkedListChannel)
+ assertTrue(Channel<Int>(Channel.UNLIMITED, BufferOverflow.DROP_OLDEST) is LinkedListChannel)
+ assertTrue(Channel<Int>(Channel.UNLIMITED, BufferOverflow.DROP_LATEST) is LinkedListChannel)
}
@Test
fun testConflatedChannel() {
assertTrue(Channel<Int>(Channel.CONFLATED) is ConflatedChannel)
+ assertTrue(Channel<Int>(1, BufferOverflow.DROP_OLDEST) is ConflatedChannel)
}
@Test
fun testArrayChannel() {
assertTrue(Channel<Int>(1) is ArrayChannel)
+ assertTrue(Channel<Int>(1, BufferOverflow.DROP_LATEST) is ArrayChannel)
assertTrue(Channel<Int>(10) is ArrayChannel)
}
@Test
- fun testInvalidCapacityNotSupported() = runTest({ it is IllegalArgumentException }) {
- Channel<Int>(-3)
+ fun testInvalidCapacityNotSupported() {
+ assertFailsWith<IllegalArgumentException> { Channel<Int>(-3) }
+ }
+
+ @Test
+ fun testUnsupportedBufferOverflow() {
+ assertFailsWith<IllegalArgumentException> { Channel<Int>(Channel.CONFLATED, BufferOverflow.DROP_OLDEST) }
+ assertFailsWith<IllegalArgumentException> { Channel<Int>(Channel.CONFLATED, BufferOverflow.DROP_LATEST) }
}
}
diff --git a/kotlinx-coroutines-core/common/test/channels/ChannelUndeliveredElementFailureTest.kt b/kotlinx-coroutines-core/common/test/channels/ChannelUndeliveredElementFailureTest.kt
new file mode 100644
index 0000000..d2ef3d2
--- /dev/null
+++ b/kotlinx-coroutines-core/common/test/channels/ChannelUndeliveredElementFailureTest.kt
@@ -0,0 +1,143 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.channels
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.internal.*
+import kotlinx.coroutines.selects.*
+import kotlin.test.*
+
+/**
+ * Tests for failures inside `onUndeliveredElement` handler in [Channel].
+ */
+class ChannelUndeliveredElementFailureTest : TestBase() {
+ private val item = "LOST"
+ private val onCancelFail: (String) -> Unit = { throw TestException(it) }
+ private val shouldBeUnhandled: List<(Throwable) -> Boolean> = listOf({ it.isElementCancelException() })
+
+ private fun Throwable.isElementCancelException() =
+ this is UndeliveredElementException && cause is TestException && cause!!.message == item
+
+ @Test
+ fun testSendCancelledFail() = runTest(unhandled = shouldBeUnhandled) {
+ val channel = Channel(onUndeliveredElement = onCancelFail)
+ val job = launch(start = CoroutineStart.UNDISPATCHED) {
+ channel.send(item)
+ expectUnreached()
+ }
+ job.cancel()
+ }
+
+ @Test
+ fun testSendSelectCancelledFail() = runTest(unhandled = shouldBeUnhandled) {
+ val channel = Channel(onUndeliveredElement = onCancelFail)
+ val job = launch(start = CoroutineStart.UNDISPATCHED) {
+ select {
+ channel.onSend(item) {
+ expectUnreached()
+ }
+ }
+ }
+ job.cancel()
+ }
+
+ @Test
+ fun testReceiveCancelledFail() = runTest(unhandled = shouldBeUnhandled) {
+ val channel = Channel(onUndeliveredElement = onCancelFail)
+ val job = launch(start = CoroutineStart.UNDISPATCHED) {
+ channel.receive()
+ expectUnreached() // will be cancelled before it dispatches
+ }
+ channel.send(item)
+ job.cancel()
+ }
+
+ @Test
+ fun testReceiveSelectCancelledFail() = runTest(unhandled = shouldBeUnhandled) {
+ val channel = Channel(onUndeliveredElement = onCancelFail)
+ val job = launch(start = CoroutineStart.UNDISPATCHED) {
+ select<Unit> {
+ channel.onReceive {
+ expectUnreached()
+ }
+ }
+ expectUnreached() // will be cancelled before it dispatches
+ }
+ channel.send(item)
+ job.cancel()
+ }
+
+ @Test
+ fun testReceiveOrNullCancelledFail() = runTest(unhandled = shouldBeUnhandled) {
+ val channel = Channel(onUndeliveredElement = onCancelFail)
+ val job = launch(start = CoroutineStart.UNDISPATCHED) {
+ channel.receiveOrNull()
+ expectUnreached() // will be cancelled before it dispatches
+ }
+ channel.send(item)
+ job.cancel()
+ }
+
+ @Test
+ fun testReceiveOrNullSelectCancelledFail() = runTest(unhandled = shouldBeUnhandled) {
+ val channel = Channel(onUndeliveredElement = onCancelFail)
+ val job = launch(start = CoroutineStart.UNDISPATCHED) {
+ select<Unit> {
+ channel.onReceiveOrNull {
+ expectUnreached()
+ }
+ }
+ expectUnreached() // will be cancelled before it dispatches
+ }
+ channel.send(item)
+ job.cancel()
+ }
+
+ @Test
+ fun testReceiveOrClosedCancelledFail() = runTest(unhandled = shouldBeUnhandled) {
+ val channel = Channel(onUndeliveredElement = onCancelFail)
+ val job = launch(start = CoroutineStart.UNDISPATCHED) {
+ channel.receiveOrClosed()
+ expectUnreached() // will be cancelled before it dispatches
+ }
+ channel.send(item)
+ job.cancel()
+ }
+
+ @Test
+ fun testReceiveOrClosedSelectCancelledFail() = runTest(unhandled = shouldBeUnhandled) {
+ val channel = Channel(onUndeliveredElement = onCancelFail)
+ val job = launch(start = CoroutineStart.UNDISPATCHED) {
+ select<Unit> {
+ channel.onReceiveOrClosed {
+ expectUnreached()
+ }
+ }
+ expectUnreached() // will be cancelled before it dispatches
+ }
+ channel.send(item)
+ job.cancel()
+ }
+
+ @Test
+ fun testHasNextCancelledFail() = runTest(unhandled = shouldBeUnhandled) {
+ val channel = Channel(onUndeliveredElement = onCancelFail)
+ val job = launch(start = CoroutineStart.UNDISPATCHED) {
+ channel.iterator().hasNext()
+ expectUnreached() // will be cancelled before it dispatches
+ }
+ channel.send(item)
+ job.cancel()
+ }
+
+ @Test
+ fun testChannelCancelledFail() = runTest(expected = { it.isElementCancelException()}) {
+ val channel = Channel(1, onUndeliveredElement = onCancelFail)
+ channel.send(item)
+ channel.cancel()
+ expectUnreached()
+ }
+
+}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/common/test/channels/ChannelUndeliveredElementTest.kt b/kotlinx-coroutines-core/common/test/channels/ChannelUndeliveredElementTest.kt
new file mode 100644
index 0000000..0391e00
--- /dev/null
+++ b/kotlinx-coroutines-core/common/test/channels/ChannelUndeliveredElementTest.kt
@@ -0,0 +1,104 @@
+package kotlinx.coroutines.channels
+
+import kotlinx.atomicfu.*
+import kotlinx.coroutines.*
+import kotlin.test.*
+
+class ChannelUndeliveredElementTest : TestBase() {
+ @Test
+ fun testSendSuccessfully() = runAllKindsTest { kind ->
+ val channel = kind.create<Resource> { it.cancel() }
+ val res = Resource("OK")
+ launch {
+ channel.send(res)
+ }
+ val ok = channel.receive()
+ assertEquals("OK", ok.value)
+ assertFalse(res.isCancelled) // was not cancelled
+ channel.close()
+ assertFalse(res.isCancelled) // still was not cancelled
+ }
+
+ @Test
+ fun testRendezvousSendCancelled() = runTest {
+ val channel = Channel<Resource> { it.cancel() }
+ val res = Resource("OK")
+ val sender = launch(start = CoroutineStart.UNDISPATCHED) {
+ assertFailsWith<CancellationException> {
+ channel.send(res) // suspends & get cancelled
+ }
+ }
+ sender.cancelAndJoin()
+ assertTrue(res.isCancelled)
+ }
+
+ @Test
+ fun testBufferedSendCancelled() = runTest {
+ val channel = Channel<Resource>(1) { it.cancel() }
+ val resA = Resource("A")
+ val resB = Resource("B")
+ val sender = launch(start = CoroutineStart.UNDISPATCHED) {
+ channel.send(resA) // goes to buffer
+ assertFailsWith<CancellationException> {
+ channel.send(resB) // suspends & get cancelled
+ }
+ }
+ sender.cancelAndJoin()
+ assertFalse(resA.isCancelled) // it is in buffer, not cancelled
+ assertTrue(resB.isCancelled) // send was cancelled
+ channel.cancel() // now cancel the channel
+ assertTrue(resA.isCancelled) // now cancelled in buffer
+ }
+
+ @Test
+ fun testConflatedResourceCancelled() = runTest {
+ val channel = Channel<Resource>(Channel.CONFLATED) { it.cancel() }
+ val resA = Resource("A")
+ val resB = Resource("B")
+ channel.send(resA)
+ assertFalse(resA.isCancelled)
+ assertFalse(resB.isCancelled)
+ channel.send(resB)
+ assertTrue(resA.isCancelled) // it was conflated (lost) and thus cancelled
+ assertFalse(resB.isCancelled)
+ channel.close()
+ assertFalse(resB.isCancelled) // not cancelled yet, can be still read by receiver
+ channel.cancel()
+ assertTrue(resB.isCancelled) // now it is cancelled
+ }
+
+ @Test
+ fun testSendToClosedChannel() = runAllKindsTest { kind ->
+ val channel = kind.create<Resource> { it.cancel() }
+ channel.close() // immediately close channel
+ val res = Resource("OK")
+ assertFailsWith<ClosedSendChannelException> {
+ channel.send(res) // send fails to closed channel, resource was not delivered
+ }
+ assertTrue(res.isCancelled)
+ }
+
+ private fun runAllKindsTest(test: suspend CoroutineScope.(TestChannelKind) -> Unit) {
+ for (kind in TestChannelKind.values()) {
+ if (kind.viaBroadcast) continue // does not support onUndeliveredElement
+ try {
+ runTest {
+ test(kind)
+ }
+ } catch(e: Throwable) {
+ error("$kind: $e", e)
+ }
+ }
+ }
+
+ private class Resource(val value: String) {
+ private val _cancelled = atomic(false)
+
+ val isCancelled: Boolean
+ get() = _cancelled.value
+
+ fun cancel() {
+ check(!_cancelled.getAndSet(true)) { "Already cancelled" }
+ }
+ }
+}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/common/test/channels/ChannelsTest.kt b/kotlinx-coroutines-core/common/test/channels/ChannelsTest.kt
index ba786d5..fb704c5 100644
--- a/kotlinx-coroutines-core/common/test/channels/ChannelsTest.kt
+++ b/kotlinx-coroutines-core/common/test/channels/ChannelsTest.kt
@@ -51,123 +51,6 @@
}
@Test
- fun testAssociate() = runTest {
- assertEquals(testList.associate { it * 2 to it * 3 },
- testList.asReceiveChannel().associate { it * 2 to it * 3 }.toMap())
- }
-
- @Test
- fun testAssociateBy() = runTest {
- assertEquals(testList.associateBy { it % 2 }, testList.asReceiveChannel().associateBy { it % 2 })
- }
-
- @Test
- fun testAssociateBy2() = runTest {
- assertEquals(testList.associateBy({ it * 2}, { it * 3 }),
- testList.asReceiveChannel().associateBy({ it * 2}, { it * 3 }).toMap())
- }
-
- @Test
- fun testDistinct() = runTest {
- assertEquals(testList.map { it % 2 }.distinct(), testList.asReceiveChannel().map { it % 2 }.distinct().toList())
- }
-
- @Test
- fun testDistinctBy() = runTest {
- assertEquals(testList.distinctBy { it % 2 }.toList(), testList.asReceiveChannel().distinctBy { it % 2 }.toList())
- }
-
- @Test
- fun testToCollection() = runTest {
- val target = mutableListOf<Int>()
- testList.asReceiveChannel().toCollection(target)
- assertEquals(testList, target)
- }
-
- @Test
- fun testDrop() = runTest {
- for (i in 0..testList.size) {
- assertEquals(testList.drop(i), testList.asReceiveChannel().drop(i).toList(), "Drop $i")
- }
- }
-
- @Test
- fun testElementAtOrElse() = runTest {
- assertEquals(testList.elementAtOrElse(2) { 42 }, testList.asReceiveChannel().elementAtOrElse(2) { 42 })
- assertEquals(testList.elementAtOrElse(9) { 42 }, testList.asReceiveChannel().elementAtOrElse(9) { 42 })
- }
-
- @Test
- fun testFirst() = runTest {
- assertEquals(testList.first(), testList.asReceiveChannel().first())
- for (i in testList) {
- assertEquals(testList.first { it == i }, testList.asReceiveChannel().first { it == i })
- }
- try {
- testList.asReceiveChannel().first { it == 9 }
- fail()
- } catch (nse: NoSuchElementException) {
- }
- }
-
- @Test
- fun testFirstOrNull() = runTest {
- assertEquals(testList.firstOrNull(), testList.asReceiveChannel().firstOrNull())
- assertEquals(testList.firstOrNull { it == 2 }, testList.asReceiveChannel().firstOrNull { it == 2 })
- assertEquals(testList.firstOrNull { it == 9 }, testList.asReceiveChannel().firstOrNull { it == 9 })
- }
-
- @Test
- fun testFlatMap() = runTest {
- assertEquals(testList.flatMap { (0..it).toList() }, testList.asReceiveChannel().flatMap { (0..it).asReceiveChannel() }.toList())
-
- }
-
- @Test
- fun testFold() = runTest {
- assertEquals(testList.fold(mutableListOf(42)) { acc, e -> acc.apply { add(e) } },
- testList.asReceiveChannel().fold(mutableListOf(42)) { acc, e -> acc.apply { add(e) } }.toList())
- }
-
- @Test
- fun testFoldIndexed() = runTest {
- assertEquals(testList.foldIndexed(mutableListOf(42)) { index, acc, e -> acc.apply { add(index + e) } },
- testList.asReceiveChannel().foldIndexed(mutableListOf(42)) { index, acc, e -> acc.apply { add(index + e) } }.toList())
- }
-
- @Test
- fun testGroupBy() = runTest {
- assertEquals(testList.groupBy { it % 2 }, testList.asReceiveChannel().groupBy { it % 2 })
- }
-
- @Test
- fun testGroupBy2() = runTest {
- assertEquals(testList.groupBy({ -it }, { it + 100 }), testList.asReceiveChannel().groupBy({ -it }, { it + 100 }).toMap())
-
- }
-
- @Test
- fun testMap() = runTest {
- assertEquals(testList.map { it + 10 }, testList.asReceiveChannel().map { it + 10 }.toList())
-
- }
-
- @Test
- fun testMapToCollection() = runTest {
- val c = mutableListOf<Int>()
- testList.asReceiveChannel().mapTo(c) { it + 10 }
- assertEquals(testList.map { it + 10 }, c)
- }
-
- @Test
- fun testMapToSendChannel() = runTest {
- val c = produce<Int> {
- testList.asReceiveChannel().mapTo(channel) { it + 10 }
- }
- assertEquals(testList.map { it + 10 }, c.toList())
- }
-
- @Test
fun testEmptyList() = runTest {
assertTrue(emptyList<Nothing>().asReceiveChannel().toList().isEmpty())
}
@@ -178,413 +61,6 @@
}
- @Test
- fun testEmptySet() = runTest {
- assertTrue(emptyList<Nothing>().asReceiveChannel().toSet().isEmpty())
-
- }
-
- @Test
- fun testToSet() = runTest {
- assertEquals(testList.toSet(), testList.asReceiveChannel().toSet())
- }
-
- @Test
- fun testToMutableSet() = runTest {
- assertEquals(testList.toMutableSet(), testList.asReceiveChannel().toMutableSet())
- }
-
- @Test
- fun testEmptySequence() = runTest {
- val channel = Channel<Nothing>()
- channel.close()
-
- assertEquals(emptyList<Nothing>().asReceiveChannel().count(), 0)
- }
-
- @Test
- fun testEmptyMap() = runTest {
- val channel = Channel<Pair<Nothing, Nothing>>()
- channel.close()
-
- assertTrue(channel.toMap().isEmpty())
- }
-
- @Test
- fun testToMap() = runTest {
- val values = testList.map { it to it.toString() }
- assertEquals(values.toMap(), values.asReceiveChannel().toMap())
- }
-
- @Test
- fun testReduce() = runTest {
- assertEquals(testList.reduce { acc, e -> acc * e },
- testList.asReceiveChannel().reduce { acc, e -> acc * e })
- }
-
- @Test
- fun testReduceIndexed() = runTest {
- assertEquals(testList.reduceIndexed { index, acc, e -> index + acc * e },
- testList.asReceiveChannel().reduceIndexed { index, acc, e -> index + acc * e })
- }
-
- @Test
- fun testTake() = runTest {
- for (i in 0..testList.size) {
- assertEquals(testList.take(i), testList.asReceiveChannel().take(i).toList())
- }
- }
-
- @Test
- fun testPartition() = runTest {
- assertEquals(testList.partition { it % 2 == 0 }, testList.asReceiveChannel().partition { it % 2 == 0 })
- }
-
- @Test
- fun testZip() = runTest {
- val other = listOf("a", "b")
- assertEquals(testList.zip(other), testList.asReceiveChannel().zip(other.asReceiveChannel()).toList())
- }
-
- @Test
- fun testElementAt() = runTest {
- testList.indices.forEach { i ->
- assertEquals(testList[i], testList.asReceiveChannel().elementAt(i))
- }
- }
-
- @Test
- fun testElementAtOrNull() = runTest {
- testList.indices.forEach { i ->
- assertEquals(testList[i], testList.asReceiveChannel().elementAtOrNull(i))
- }
- assertNull(testList.asReceiveChannel().elementAtOrNull(-1))
- assertNull(testList.asReceiveChannel().elementAtOrNull(testList.size))
- }
-
- @Test
- fun testFind() = runTest {
- repeat(3) { mod ->
- assertEquals(testList.find { it % 2 == mod },
- testList.asReceiveChannel().find { it % 2 == mod })
- }
- }
-
- @Test
- fun testFindLast() = runTest {
- repeat(3) { mod ->
- assertEquals(testList.findLast { it % 2 == mod }, testList.asReceiveChannel().findLast { it % 2 == mod })
- }
- }
-
- @Test
- fun testIndexOf() = runTest {
- repeat(testList.size + 1) { i ->
- assertEquals(testList.indexOf(i), testList.asReceiveChannel().indexOf(i))
- }
- }
-
- @Test
- fun testLastIndexOf() = runTest {
- repeat(testList.size + 1) { i ->
- assertEquals(testList.lastIndexOf(i), testList.asReceiveChannel().lastIndexOf(i))
- }
- }
-
- @Test
- fun testIndexOfFirst() = runTest {
- repeat(3) { mod ->
- assertEquals(testList.indexOfFirst { it % 2 == mod },
- testList.asReceiveChannel().indexOfFirst { it % 2 == mod })
- }
- }
-
- @Test
- fun testIndexOfLast() = runTest {
- repeat(3) { mod ->
- assertEquals(testList.indexOfLast { it % 2 != mod },
- testList.asReceiveChannel().indexOfLast { it % 2 != mod })
- }
- }
-
- @Test
- fun testLastOrNull() = runTest {
- assertEquals(testList.lastOrNull(), testList.asReceiveChannel().lastOrNull())
- assertNull(emptyList<Int>().asReceiveChannel().lastOrNull())
- }
-
- @Test
- fun testSingleOrNull() = runTest {
- assertEquals(1, listOf(1).asReceiveChannel().singleOrNull())
- assertNull(listOf(1, 2).asReceiveChannel().singleOrNull())
- assertNull(emptyList<Int>().asReceiveChannel().singleOrNull())
- repeat(testList.size + 1) { i ->
- assertEquals(testList.singleOrNull { it == i },
- testList.asReceiveChannel().singleOrNull { it == i })
- }
- repeat(3) { mod ->
- assertEquals(testList.singleOrNull { it % 2 == mod },
- testList.asReceiveChannel().singleOrNull { it % 2 == mod })
- }
- }
-
- @Test
- fun testDropWhile() = runTest {
- repeat(3) { mod ->
- assertEquals(testList.dropWhile { it % 2 == mod },
- testList.asReceiveChannel().dropWhile { it % 2 == mod }.toList())
- }
- }
-
- @Test
- fun testFilter() = runTest {
- repeat(3) { mod ->
- assertEquals(testList.filter { it % 2 == mod },
- testList.asReceiveChannel().filter { it % 2 == mod }.toList())
- }
- }
-
- @Test
- fun testFilterToCollection() = runTest {
- repeat(3) { mod ->
- val c = mutableListOf<Int>()
- testList.asReceiveChannel().filterTo(c) { it % 2 == mod }
- assertEquals(testList.filter { it % 2 == mod }, c)
- }
- }
-
- @Test
- fun testFilterToSendChannel() = runTest {
- repeat(3) { mod ->
- val c = produce<Int> {
- testList.asReceiveChannel().filterTo(channel) { it % 2 == mod }
- }
- assertEquals(testList.filter { it % 2 == mod }, c.toList())
- }
- }
-
- @Test
- fun testFilterNot() = runTest {
- repeat(3) { mod ->
- assertEquals(testList.filterNot { it % 2 == mod },
- testList.asReceiveChannel().filterNot { it % 2 == mod }.toList())
- }
- }
-
- @Test
- fun testFilterNotToCollection() = runTest {
- repeat(3) { mod ->
- val c = mutableListOf<Int>()
- testList.asReceiveChannel().filterNotTo(c) { it % 2 == mod }
- assertEquals(testList.filterNot { it % 2 == mod }, c)
- }
- }
-
- @Test
- fun testFilterNotToSendChannel() = runTest {
- repeat(3) { mod ->
- val c = produce<Int> {
- testList.asReceiveChannel().filterNotTo(channel) { it % 2 == mod }
- }
- assertEquals(testList.filterNot { it % 2 == mod }, c.toList())
- }
- }
-
- @Test
- fun testFilterNotNull() = runTest {
- repeat(3) { mod ->
- assertEquals(
- testList.mapNotNull { it.takeIf { it % 2 == mod } },
- testList.asReceiveChannel().map { it.takeIf { it % 2 == mod } }.filterNotNull().toList())
- }
- }
-
- @Test
- fun testFilterNotNullToCollection() = runTest {
- repeat(3) { mod ->
- val c = mutableListOf<Int>()
- testList.asReceiveChannel().map { it.takeIf { it % 2 == mod } }.filterNotNullTo(c)
- assertEquals(testList.mapNotNull { it.takeIf { it % 2 == mod } }, c)
- }
- }
-
- @Test
- fun testFilterNotNullToSendChannel() = runTest {
- repeat(3) { mod ->
- val c = produce<Int> {
- testList.asReceiveChannel().map { it.takeIf { it % 2 == mod } }.filterNotNullTo(channel)
- }
- assertEquals(testList.mapNotNull { it.takeIf { it % 2 == mod } }, c.toList())
- }
- }
-
- @Test
- fun testFilterIndexed() = runTest {
- repeat(3) { mod ->
- assertEquals(testList.filterIndexed { index, _ -> index % 2 == mod },
- testList.asReceiveChannel().filterIndexed { index, _ -> index % 2 == mod }.toList())
- }
- }
-
- @Test
- fun testFilterIndexedToCollection() = runTest {
- repeat(3) { mod ->
- val c = mutableListOf<Int>()
- testList.asReceiveChannel().filterIndexedTo(c) { index, _ -> index % 2 == mod }
- assertEquals(testList.filterIndexed { index, _ -> index % 2 == mod }, c)
- }
- }
-
- @Test
- fun testFilterIndexedToChannel() = runTest {
- repeat(3) { mod ->
- val c = produce<Int> {
- testList.asReceiveChannel().filterIndexedTo(channel) { index, _ -> index % 2 == mod }
- }
- assertEquals(testList.filterIndexed { index, _ -> index % 2 == mod }, c.toList())
- }
- }
-
- @Test
- fun testTakeWhile() = runTest {
- repeat(3) { mod ->
- assertEquals(testList.takeWhile { it % 2 != mod },
- testList.asReceiveChannel().takeWhile { it % 2 != mod }.toList())
- }
- }
-
- @Test
- fun testToChannel() = runTest {
- val c = produce<Int> {
- testList.asReceiveChannel().toChannel(channel)
- }
- assertEquals(testList, c.toList())
- }
-
- @Test
- fun testMapIndexed() = runTest {
- assertEquals(testList.mapIndexed { index, i -> index + i },
- testList.asReceiveChannel().mapIndexed { index, i -> index + i }.toList())
- }
-
- @Test
- fun testMapIndexedToCollection() = runTest {
- val c = mutableListOf<Int>()
- testList.asReceiveChannel().mapIndexedTo(c) { index, i -> index + i }
- assertEquals(testList.mapIndexed { index, i -> index + i }, c)
- }
-
- @Test
- fun testMapIndexedToSendChannel() = runTest {
- val c = produce<Int> {
- testList.asReceiveChannel().mapIndexedTo(channel) { index, i -> index + i }
- }
- assertEquals(testList.mapIndexed { index, i -> index + i }, c.toList())
- }
-
- @Test
- fun testMapNotNull() = runTest {
- repeat(3) { mod ->
- assertEquals(testList.mapNotNull { i -> i.takeIf { i % 2 == mod } },
- testList.asReceiveChannel().mapNotNull { i -> i.takeIf { i % 2 == mod } }.toList())
- }
- }
-
- @Test
- fun testMapNotNullToCollection() = runTest {
- repeat(3) { mod ->
- val c = mutableListOf<Int>()
- testList.asReceiveChannel().mapNotNullTo(c) { i -> i.takeIf { i % 2 == mod } }
- assertEquals(testList.mapNotNull { i -> i.takeIf { i % 2 == mod } }, c)
- }
- }
-
- @Test
- fun testMapNotNullToSendChannel() = runTest {
- repeat(3) { mod ->
- val c = produce<Int> {
- testList.asReceiveChannel().mapNotNullTo(channel) { i -> i.takeIf { i % 2 == mod } }
- }
- assertEquals(testList.mapNotNull { i -> i.takeIf { i % 2 == mod } }, c.toList())
- }
- }
-
- @Test
- fun testMapIndexedNotNull() = runTest {
- repeat(3) { mod ->
- assertEquals(testList.mapIndexedNotNull { index, i -> index.takeIf { i % 2 == mod } },
- testList.asReceiveChannel().mapIndexedNotNull { index, i -> index.takeIf { i % 2 == mod } }.toList())
- }
- }
-
- @Test
- fun testMapIndexedNotNullToCollection() = runTest {
- repeat(3) { mod ->
- val c = mutableListOf<Int>()
- testList.asReceiveChannel().mapIndexedNotNullTo(c) { index, i -> index.takeIf { i % 2 == mod } }
- assertEquals(testList.mapIndexedNotNull { index, i -> index.takeIf { i % 2 == mod } }, c)
- }
- }
-
- @Test
- fun testMapIndexedNotNullToSendChannel() = runTest {
- repeat(3) { mod ->
- val c = produce<Int> {
- testList.asReceiveChannel().mapIndexedNotNullTo(channel) { index, i -> index.takeIf { i % 2 == mod } }
- }
- assertEquals(testList.mapIndexedNotNull { index, i -> index.takeIf { i % 2 == mod } }, c.toList())
- }
- }
-
- @Test
- fun testWithIndex() = runTest {
- assertEquals(testList.withIndex().toList(), testList.asReceiveChannel().withIndex().toList())
- }
-
- @Test
- fun testMaxBy() = runTest {
- assertEquals(testList.maxBy { 10 - abs(it - 2) },
- testList.asReceiveChannel().maxBy { 10 - abs(it - 2) })
- }
-
- @Test
- fun testMaxWith() = runTest {
- val cmp = compareBy<Int> { 10 - abs(it - 2) }
- assertEquals(testList.maxWith(cmp),
- testList.asReceiveChannel().maxWith(cmp))
- }
-
- @Test
- fun testMinBy() = runTest {
- assertEquals(testList.minBy { abs(it - 2) },
- testList.asReceiveChannel().minBy { abs(it - 2) })
- }
-
- @Test
- fun testMinWith() = runTest {
- val cmp = compareBy<Int> { abs(it - 2) }
- assertEquals(testList.minWith(cmp),
- testList.asReceiveChannel().minWith(cmp))
- }
-
- @Test
- fun testSumBy() = runTest {
- assertEquals(testList.sumBy { it * 3 },
- testList.asReceiveChannel().sumBy { it * 3 })
- }
-
- @Test
- fun testSumByDouble() = runTest {
- val expected = testList.sumByDouble { it * 3.0 }
- val actual = testList.asReceiveChannel().sumByDouble { it * 3.0 }
- assertEquals(expected, actual)
- }
-
- @Test
- fun testRequireNoNulls() = runTest {
- assertEquals(testList.requireNoNulls(), testList.asReceiveChannel().requireNoNulls().toList())
- }
-
private fun <E> Iterable<E>.asReceiveChannel(context: CoroutineContext = Dispatchers.Unconfined): ReceiveChannel<E> =
GlobalScope.produce(context) {
for (element in this@asReceiveChannel)
diff --git a/kotlinx-coroutines-core/common/test/channels/ConflatedChannelArrayModelTest.kt b/kotlinx-coroutines-core/common/test/channels/ConflatedChannelArrayModelTest.kt
new file mode 100644
index 0000000..e80309b
--- /dev/null
+++ b/kotlinx-coroutines-core/common/test/channels/ConflatedChannelArrayModelTest.kt
@@ -0,0 +1,11 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.channels
+
+// Test that ArrayChannel(1, DROP_OLDEST) works just like ConflatedChannel()
+class ConflatedChannelArrayModelTest : ConflatedChannelTest() {
+ override fun <T> createConflatedChannel(): Channel<T> =
+ ArrayChannel<T>(1, BufferOverflow.DROP_OLDEST, null)
+}
diff --git a/kotlinx-coroutines-core/common/test/channels/ConflatedChannelTest.kt b/kotlinx-coroutines-core/common/test/channels/ConflatedChannelTest.kt
index 4deb385..18f2843 100644
--- a/kotlinx-coroutines-core/common/test/channels/ConflatedChannelTest.kt
+++ b/kotlinx-coroutines-core/common/test/channels/ConflatedChannelTest.kt
@@ -1,5 +1,5 @@
/*
- * Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
*/
package kotlinx.coroutines.channels
@@ -7,10 +7,13 @@
import kotlinx.coroutines.*
import kotlin.test.*
-class ConflatedChannelTest : TestBase() {
+open class ConflatedChannelTest : TestBase() {
+ protected open fun <T> createConflatedChannel() =
+ Channel<T>(Channel.CONFLATED)
+
@Test
fun testBasicConflationOfferPoll() {
- val q = Channel<Int>(Channel.CONFLATED)
+ val q = createConflatedChannel<Int>()
assertNull(q.poll())
assertTrue(q.offer(1))
assertTrue(q.offer(2))
@@ -21,7 +24,7 @@
@Test
fun testConflatedSend() = runTest {
- val q = ConflatedChannel<Int>()
+ val q = createConflatedChannel<Int>()
q.send(1)
q.send(2) // shall conflated previously sent
assertEquals(2, q.receiveOrNull())
@@ -29,7 +32,7 @@
@Test
fun testConflatedClose() = runTest {
- val q = Channel<Int>(Channel.CONFLATED)
+ val q = createConflatedChannel<Int>()
q.send(1)
q.close() // shall become closed but do not conflate last sent item yet
assertTrue(q.isClosedForSend)
@@ -43,7 +46,7 @@
@Test
fun testConflationSendReceive() = runTest {
- val q = Channel<Int>(Channel.CONFLATED)
+ val q = createConflatedChannel<Int>()
expect(1)
launch { // receiver coroutine
expect(4)
@@ -71,7 +74,7 @@
@Test
fun testConsumeAll() = runTest {
- val q = Channel<Int>(Channel.CONFLATED)
+ val q = createConflatedChannel<Int>()
expect(1)
for (i in 1..10) {
q.send(i) // stores as last
@@ -85,7 +88,7 @@
@Test
fun testCancelWithCause() = runTest({ it is TestCancellationException }) {
- val channel = Channel<Int>(Channel.CONFLATED)
+ val channel = createConflatedChannel<Int>()
channel.cancel(TestCancellationException())
channel.receiveOrNull()
}
diff --git a/kotlinx-coroutines-core/common/test/channels/ProduceTest.kt b/kotlinx-coroutines-core/common/test/channels/ProduceTest.kt
index 885f1d6..6ddde00 100644
--- a/kotlinx-coroutines-core/common/test/channels/ProduceTest.kt
+++ b/kotlinx-coroutines-core/common/test/channels/ProduceTest.kt
@@ -163,7 +163,7 @@
private suspend fun cancelOnCompletion(coroutineContext: CoroutineContext) = CoroutineScope(coroutineContext).apply {
val source = Channel<Int>()
expect(1)
- val produced = produce<Int>(coroutineContext, onCompletion = source.consumes()) {
+ val produced = produce<Int>(coroutineContext, onCompletion = { source.cancelConsumed(it) }) {
expect(2)
source.receive()
}
diff --git a/kotlinx-coroutines-core/common/test/channels/TestChannelKind.kt b/kotlinx-coroutines-core/common/test/channels/TestChannelKind.kt
index 69d8fd0..993be78 100644
--- a/kotlinx-coroutines-core/common/test/channels/TestChannelKind.kt
+++ b/kotlinx-coroutines-core/common/test/channels/TestChannelKind.kt
@@ -7,9 +7,10 @@
import kotlinx.coroutines.*
import kotlinx.coroutines.selects.*
-enum class TestChannelKind(val capacity: Int,
- private val description: String,
- private val viaBroadcast: Boolean = false
+enum class TestChannelKind(
+ val capacity: Int,
+ private val description: String,
+ val viaBroadcast: Boolean = false
) {
RENDEZVOUS(0, "RendezvousChannel"),
ARRAY_1(1, "ArrayChannel(1)"),
@@ -22,8 +23,11 @@
CONFLATED_BROADCAST(Channel.CONFLATED, "ConflatedBroadcastChannel", viaBroadcast = true)
;
- fun create(): Channel<Int> = if (viaBroadcast) ChannelViaBroadcast(BroadcastChannel(capacity))
- else Channel(capacity)
+ fun <T> create(onUndeliveredElement: ((T) -> Unit)? = null): Channel<T> = when {
+ viaBroadcast && onUndeliveredElement != null -> error("Broadcast channels to do not support onUndeliveredElement")
+ viaBroadcast -> ChannelViaBroadcast(BroadcastChannel(capacity))
+ else -> Channel(capacity, onUndeliveredElement = onUndeliveredElement)
+ }
val isConflated get() = capacity == Channel.CONFLATED
override fun toString(): String = description
diff --git a/kotlinx-coroutines-core/common/test/flow/StateFlowTest.kt b/kotlinx-coroutines-core/common/test/flow/StateFlowTest.kt
deleted file mode 100644
index a6be97e..0000000
--- a/kotlinx-coroutines-core/common/test/flow/StateFlowTest.kt
+++ /dev/null
@@ -1,113 +0,0 @@
-/*
- * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
- */
-
-package kotlinx.coroutines.flow
-
-import kotlinx.coroutines.*
-import kotlin.test.*
-
-class StateFlowTest : TestBase() {
- @Test
- fun testNormalAndNull() = runTest {
- expect(1)
- val state = MutableStateFlow<Int?>(0)
- val job = launch(start = CoroutineStart.UNDISPATCHED) {
- expect(2)
- assertFailsWith<CancellationException> {
- state.collect { value ->
- when (value) {
- 0 -> expect(3)
- 1 -> expect(5)
- null -> expect(8)
- 2 -> expect(10)
- else -> expectUnreached()
- }
- }
- }
- expect(12)
- }
- expect(4) // collector is waiting
- state.value = 1 // fire in the hole!
- assertEquals(1, state.value)
- yield()
- expect(6)
- state.value = 1 // same value, nothing happens
- yield()
- expect(7)
- state.value = null // null value
- assertNull(state.value)
- yield()
- expect(9)
- state.value = 2 // another value
- assertEquals(2, state.value)
- yield()
- expect(11)
- job.cancel()
- yield()
- finish(13)
- }
-
- @Test
- fun testEqualsConflation() = runTest {
- expect(1)
- val state = MutableStateFlow(Data(0))
- val job = launch(start = CoroutineStart.UNDISPATCHED) {
- expect(2)
- assertFailsWith<CancellationException> {
- state.collect { value ->
- when(value.i) {
- 0 -> expect(3) // initial value
- 2 -> expect(5)
- 4 -> expect(7)
- else -> error("Unexpected $value")
- }
- }
- }
- expect(9)
- }
- state.value = Data(1) // conflated
- state.value = Data(0) // equals to last emitted
- yield() // no repeat zero
- state.value = Data(3) // conflated
- state.value = Data(2) // delivered
- expect(4)
- yield()
- state.value = Data(2) // equals to last one, dropped
- yield()
- state.value = Data(5) // conflated
- state.value = Data(4) // delivered
- expect(6)
- yield()
- expect(8)
- job.cancel()
- yield()
- finish(10)
- }
-
- data class Data(val i: Int)
-
- @Test
- fun testDataModel() = runTest {
- val s = CounterModel()
- launch {
- val sum = s.counter.take(11).sum()
- assertEquals(55, sum)
- }
- repeat(10) {
- yield()
- s.inc()
- }
- }
-
- class CounterModel {
- // private data flow
- private val _counter = MutableStateFlow(0)
- // publicly exposed as a flow
- val counter: StateFlow<Int> get() = _counter
-
- fun inc() {
- _counter.value++
- }
- }
-}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/common/test/flow/VirtualTime.kt b/kotlinx-coroutines-core/common/test/flow/VirtualTime.kt
index 9b257d9..ddb1d88 100644
--- a/kotlinx-coroutines-core/common/test/flow/VirtualTime.kt
+++ b/kotlinx-coroutines-core/common/test/flow/VirtualTime.kt
@@ -1,5 +1,5 @@
/*
- * Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
*/
package kotlinx.coroutines
@@ -7,11 +7,12 @@
import kotlin.coroutines.*
import kotlin.jvm.*
-private class VirtualTimeDispatcher(enclosingScope: CoroutineScope) : CoroutineDispatcher(), Delay {
-
+internal class VirtualTimeDispatcher(enclosingScope: CoroutineScope) : CoroutineDispatcher(), Delay {
private val originalDispatcher = enclosingScope.coroutineContext[ContinuationInterceptor] as CoroutineDispatcher
private val heap = ArrayList<TimedTask>() // TODO use MPP heap/ordered set implementation (commonize ThreadSafeHeap)
- private var currentTime = 0L
+
+ var currentTime = 0L
+ private set
init {
/*
@@ -50,17 +51,20 @@
@ExperimentalCoroutinesApi
override fun isDispatchNeeded(context: CoroutineContext): Boolean = originalDispatcher.isDispatchNeeded(context)
- override fun invokeOnTimeout(timeMillis: Long, block: Runnable): DisposableHandle {
- val task = TimedTask(block, currentTime + timeMillis)
+ override fun invokeOnTimeout(timeMillis: Long, block: Runnable, context: CoroutineContext): DisposableHandle {
+ val task = TimedTask(block, deadline(timeMillis))
heap += task
return task
}
override fun scheduleResumeAfterDelay(timeMillis: Long, continuation: CancellableContinuation<Unit>) {
- val task = TimedTask(Runnable { with(continuation) { resumeUndispatched(Unit) } }, currentTime + timeMillis)
+ val task = TimedTask(Runnable { with(continuation) { resumeUndispatched(Unit) } }, deadline(timeMillis))
heap += task
continuation.invokeOnCancellation { task.dispose() }
}
+
+ private fun deadline(timeMillis: Long) =
+ if (timeMillis == Long.MAX_VALUE) Long.MAX_VALUE else currentTime + timeMillis
}
/**
diff --git a/kotlinx-coroutines-core/common/test/flow/operators/BufferConflationTest.kt b/kotlinx-coroutines-core/common/test/flow/operators/BufferConflationTest.kt
new file mode 100644
index 0000000..7b66977
--- /dev/null
+++ b/kotlinx-coroutines-core/common/test/flow/operators/BufferConflationTest.kt
@@ -0,0 +1,146 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.flow
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.channels.*
+import kotlin.test.*
+
+/**
+ * A _behavioral_ test for conflation options that can be configured by the [buffer] operator to test that it is
+ * implemented properly and that adjacent [buffer] calls are fused properly.
+*/
+class BufferConflationTest : TestBase() {
+ private val n = 100 // number of elements to emit for test
+
+ private fun checkConflate(
+ capacity: Int,
+ onBufferOverflow: BufferOverflow = BufferOverflow.DROP_OLDEST,
+ op: suspend Flow<Int>.() -> Flow<Int>
+ ) = runTest {
+ expect(1)
+ // emit all and conflate, then collect first & last
+ val expectedList = when (onBufferOverflow) {
+ BufferOverflow.DROP_OLDEST -> listOf(0) + (n - capacity until n).toList() // first item & capacity last ones
+ BufferOverflow.DROP_LATEST -> (0..capacity).toList() // first & capacity following ones
+ else -> error("cannot happen")
+ }
+ flow {
+ repeat(n) { i ->
+ expect(i + 2)
+ emit(i)
+ }
+ }
+ .op()
+ .collect { i ->
+ val j = expectedList.indexOf(i)
+ expect(n + 2 + j)
+ }
+ finish(n + 2 + expectedList.size)
+ }
+
+ @Test
+ fun testConflate() =
+ checkConflate(1) {
+ conflate()
+ }
+
+ @Test
+ fun testBufferConflated() =
+ checkConflate(1) {
+ buffer(Channel.CONFLATED)
+ }
+
+ @Test
+ fun testBufferDropOldest() =
+ checkConflate(1) {
+ buffer(onBufferOverflow = BufferOverflow.DROP_OLDEST)
+ }
+
+ @Test
+ fun testBuffer0DropOldest() =
+ checkConflate(1) {
+ buffer(0, onBufferOverflow = BufferOverflow.DROP_OLDEST)
+ }
+
+ @Test
+ fun testBuffer1DropOldest() =
+ checkConflate(1) {
+ buffer(1, onBufferOverflow = BufferOverflow.DROP_OLDEST)
+ }
+
+ @Test
+ fun testBuffer10DropOldest() =
+ checkConflate(10) {
+ buffer(10, onBufferOverflow = BufferOverflow.DROP_OLDEST)
+ }
+
+ @Test
+ fun testConflateOverridesBuffer() =
+ checkConflate(1) {
+ buffer(42).conflate()
+ }
+
+ @Test // conflate().conflate() should work like a single conflate
+ fun testDoubleConflate() =
+ checkConflate(1) {
+ conflate().conflate()
+ }
+
+ @Test
+ fun testConflateBuffer10Combine() =
+ checkConflate(10) {
+ conflate().buffer(10)
+ }
+
+ @Test
+ fun testBufferDropLatest() =
+ checkConflate(1, BufferOverflow.DROP_LATEST) {
+ buffer(onBufferOverflow = BufferOverflow.DROP_LATEST)
+ }
+
+ @Test
+ fun testBuffer0DropLatest() =
+ checkConflate(1, BufferOverflow.DROP_LATEST) {
+ buffer(0, onBufferOverflow = BufferOverflow.DROP_LATEST)
+ }
+
+ @Test
+ fun testBuffer1DropLatest() =
+ checkConflate(1, BufferOverflow.DROP_LATEST) {
+ buffer(1, onBufferOverflow = BufferOverflow.DROP_LATEST)
+ }
+
+ @Test // overrides previous buffer
+ fun testBufferDropLatestOverrideBuffer() =
+ checkConflate(1, BufferOverflow.DROP_LATEST) {
+ buffer(42).buffer(onBufferOverflow = BufferOverflow.DROP_LATEST)
+ }
+
+ @Test // overrides previous conflate
+ fun testBufferDropLatestOverrideConflate() =
+ checkConflate(1, BufferOverflow.DROP_LATEST) {
+ conflate().buffer(onBufferOverflow = BufferOverflow.DROP_LATEST)
+ }
+
+ @Test
+ fun testBufferDropLatestBuffer7Combine() =
+ checkConflate(7, BufferOverflow.DROP_LATEST) {
+ buffer(onBufferOverflow = BufferOverflow.DROP_LATEST).buffer(7)
+ }
+
+ @Test
+ fun testConflateOverrideBufferDropLatest() =
+ checkConflate(1) {
+ buffer(onBufferOverflow = BufferOverflow.DROP_LATEST).conflate()
+ }
+
+ @Test
+ fun testBuffer3DropOldestOverrideBuffer8DropLatest() =
+ checkConflate(3, BufferOverflow.DROP_OLDEST) {
+ buffer(8, onBufferOverflow = BufferOverflow.DROP_LATEST)
+ .buffer(3, BufferOverflow.DROP_OLDEST)
+ }
+}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/common/test/flow/operators/BufferTest.kt b/kotlinx-coroutines-core/common/test/flow/operators/BufferTest.kt
index b68e115..6352aac 100644
--- a/kotlinx-coroutines-core/common/test/flow/operators/BufferTest.kt
+++ b/kotlinx-coroutines-core/common/test/flow/operators/BufferTest.kt
@@ -1,5 +1,5 @@
/*
- * Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
*/
package kotlinx.coroutines.flow
@@ -9,13 +9,21 @@
import kotlin.math.*
import kotlin.test.*
+/**
+ * A _behavioral_ test for buffering that is introduced by the [buffer] operator to test that it is
+ * implemented properly and that adjacent [buffer] calls are fused properly.
+ */
class BufferTest : TestBase() {
- private val n = 50 // number of elements to emit for test
+ private val n = 200 // number of elements to emit for test
private val defaultBufferSize = 64 // expected default buffer size (per docs)
// Use capacity == -1 to check case of "no buffer"
private fun checkBuffer(capacity: Int, op: suspend Flow<Int>.() -> Flow<Int>) = runTest {
expect(1)
+ /*
+ Channels perform full rendezvous. Sender does not suspend when there is a suspended receiver and vice-versa.
+ Thus, perceived batch size is +2 from capacity.
+ */
val batchSize = capacity + 2
flow {
repeat(n) { i ->
@@ -164,27 +172,6 @@
}
@Test
- fun testConflate() = runTest {
- expect(1)
- // emit all and conflate / then collect first & last
- flow {
- repeat(n) { i ->
- expect(i + 2)
- emit(i)
- }
- }
- .buffer(Channel.CONFLATED)
- .collect { i ->
- when (i) {
- 0 -> expect(n + 2) // first value
- n - 1 -> expect(n + 3) // last value
- else -> error("Unexpected $i")
- }
- }
- finish(n + 4)
- }
-
- @Test
fun testCancellation() = runTest {
val result = flow {
emit(1)
diff --git a/kotlinx-coroutines-core/common/test/flow/operators/CatchTest.kt b/kotlinx-coroutines-core/common/test/flow/operators/CatchTest.kt
index 802ba1e..eedfac2 100644
--- a/kotlinx-coroutines-core/common/test/flow/operators/CatchTest.kt
+++ b/kotlinx-coroutines-core/common/test/flow/operators/CatchTest.kt
@@ -134,15 +134,14 @@
// flowOn with a different dispatcher introduces asynchrony so that all exceptions in the
// upstream flows are handled before they go downstream
.onEach { value ->
- expect(8)
- assertEquals("OK", value)
+ expectUnreached() // already cancelled
}
.catch { e ->
- expect(9)
+ expect(8)
assertTrue(e is TestException)
assertSame(d0, kotlin.coroutines.coroutineContext[ContinuationInterceptor] as CoroutineContext)
}
.collect()
- finish(10)
+ finish(9)
}
}
diff --git a/kotlinx-coroutines-core/common/test/flow/operators/CombineParametersTestBase.kt b/kotlinx-coroutines-core/common/test/flow/operators/CombineParametersTestBase.kt
index b51197e..8c65ea4 100644
--- a/kotlinx-coroutines-core/common/test/flow/operators/CombineParametersTestBase.kt
+++ b/kotlinx-coroutines-core/common/test/flow/operators/CombineParametersTestBase.kt
@@ -161,4 +161,33 @@
}.singleOrNull()
assertNull(value)
}
+
+ @Test
+ fun testFairnessInVariousConfigurations() = runTest {
+ // Test various configurations
+ for (flowsCount in 2..5) {
+ for (flowSize in 1..5) {
+ val flows = List(flowsCount) { (1..flowSize).asFlow() }
+ val combined = combine(flows) { it.joinToString(separator = "") }.toList()
+ val expected = List(flowSize) { (it + 1).toString().repeat(flowsCount) }
+ assertEquals(expected, combined, "Count: $flowsCount, size: $flowSize")
+ }
+ }
+ }
+
+ @Test
+ fun testEpochOverflow() = runTest {
+ val flow = (0..1023).asFlow()
+ val result = flow.combine(flow) { a, b -> a + b }.toList()
+ assertEquals(List(1024) { it * 2 } , result)
+ }
+
+ @Test
+ fun testArrayType() = runTest {
+ val arr = flowOf(1)
+ combine(listOf(arr, arr)) {
+ println(it[0])
+ it[0]
+ }.toList().also { println(it) }
+ }
}
diff --git a/kotlinx-coroutines-core/common/test/flow/operators/CombineTest.kt b/kotlinx-coroutines-core/common/test/flow/operators/CombineTest.kt
index a619355..5e2926d 100644
--- a/kotlinx-coroutines-core/common/test/flow/operators/CombineTest.kt
+++ b/kotlinx-coroutines-core/common/test/flow/operators/CombineTest.kt
@@ -1,10 +1,11 @@
/*
- * Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
*/
-
-package kotlinx.coroutines.flow
+@file:Suppress("UNCHECKED_CAST")
+package kotlinx.coroutines.flow.operators
import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
import kotlin.test.*
import kotlinx.coroutines.flow.combine as combineOriginal
import kotlinx.coroutines.flow.combineTransform as combineTransformOriginal
@@ -21,28 +22,28 @@
val flow = flowOf("a", "b", "c")
val flow2 = flowOf(1, 2, 3)
val list = flow.combineLatest(flow2) { i, j -> i + j }.toList()
- assertEquals(listOf("a1", "b1", "b2", "c2", "c3"), list)
+ assertEquals(listOf("a1", "b2", "c3"), list)
}
@Test
fun testNulls() = runTest {
val flow = flowOf("a", null, null)
val flow2 = flowOf(1, 2, 3)
- val list = flow.combineLatest(flow2, { i, j -> i + j }).toList()
- assertEquals(listOf("a1", "null1", "null2", "null2", "null3"), list)
+ val list = flow.combineLatest(flow2) { i, j -> i + j }.toList()
+ assertEquals(listOf("a1", "null2", "null3"), list)
}
@Test
fun testNullsOther() = runTest {
val flow = flowOf("a", "b", "c")
val flow2 = flowOf(null, 2, null)
- val list = flow.combineLatest(flow2, { i, j -> i + j }).toList()
- assertEquals(listOf("anull", "bnull", "b2", "c2", "cnull"), list)
+ val list = flow.combineLatest(flow2) { i, j -> i + j }.toList()
+ assertEquals(listOf("anull", "b2", "cnull"), list)
}
@Test
fun testEmptyFlow() = runTest {
- val flow = emptyFlow<String>().combineLatest(emptyFlow<Int>(), { i, j -> i + j })
+ val flow = emptyFlow<String>().combineLatest(emptyFlow<Int>()) { i, j -> i + j }
assertNull(flow.singleOrNull())
}
@@ -208,12 +209,12 @@
}
val f2 = flow {
emit(1)
- hang { expect(3) }
+ expectUnreached()
}
- val flow = f1.combineLatest(f2, { _, _ -> 1 }).onEach { expect(2) }
+ val flow = f1.combineLatest(f2) { _, _ -> 1 }.onEach { expect(2) }
assertFailsWith<CancellationException>(flow)
- finish(4)
+ finish(3)
}
@Test
@@ -229,7 +230,7 @@
hang { expect(6) }
}
- val flow = f1.combineLatest(f2, { _, _ -> 1 }).onEach {
+ val flow = f1.combineLatest(f2) { _, _ -> 1 }.onEach {
expect(1)
yield()
expect(4)
@@ -238,6 +239,22 @@
assertFailsWith<CancellationException>(flow)
finish(7)
}
+
+ @Test
+ fun testCancelledCombine() = runTest(
+ expected = { it is CancellationException }
+ ) {
+ coroutineScope {
+ val flow = flow {
+ emit(Unit) // emit
+ }
+ cancel() // cancel the scope
+ flow.combineLatest(flow) { _, _ -> }.collect {
+ // should not be reached, because cancelled before it runs
+ expectUnreached()
+ }
+ }
+ }
}
class CombineTest : CombineTestBase() {
@@ -249,15 +266,26 @@
emit(transform(a, b))
}
}
+// Array null-out is an additional test for our array elimination optimization
class CombineVarargAdapterTest : CombineTestBase() {
override fun <T1, T2, R> Flow<T1>.combineLatest(other: Flow<T2>, transform: suspend (T1, T2) -> R): Flow<R> =
- combineOriginal(this, other) { args: Array<Any?> -> transform(args[0] as T1, args[1] as T2) }
+ combineOriginal(this, other) { args: Array<Any?> ->
+ transform(args[0] as T1, args[1] as T2).also {
+ args[0] = null
+ args[1] = null
+ }
+ }
}
class CombineIterableTest : CombineTestBase() {
override fun <T1, T2, R> Flow<T1>.combineLatest(other: Flow<T2>, transform: suspend (T1, T2) -> R): Flow<R> =
- combineOriginal(listOf(this, other)) { args -> transform(args[0] as T1, args[1] as T2) }
+ combineOriginal(listOf(this, other)) { args ->
+ transform(args[0] as T1, args[1] as T2).also {
+ args[0] = null
+ args[1] = null
+ }
+ }
}
class CombineTransformAdapterTest : CombineTestBase() {
@@ -267,11 +295,20 @@
class CombineTransformVarargAdapterTest : CombineTestBase() {
override fun <T1, T2, R> Flow<T1>.combineLatest(other: Flow<T2>, transform: suspend (T1, T2) -> R): Flow<R> =
- combineTransformOriginal(this, other) { args: Array<Any?> -> emit(transform(args[0] as T1, args[1] as T2)) }
+ combineTransformOriginal(this, other) { args: Array<Any?> ->
+ emit(transform(args[0] as T1, args[1] as T2)) // Mess up with array
+ args[0] = null
+ args[1] = null
+ }
}
class CombineTransformIterableTest : CombineTestBase() {
override fun <T1, T2, R> Flow<T1>.combineLatest(other: Flow<T2>, transform: suspend (T1, T2) -> R): Flow<R> =
- combineTransformOriginal(listOf(this, other)) { args -> emit(transform(args[0] as T1, args[1] as T2)) }
+ combineTransformOriginal(listOf(this, other)) { args ->
+ emit(transform(args[0] as T1, args[1] as T2))
+ // Mess up with array
+ args[0] = null
+ args[1] = null
+ }
}
diff --git a/kotlinx-coroutines-core/common/test/flow/operators/DebounceTest.kt b/kotlinx-coroutines-core/common/test/flow/operators/DebounceTest.kt
index 4065671..ce75e59 100644
--- a/kotlinx-coroutines-core/common/test/flow/operators/DebounceTest.kt
+++ b/kotlinx-coroutines-core/common/test/flow/operators/DebounceTest.kt
@@ -11,7 +11,7 @@
class DebounceTest : TestBase() {
@Test
- public fun testBasic() = withVirtualTime {
+ fun testBasic() = withVirtualTime {
expect(1)
val flow = flow {
expect(3)
@@ -159,7 +159,7 @@
expect(2)
throw TestException()
}.flowOn(NamedDispatchers("source")).debounce(Long.MAX_VALUE).map {
- expectUnreached()
+ expectUnreached()
}
assertFailsWith<TestException>(flow)
finish(3)
@@ -175,7 +175,6 @@
expect(2)
yield()
throw TestException()
- it
}
assertFailsWith<TestException>(flow)
@@ -193,7 +192,6 @@
expect(2)
yield()
throw TestException()
- it
}
assertFailsWith<TestException>(flow)
@@ -202,7 +200,7 @@
@ExperimentalTime
@Test
- public fun testDurationBasic() = withVirtualTime {
+ fun testDurationBasic() = withVirtualTime {
expect(1)
val flow = flow {
expect(3)
@@ -223,4 +221,102 @@
assertEquals(listOf("A", "D", "E"), result)
finish(5)
}
+
+ @ExperimentalTime
+ @Test
+ fun testDebounceSelectorBasic() = withVirtualTime {
+ expect(1)
+ val flow = flow {
+ expect(3)
+ emit(1)
+ delay(90)
+ emit(2)
+ delay(90)
+ emit(3)
+ delay(1010)
+ emit(4)
+ delay(1010)
+ emit(5)
+ expect(4)
+ }
+
+ expect(2)
+ val result = flow.debounce {
+ if (it == 1) {
+ 0
+ } else {
+ 1000
+ }
+ }.toList()
+
+ assertEquals(listOf(1, 3, 4, 5), result)
+ finish(5)
+ }
+
+ @Test
+ fun testZeroDebounceTime() = withVirtualTime {
+ expect(1)
+ val flow = flow {
+ expect(3)
+ emit("A")
+ emit("B")
+ emit("C")
+ expect(4)
+ }
+
+ expect(2)
+ val result = flow.debounce(0).toList()
+
+ assertEquals(listOf("A", "B", "C"), result)
+ finish(5)
+ }
+
+ @ExperimentalTime
+ @Test
+ fun testZeroDebounceTimeSelector() = withVirtualTime {
+ expect(1)
+ val flow = flow {
+ expect(3)
+ emit("A")
+ emit("B")
+ expect(4)
+ }
+
+ expect(2)
+ val result = flow.debounce { 0 }.toList()
+
+ assertEquals(listOf("A", "B"), result)
+ finish(5)
+ }
+
+ @ExperimentalTime
+ @Test
+ fun testDebounceDurationSelectorBasic() = withVirtualTime {
+ expect(1)
+ val flow = flow {
+ expect(3)
+ emit("A")
+ delay(1500.milliseconds)
+ emit("B")
+ delay(500.milliseconds)
+ emit("C")
+ delay(250.milliseconds)
+ emit("D")
+ delay(2000.milliseconds)
+ emit("E")
+ expect(4)
+ }
+
+ expect(2)
+ val result = flow.debounce {
+ if (it == "C") {
+ 0.milliseconds
+ } else {
+ 1000.milliseconds
+ }
+ }.toList()
+
+ assertEquals(listOf("A", "C", "D", "E"), result)
+ finish(5)
+ }
}
diff --git a/kotlinx-coroutines-core/common/test/flow/operators/DistinctUntilChangedTest.kt b/kotlinx-coroutines-core/common/test/flow/operators/DistinctUntilChangedTest.kt
index fc03d36..68e7f66 100644
--- a/kotlinx-coroutines-core/common/test/flow/operators/DistinctUntilChangedTest.kt
+++ b/kotlinx-coroutines-core/common/test/flow/operators/DistinctUntilChangedTest.kt
@@ -94,4 +94,33 @@
val flow = flowOf(null, 1, null, null).distinctUntilChanged()
assertEquals(listOf(null, 1, null), flow.toList())
}
+
+ @Test
+ fun testRepeatedDistinctFusionDefault() = testRepeatedDistinctFusion {
+ distinctUntilChanged()
+ }
+
+ // A separate variable is needed for K/N that does not optimize non-captured lambdas (yet)
+ private val areEquivalentTestFun: (old: Int, new: Int) -> Boolean = { old, new -> old == new }
+
+ @Test
+ fun testRepeatedDistinctFusionAreEquivalent() = testRepeatedDistinctFusion {
+ distinctUntilChanged(areEquivalentTestFun)
+ }
+
+ // A separate variable is needed for K/N that does not optimize non-captured lambdas (yet)
+ private val keySelectorTestFun: (Int) -> Int = { it % 2 }
+
+ @Test
+ fun testRepeatedDistinctFusionByKey() = testRepeatedDistinctFusion {
+ distinctUntilChangedBy(keySelectorTestFun)
+ }
+
+ private fun testRepeatedDistinctFusion(op: Flow<Int>.() -> Flow<Int>) = runTest {
+ val flow = (1..10).asFlow()
+ val d1 = flow.op()
+ assertNotSame(flow, d1)
+ val d2 = d1.op()
+ assertSame(d1, d2)
+ }
}
diff --git a/kotlinx-coroutines-core/common/test/flow/operators/FlowOnTest.kt b/kotlinx-coroutines-core/common/test/flow/operators/FlowOnTest.kt
index f8350ff..6865328 100644
--- a/kotlinx-coroutines-core/common/test/flow/operators/FlowOnTest.kt
+++ b/kotlinx-coroutines-core/common/test/flow/operators/FlowOnTest.kt
@@ -341,4 +341,20 @@
assertEquals(expected, value)
}
}
+
+ @Test
+ fun testCancelledFlowOn() = runTest {
+ assertFailsWith<CancellationException> {
+ coroutineScope {
+ val scope = this
+ flow {
+ emit(Unit) // emit to buffer
+ scope.cancel() // now cancel outer scope
+ }.flowOn(wrapperDispatcher()).collect {
+ // should not be reached, because cancelled before it runs
+ expectUnreached()
+ }
+ }
+ }
+ }
}
diff --git a/kotlinx-coroutines-core/common/test/flow/operators/OnCompletionTest.kt b/kotlinx-coroutines-core/common/test/flow/operators/OnCompletionTest.kt
index 7f0c548..f55e8be 100644
--- a/kotlinx-coroutines-core/common/test/flow/operators/OnCompletionTest.kt
+++ b/kotlinx-coroutines-core/common/test/flow/operators/OnCompletionTest.kt
@@ -231,7 +231,7 @@
@Test
fun testSingle() = runTest {
- assertFailsWith<IllegalStateException> {
+ assertFailsWith<IllegalArgumentException> {
flowOf(239).onCompletion {
assertNull(it)
expect(1)
@@ -240,7 +240,7 @@
expectUnreached()
} catch (e: Throwable) {
// Second emit -- failure
- assertTrue { e is IllegalStateException }
+ assertTrue { e is IllegalArgumentException }
throw e
}
}.single()
diff --git a/kotlinx-coroutines-core/common/test/flow/operators/ZipTest.kt b/kotlinx-coroutines-core/common/test/flow/operators/ZipTest.kt
index b28320c..02dbfc4 100644
--- a/kotlinx-coroutines-core/common/test/flow/operators/ZipTest.kt
+++ b/kotlinx-coroutines-core/common/test/flow/operators/ZipTest.kt
@@ -23,7 +23,7 @@
fun testUnevenZip() = runTest {
val f1 = flowOf("a", "b", "c", "d", "e")
val f2 = flowOf(1, 2, 3)
- assertEquals(listOf("a1", "b2", "c3"), f1.zip(f2, { i, j -> i + j }).toList())
+ assertEquals(listOf("a1", "b2", "c3"), f1.zip(f2) { i, j -> i + j }.toList())
assertEquals(listOf("a1", "b2", "c3"), f2.zip(f1) { i, j -> j + i }.toList())
}
@@ -67,7 +67,26 @@
val f1 = flow<String> {
emit("1")
emit("2")
- hang {
+ }
+
+ val f2 = flow<String> {
+ emit("a")
+ emit("b")
+ expectUnreached()
+ }
+ assertEquals(listOf("1a", "2b"), f1.zip(f2) { s1, s2 -> s1 + s2 }.toList())
+ finish(1)
+ }
+
+ @Test
+ fun testCancelWhenFlowIsDone2() = runTest {
+ val f1 = flow<String> {
+ emit("1")
+ emit("2")
+ try {
+ emit("3")
+ expectUnreached()
+ } finally {
expect(1)
}
}
@@ -87,27 +106,13 @@
}
}
- val f2 = flowOf("a", "b")
- assertEquals(listOf("a1", "b2"), f2.zip(f1) { s1, s2 -> s1 + s2 }.toList())
- finish(2)
- }
-
- @Test
- fun testCancelWhenFlowIsDone2() = runTest {
- val f1 = flow<String> {
- emit("1")
- emit("2")
- try {
- emit("3")
- expectUnreached()
- } finally {
- expect(1)
- }
-
+ val f2 = flow<String> {
+ emit("a")
+ emit("b")
+ yield()
}
- val f2 = flowOf("a", "b")
- assertEquals(listOf("1a", "2b"), f1.zip(f2) { s1, s2 -> s1 + s2 }.toList())
+ assertEquals(listOf("a1", "b2"), f2.zip(f1) { s1, s2 -> s1 + s2 }.toList())
finish(2)
}
@@ -116,19 +121,19 @@
val f1 = flow {
emit("a")
assertEquals("first", NamedDispatchers.name())
- expect(1)
+ expect(3)
}.flowOn(NamedDispatchers("first")).onEach {
assertEquals("with", NamedDispatchers.name())
- expect(2)
+ expect(4)
}.flowOn(NamedDispatchers("with"))
val f2 = flow {
emit(1)
assertEquals("second", NamedDispatchers.name())
- expect(3)
+ expect(1)
}.flowOn(NamedDispatchers("second")).onEach {
assertEquals("nested", NamedDispatchers.name())
- expect(4)
+ expect(2)
}.flowOn(NamedDispatchers("nested"))
val value = withContext(NamedDispatchers("main")) {
@@ -148,14 +153,14 @@
val f1 = flow {
emit("a")
hang {
- expect(2)
+ expect(3)
}
}.flowOn(NamedDispatchers("first"))
val f2 = flow {
emit(1)
hang {
- expect(3)
+ expect(2)
}
}.flowOn(NamedDispatchers("second"))
@@ -195,19 +200,18 @@
val f1 = flow {
expect(1)
emit(1)
- yield()
- expect(4)
+ expect(5)
throw CancellationException("")
}
val f2 = flow {
expect(2)
emit(1)
- expect(5)
+ expect(3)
hang { expect(6) }
}
- val flow = f1.zip(f2, { _, _ -> 1 }).onEach { expect(3) }
+ val flow = f1.zip(f2) { _, _ -> 1 }.onEach { expect(4) }
assertFailsWith<CancellationException>(flow)
finish(7)
}
@@ -217,24 +221,37 @@
val f1 = flow {
expect(1)
emit(1)
- yield()
- expect(4)
- hang { expect(6) }
+ expectUnreached() // Will throw CE
}
val f2 = flow {
expect(2)
emit(1)
- expect(5)
- hang { expect(7) }
+ expect(3)
+ hang { expect(5) }
}
val flow = f1.zip(f2, { _, _ -> 1 }).onEach {
- expect(3)
+ expect(4)
yield()
throw CancellationException("")
}
assertFailsWith<CancellationException>(flow)
- finish(8)
+ finish(6)
+ }
+
+ @Test
+ fun testCancellationOfCollector() = runTest {
+ val f1 = flow {
+ emit("1")
+ awaitCancellation()
+ }
+
+ val f2 = flow {
+ emit("2")
+ yield()
+ }
+
+ f1.zip(f2) { a, b -> a + b }.collect { }
}
}
diff --git a/kotlinx-coroutines-core/common/test/flow/sharing/ShareInBufferTest.kt b/kotlinx-coroutines-core/common/test/flow/sharing/ShareInBufferTest.kt
new file mode 100644
index 0000000..9c6aed2
--- /dev/null
+++ b/kotlinx-coroutines-core/common/test/flow/sharing/ShareInBufferTest.kt
@@ -0,0 +1,98 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.flow
+
+import kotlinx.coroutines.*
+import kotlin.math.*
+import kotlin.test.*
+
+/**
+ * Similar to [BufferTest], but tests [shareIn] buffering and its fusion with [buffer] operators.
+ */
+class ShareInBufferTest : TestBase() {
+ private val n = 200 // number of elements to emit for test
+ private val defaultBufferSize = 64 // expected default buffer size (per docs)
+
+ // Use capacity == -1 to check case of "no buffer"
+ private fun checkBuffer(capacity: Int, op: suspend Flow<Int>.(CoroutineScope) -> Flow<Int>) = runTest {
+ expect(1)
+ /*
+ Shared flows do not perform full rendezvous. On buffer overflow emitter always suspends until all
+ subscribers get the value and then resumes. Thus, perceived batch size is +1 from buffer capacity.
+ */
+ val batchSize = capacity + 1
+ val upstream = flow {
+ repeat(n) { i ->
+ val batchNo = i / batchSize
+ val batchIdx = i % batchSize
+ expect(batchNo * batchSize * 2 + batchIdx + 2)
+ emit(i)
+ }
+ emit(-1) // done
+ }
+ coroutineScope {
+ upstream
+ .op(this)
+ .takeWhile { i -> i >= 0 } // until done
+ .collect { i ->
+ val batchNo = i / batchSize
+ val batchIdx = i % batchSize
+ // last batch might have smaller size
+ val k = min((batchNo + 1) * batchSize, n) - batchNo * batchSize
+ expect(batchNo * batchSize * 2 + k + batchIdx + 2)
+ }
+ coroutineContext.cancelChildren() // cancels sharing
+ }
+ finish(2 * n + 2)
+ }
+
+ @Test
+ fun testReplay0DefaultBuffer() =
+ checkBuffer(defaultBufferSize) {
+ shareIn(it, SharingStarted.Eagerly)
+ }
+
+ @Test
+ fun testReplay1DefaultBuffer() =
+ checkBuffer(defaultBufferSize) {
+ shareIn(it, SharingStarted.Eagerly, 1)
+ }
+
+ @Test // buffer is padded to default size as needed
+ fun testReplay10DefaultBuffer() =
+ checkBuffer(maxOf(10, defaultBufferSize)) {
+ shareIn(it, SharingStarted.Eagerly, 10)
+ }
+
+ @Test // buffer is padded to default size as needed
+ fun testReplay100DefaultBuffer() =
+ checkBuffer( maxOf(100, defaultBufferSize)) {
+ shareIn(it, SharingStarted.Eagerly, 100)
+ }
+
+ @Test
+ fun testDefaultBufferKeepsDefault() =
+ checkBuffer(defaultBufferSize) {
+ buffer().shareIn(it, SharingStarted.Eagerly)
+ }
+
+ @Test
+ fun testOverrideDefaultBuffer0() =
+ checkBuffer(0) {
+ buffer(0).shareIn(it, SharingStarted.Eagerly)
+ }
+
+ @Test
+ fun testOverrideDefaultBuffer10() =
+ checkBuffer(10) {
+ buffer(10).shareIn(it, SharingStarted.Eagerly)
+ }
+
+ @Test // buffer and replay sizes add up
+ fun testBufferReplaySum() =
+ checkBuffer(41) {
+ buffer(10).buffer(20).shareIn(it, SharingStarted.Eagerly, 11)
+ }
+}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/common/test/flow/sharing/ShareInConflationTest.kt b/kotlinx-coroutines-core/common/test/flow/sharing/ShareInConflationTest.kt
new file mode 100644
index 0000000..0528e97
--- /dev/null
+++ b/kotlinx-coroutines-core/common/test/flow/sharing/ShareInConflationTest.kt
@@ -0,0 +1,162 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.flow
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.channels.*
+import kotlin.test.*
+
+/**
+ * Similar to [ShareInBufferTest] and [BufferConflationTest],
+ * but tests [shareIn] and its fusion with [conflate] operator.
+ */
+class ShareInConflationTest : TestBase() {
+ private val n = 100
+
+ private fun checkConflation(
+ bufferCapacity: Int,
+ onBufferOverflow: BufferOverflow = BufferOverflow.DROP_OLDEST,
+ op: suspend Flow<Int>.(CoroutineScope) -> Flow<Int>
+ ) = runTest {
+ expect(1)
+ // emit all and conflate, then should collect bufferCapacity latest ones
+ val done = Job()
+ flow {
+ repeat(n) { i ->
+ expect(i + 2)
+ emit(i)
+ }
+ done.join() // wait until done collection
+ emit(-1) // signal flow completion
+ }
+ .op(this)
+ .takeWhile { i -> i >= 0 }
+ .collect { i ->
+ val first = if (onBufferOverflow == BufferOverflow.DROP_LATEST) 0 else n - bufferCapacity
+ val last = first + bufferCapacity - 1
+ if (i in first..last) {
+ expect(n + i - first + 2)
+ if (i == last) done.complete() // received the last one
+ } else {
+ error("Unexpected $i")
+ }
+ }
+ finish(n + bufferCapacity + 2)
+ }
+
+ @Test
+ fun testConflateReplay1() =
+ checkConflation(1) {
+ conflate().shareIn(it, SharingStarted.Eagerly, 1)
+ }
+
+ @Test // still looks like conflating the last value for the first subscriber (will not replay to others though)
+ fun testConflateReplay0() =
+ checkConflation(1) {
+ conflate().shareIn(it, SharingStarted.Eagerly, 0)
+ }
+
+ @Test
+ fun testConflateReplay5() =
+ checkConflation(5) {
+ conflate().shareIn(it, SharingStarted.Eagerly, 5)
+ }
+
+ @Test
+ fun testBufferDropOldestReplay1() =
+ checkConflation(1) {
+ buffer(onBufferOverflow = BufferOverflow.DROP_OLDEST).shareIn(it, SharingStarted.Eagerly, 1)
+ }
+
+ @Test
+ fun testBufferDropOldestReplay0() =
+ checkConflation(1) {
+ buffer(onBufferOverflow = BufferOverflow.DROP_OLDEST).shareIn(it, SharingStarted.Eagerly, 0)
+ }
+
+ @Test
+ fun testBufferDropOldestReplay10() =
+ checkConflation(10) {
+ buffer(onBufferOverflow = BufferOverflow.DROP_OLDEST).shareIn(it, SharingStarted.Eagerly, 10)
+ }
+
+ @Test
+ fun testBuffer20DropOldestReplay0() =
+ checkConflation(20) {
+ buffer(20, onBufferOverflow = BufferOverflow.DROP_OLDEST).shareIn(it, SharingStarted.Eagerly, 0)
+ }
+
+ @Test
+ fun testBuffer7DropOldestReplay11() =
+ checkConflation(18) {
+ buffer(7, onBufferOverflow = BufferOverflow.DROP_OLDEST).shareIn(it, SharingStarted.Eagerly, 11)
+ }
+
+ @Test // a preceding buffer() gets overridden by conflate()
+ fun testBufferConflateOverride() =
+ checkConflation(1) {
+ buffer(23).conflate().shareIn(it, SharingStarted.Eagerly, 1)
+ }
+
+ @Test // a preceding buffer() gets overridden by buffer(onBufferOverflow = BufferOverflow.DROP_OLDEST)
+ fun testBufferDropOldestOverride() =
+ checkConflation(1) {
+ buffer(23).buffer(onBufferOverflow = BufferOverflow.DROP_OLDEST).shareIn(it, SharingStarted.Eagerly, 1)
+ }
+
+ @Test
+ fun testBufferDropLatestReplay0() =
+ checkConflation(1, BufferOverflow.DROP_LATEST) {
+ buffer(onBufferOverflow = BufferOverflow.DROP_LATEST).shareIn(it, SharingStarted.Eagerly, 0)
+ }
+
+ @Test
+ fun testBufferDropLatestReplay1() =
+ checkConflation(1, BufferOverflow.DROP_LATEST) {
+ buffer(onBufferOverflow = BufferOverflow.DROP_LATEST).shareIn(it, SharingStarted.Eagerly, 1)
+ }
+
+ @Test
+ fun testBufferDropLatestReplay10() =
+ checkConflation(10, BufferOverflow.DROP_LATEST) {
+ buffer(onBufferOverflow = BufferOverflow.DROP_LATEST).shareIn(it, SharingStarted.Eagerly, 10)
+ }
+
+ @Test
+ fun testBuffer0DropLatestReplay0() =
+ checkConflation(1, BufferOverflow.DROP_LATEST) {
+ buffer(0, onBufferOverflow = BufferOverflow.DROP_LATEST).shareIn(it, SharingStarted.Eagerly, 0)
+ }
+
+ @Test
+ fun testBuffer0DropLatestReplay1() =
+ checkConflation(1, BufferOverflow.DROP_LATEST) {
+ buffer(0, onBufferOverflow = BufferOverflow.DROP_LATEST).shareIn(it, SharingStarted.Eagerly, 1)
+ }
+
+ @Test
+ fun testBuffer0DropLatestReplay10() =
+ checkConflation(10, BufferOverflow.DROP_LATEST) {
+ buffer(0, onBufferOverflow = BufferOverflow.DROP_LATEST).shareIn(it, SharingStarted.Eagerly, 10)
+ }
+
+ @Test
+ fun testBuffer5DropLatestReplay0() =
+ checkConflation(5, BufferOverflow.DROP_LATEST) {
+ buffer(5, onBufferOverflow = BufferOverflow.DROP_LATEST).shareIn(it, SharingStarted.Eagerly, 0)
+ }
+
+ @Test
+ fun testBuffer5DropLatestReplay10() =
+ checkConflation(15, BufferOverflow.DROP_LATEST) {
+ buffer(5, onBufferOverflow = BufferOverflow.DROP_LATEST).shareIn(it, SharingStarted.Eagerly, 10)
+ }
+
+ @Test // a preceding buffer() gets overridden by buffer(onBufferOverflow = BufferOverflow.DROP_LATEST)
+ fun testBufferDropLatestOverride() =
+ checkConflation(1, BufferOverflow.DROP_LATEST) {
+ buffer(23).buffer(onBufferOverflow = BufferOverflow.DROP_LATEST).shareIn(it, SharingStarted.Eagerly, 0)
+ }
+}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/common/test/flow/sharing/ShareInFusionTest.kt b/kotlinx-coroutines-core/common/test/flow/sharing/ShareInFusionTest.kt
new file mode 100644
index 0000000..371d014
--- /dev/null
+++ b/kotlinx-coroutines-core/common/test/flow/sharing/ShareInFusionTest.kt
@@ -0,0 +1,56 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.flow
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.channels.*
+import kotlin.test.*
+
+class ShareInFusionTest : TestBase() {
+ /**
+ * Test perfect fusion for operators **after** [shareIn].
+ */
+ @Test
+ fun testOperatorFusion() = runTest {
+ val sh = emptyFlow<Int>().shareIn(this, SharingStarted.Eagerly)
+ assertTrue(sh !is MutableSharedFlow<*>) // cannot be cast to mutable shared flow!!!
+ assertSame(sh, (sh as Flow<*>).cancellable())
+ assertSame(sh, (sh as Flow<*>).flowOn(Dispatchers.Default))
+ assertSame(sh, sh.buffer(Channel.RENDEZVOUS))
+ coroutineContext.cancelChildren()
+ }
+
+ @Test
+ fun testFlowOnContextFusion() = runTest {
+ val flow = flow {
+ assertEquals("FlowCtx", currentCoroutineContext()[CoroutineName]?.name)
+ emit("OK")
+ }.flowOn(CoroutineName("FlowCtx"))
+ assertEquals("OK", flow.shareIn(this, SharingStarted.Eagerly, 1).first())
+ coroutineContext.cancelChildren()
+ }
+
+ /**
+ * Tests that `channelFlow { ... }.buffer(x)` works according to the [channelFlow] docs, and subsequent
+ * application of [shareIn] does not leak upstream.
+ */
+ @Test
+ fun testChannelFlowBufferShareIn() = runTest {
+ expect(1)
+ val flow = channelFlow {
+ // send a batch of 10 elements using [offer]
+ for (i in 1..10) {
+ assertTrue(offer(i)) // offer must succeed, because buffer
+ }
+ send(0) // done
+ }.buffer(10) // request a buffer of 10
+ // ^^^^^^^^^ buffer stays here
+ val shared = flow.shareIn(this, SharingStarted.Eagerly)
+ shared
+ .takeWhile { it > 0 }
+ .collect { i -> expect(i + 1) }
+ finish(12)
+ }
+}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/common/test/flow/sharing/ShareInTest.kt b/kotlinx-coroutines-core/common/test/flow/sharing/ShareInTest.kt
new file mode 100644
index 0000000..9020f5f
--- /dev/null
+++ b/kotlinx-coroutines-core/common/test/flow/sharing/ShareInTest.kt
@@ -0,0 +1,215 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.flow
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.channels.*
+import kotlin.test.*
+
+class ShareInTest : TestBase() {
+ @Test
+ fun testReplay0Eager() = runTest {
+ expect(1)
+ val flow = flowOf("OK")
+ val shared = flow.shareIn(this, SharingStarted.Eagerly)
+ yield() // actually start sharing
+ // all subscribers miss "OK"
+ val jobs = List(10) {
+ shared.onEach { expectUnreached() }.launchIn(this)
+ }
+ yield() // ensure nothing is collected
+ jobs.forEach { it.cancel() }
+ finish(2)
+ }
+
+ @Test
+ fun testReplay0Lazy() = testReplayZeroOrOne(0)
+
+ @Test
+ fun testReplay1Lazy() = testReplayZeroOrOne(1)
+
+ private fun testReplayZeroOrOne(replay: Int) = runTest {
+ expect(1)
+ val doneBarrier = Job()
+ val flow = flow {
+ expect(2)
+ emit("OK")
+ doneBarrier.join()
+ emit("DONE")
+ }
+ val sharingJob = Job()
+ val shared = flow.shareIn(this + sharingJob, started = SharingStarted.Lazily, replay = replay)
+ yield() // should not start sharing
+ // first subscriber gets "OK", other subscribers miss "OK"
+ val n = 10
+ val replayOfs = replay * (n - 1)
+ val subscriberJobs = List(n) { index ->
+ val subscribedBarrier = Job()
+ val job = shared
+ .onSubscription {
+ subscribedBarrier.complete()
+ }
+ .onEach { value ->
+ when (value) {
+ "OK" -> {
+ expect(3 + index)
+ if (replay == 0) { // only the first subscriber collects "OK" without replay
+ assertEquals(0, index)
+ }
+ }
+ "DONE" -> {
+ expect(4 + index + replayOfs)
+ }
+ else -> expectUnreached()
+ }
+ }
+ .takeWhile { it != "DONE" }
+ .launchIn(this)
+ subscribedBarrier.join() // wait until the launched job subscribed before launching the next one
+ job
+ }
+ doneBarrier.complete()
+ subscriberJobs.joinAll()
+ expect(4 + n + replayOfs)
+ sharingJob.cancel()
+ finish(5 + n + replayOfs)
+ }
+
+ @Test
+ fun testUpstreamCompleted() =
+ testUpstreamCompletedOrFailed(failed = false)
+
+ @Test
+ fun testUpstreamFailed() =
+ testUpstreamCompletedOrFailed(failed = true)
+
+ private fun testUpstreamCompletedOrFailed(failed: Boolean) = runTest {
+ val emitted = Job()
+ val terminate = Job()
+ val sharingJob = CompletableDeferred<Unit>()
+ val upstream = flow {
+ emit("OK")
+ emitted.complete()
+ terminate.join()
+ if (failed) throw TestException()
+ }
+ val shared = upstream.shareIn(this + sharingJob, SharingStarted.Eagerly, 1)
+ assertEquals(emptyList(), shared.replayCache)
+ emitted.join() // should start sharing, emit & cache
+ assertEquals(listOf("OK"), shared.replayCache)
+ terminate.complete()
+ sharingJob.complete(Unit)
+ sharingJob.join() // should complete sharing
+ assertEquals(listOf("OK"), shared.replayCache) // cache is still there
+ if (failed) {
+ assertTrue(sharingJob.getCompletionExceptionOrNull() is TestException)
+ } else {
+ assertNull(sharingJob.getCompletionExceptionOrNull())
+ }
+ }
+
+ @Test
+ fun testWhileSubscribedBasic() =
+ testWhileSubscribed(1, SharingStarted.WhileSubscribed())
+
+ @Test
+ fun testWhileSubscribedCustomAtLeast1() =
+ testWhileSubscribed(1, SharingStarted.WhileSubscribedAtLeast(1))
+
+ @Test
+ fun testWhileSubscribedCustomAtLeast2() =
+ testWhileSubscribed(2, SharingStarted.WhileSubscribedAtLeast(2))
+
+ @OptIn(ExperimentalStdlibApi::class)
+ private fun testWhileSubscribed(threshold: Int, started: SharingStarted) = runTest {
+ expect(1)
+ val flowState = FlowState()
+ val n = 3 // max number of subscribers
+ val log = Channel<String>(2 * n)
+
+ suspend fun checkStartTransition(subscribers: Int) {
+ when (subscribers) {
+ in 0 until threshold -> assertFalse(flowState.started)
+ threshold -> {
+ flowState.awaitStart() // must eventually start the flow
+ for (i in 1..threshold) {
+ assertEquals("sub$i: OK", log.receive()) // threshold subs must receive the values
+ }
+ }
+ in threshold + 1..n -> assertTrue(flowState.started)
+ }
+ }
+
+ suspend fun checkStopTransition(subscribers: Int) {
+ when (subscribers) {
+ in threshold + 1..n -> assertTrue(flowState.started)
+ threshold - 1 -> flowState.awaitStop() // upstream flow must be eventually stopped
+ in 0..threshold - 2 -> assertFalse(flowState.started) // should have stopped already
+ }
+ }
+
+ val flow = flow {
+ flowState.track {
+ emit("OK")
+ delay(Long.MAX_VALUE) // await forever, will get cancelled
+ }
+ }
+
+ val shared = flow.shareIn(this, started)
+ repeat(5) { // repeat scenario a few times
+ yield()
+ assertFalse(flowState.started) // flow is not running even if we yield
+ // start 3 subscribers
+ val subs = ArrayList<Job>()
+ for (i in 1..n) {
+ subs += shared
+ .onEach { value -> // only the first threshold subscribers get the value
+ when (i) {
+ in 1..threshold -> log.offer("sub$i: $value")
+ else -> expectUnreached()
+ }
+ }
+ .onCompletion { log.offer("sub$i: completion") }
+ .launchIn(this)
+ checkStartTransition(i)
+ }
+ // now cancel all subscribers
+ for (i in 1..n) {
+ subs.removeFirst().cancel() // cancel subscriber
+ assertEquals("sub$i: completion", log.receive()) // subscriber shall shutdown
+ checkStopTransition(n - i)
+ }
+ }
+ coroutineContext.cancelChildren() // cancel sharing job
+ finish(2)
+ }
+
+ @Suppress("TestFunctionName")
+ private fun SharingStarted.Companion.WhileSubscribedAtLeast(threshold: Int): SharingStarted =
+ object : SharingStarted {
+ override fun command(subscriptionCount: StateFlow<Int>): Flow<SharingCommand> =
+ subscriptionCount
+ .map { if (it >= threshold) SharingCommand.START else SharingCommand.STOP }
+ }
+
+ private class FlowState {
+ private val timeLimit = 10000L
+ private val _started = MutableStateFlow(false)
+ val started: Boolean get() = _started.value
+ fun start() = check(_started.compareAndSet(expect = false, update = true))
+ fun stop() = check(_started.compareAndSet(expect = true, update = false))
+ suspend fun awaitStart() = withTimeout(timeLimit) { _started.first { it } }
+ suspend fun awaitStop() = withTimeout(timeLimit) { _started.first { !it } }
+ }
+
+ private suspend fun FlowState.track(block: suspend () -> Unit) {
+ start()
+ try {
+ block()
+ } finally {
+ stop()
+ }
+ }
+}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/common/test/flow/sharing/SharedFlowScenarioTest.kt b/kotlinx-coroutines-core/common/test/flow/sharing/SharedFlowScenarioTest.kt
new file mode 100644
index 0000000..794553b
--- /dev/null
+++ b/kotlinx-coroutines-core/common/test/flow/sharing/SharedFlowScenarioTest.kt
@@ -0,0 +1,407 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.flow
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.channels.*
+import kotlin.coroutines.*
+import kotlin.test.*
+
+/**
+ * This test suit for [SharedFlow] has a dense framework that allows to test complex
+ * suspend/resume scenarios while keeping the code readable. Each test here is for
+ * one specific [SharedFlow] configuration, testing all the various corner cases in its
+ * behavior.
+ */
+class SharedFlowScenarioTest : TestBase() {
+ @Test
+ fun testReplay1Extra2() =
+ testSharedFlow(MutableSharedFlow<Int>(1, 2)) {
+ // total buffer size == 3
+ expectReplayOf()
+ emitRightNow(1); expectReplayOf(1)
+ emitRightNow(2); expectReplayOf(2)
+ emitRightNow(3); expectReplayOf(3)
+ emitRightNow(4); expectReplayOf(4) // no prob - no subscribers
+ val a = subscribe("a"); collect(a, 4)
+ emitRightNow(5); expectReplayOf(5)
+ emitRightNow(6); expectReplayOf(6)
+ emitRightNow(7); expectReplayOf(7)
+ // suspend/collect sequentially
+ val e8 = emitSuspends(8); collect(a, 5); emitResumes(e8); expectReplayOf(8)
+ val e9 = emitSuspends(9); collect(a, 6); emitResumes(e9); expectReplayOf(9)
+ // buffer full, but parallel emitters can still suspend (queue up)
+ val e10 = emitSuspends(10)
+ val e11 = emitSuspends(11)
+ val e12 = emitSuspends(12)
+ collect(a, 7); emitResumes(e10); expectReplayOf(10) // buffer 8, 9 | 10
+ collect(a, 8); emitResumes(e11); expectReplayOf(11) // buffer 9, 10 | 11
+ sharedFlow.resetReplayCache(); expectReplayOf() // 9, 10 11 | no replay
+ collect(a, 9); emitResumes(e12); expectReplayOf(12)
+ collect(a, 10, 11, 12); expectReplayOf(12) // buffer empty | 12
+ emitRightNow(13); expectReplayOf(13)
+ emitRightNow(14); expectReplayOf(14)
+ emitRightNow(15); expectReplayOf(15) // buffer 13, 14 | 15
+ val e16 = emitSuspends(16)
+ val e17 = emitSuspends(17)
+ val e18 = emitSuspends(18)
+ cancel(e17); expectReplayOf(15) // cancel in the middle of three emits; buffer 13, 14 | 15
+ collect(a, 13); emitResumes(e16); expectReplayOf(16) // buffer 14, 15, | 16
+ collect(a, 14); emitResumes(e18); expectReplayOf(18) // buffer 15, 16 | 18
+ val e19 = emitSuspends(19)
+ val e20 = emitSuspends(20)
+ val e21 = emitSuspends(21)
+ cancel(e21); expectReplayOf(18) // cancel last emit; buffer 15, 16, 18
+ collect(a, 15); emitResumes(e19); expectReplayOf(19) // buffer 16, 18 | 19
+ collect(a, 16); emitResumes(e20); expectReplayOf(20) // buffer 18, 19 | 20
+ collect(a, 18, 19, 20); expectReplayOf(20) // buffer empty | 20
+ emitRightNow(22); expectReplayOf(22)
+ emitRightNow(23); expectReplayOf(23)
+ emitRightNow(24); expectReplayOf(24) // buffer 22, 23 | 24
+ val e25 = emitSuspends(25)
+ val e26 = emitSuspends(26)
+ val e27 = emitSuspends(27)
+ cancel(e25); expectReplayOf(24) // cancel first emit, buffer 22, 23 | 24
+ sharedFlow.resetReplayCache(); expectReplayOf() // buffer 22, 23, 24 | no replay
+ val b = subscribe("b") // new subscriber
+ collect(a, 22); emitResumes(e26); expectReplayOf(26) // buffer 23, 24 | 26
+ collect(b, 26)
+ collect(a, 23); emitResumes(e27); expectReplayOf(27) // buffer 24, 26 | 27
+ collect(a, 24, 26, 27) // buffer empty | 27
+ emitRightNow(28); expectReplayOf(28)
+ emitRightNow(29); expectReplayOf(29) // buffer 27, 28 | 29
+ collect(a, 28, 29) // but b is slow
+ val e30 = emitSuspends(30)
+ val e31 = emitSuspends(31)
+ val e32 = emitSuspends(32)
+ val e33 = emitSuspends(33)
+ val e34 = emitSuspends(34)
+ val e35 = emitSuspends(35)
+ val e36 = emitSuspends(36)
+ val e37 = emitSuspends(37)
+ val e38 = emitSuspends(38)
+ val e39 = emitSuspends(39)
+ cancel(e31) // cancel emitter in queue
+ cancel(b) // cancel slow subscriber -> 3 emitters resume
+ emitResumes(e30); emitResumes(e32); emitResumes(e33); expectReplayOf(33) // buffer 30, 32 | 33
+ val c = subscribe("c"); collect(c, 33) // replays
+ cancel(e34)
+ collect(a, 30); emitResumes(e35); expectReplayOf(35) // buffer 32, 33 | 35
+ cancel(e37)
+ cancel(a); emitResumes(e36); emitResumes(e38); expectReplayOf(38) // buffer 35, 36 | 38
+ collect(c, 35); emitResumes(e39); expectReplayOf(39) // buffer 36, 38 | 39
+ collect(c, 36, 38, 39); expectReplayOf(39)
+ cancel(c); expectReplayOf(39) // replay stays
+ }
+
+ @Test
+ fun testReplay1() =
+ testSharedFlow(MutableSharedFlow<Int>(1)) {
+ emitRightNow(0); expectReplayOf(0)
+ emitRightNow(1); expectReplayOf(1)
+ emitRightNow(2); expectReplayOf(2)
+ sharedFlow.resetReplayCache(); expectReplayOf()
+ sharedFlow.resetReplayCache(); expectReplayOf()
+ emitRightNow(3); expectReplayOf(3)
+ emitRightNow(4); expectReplayOf(4)
+ val a = subscribe("a"); collect(a, 4)
+ emitRightNow(5); expectReplayOf(5); collect(a, 5)
+ emitRightNow(6)
+ sharedFlow.resetReplayCache(); expectReplayOf()
+ sharedFlow.resetReplayCache(); expectReplayOf()
+ val e7 = emitSuspends(7)
+ val e8 = emitSuspends(8)
+ val e9 = emitSuspends(9)
+ collect(a, 6); emitResumes(e7); expectReplayOf(7)
+ sharedFlow.resetReplayCache(); expectReplayOf()
+ sharedFlow.resetReplayCache(); expectReplayOf() // buffer 7 | -- no replay, but still buffered
+ val b = subscribe("b")
+ collect(a, 7); emitResumes(e8); expectReplayOf(8)
+ collect(b, 8) // buffer | 8 -- a is slow
+ val e10 = emitSuspends(10)
+ val e11 = emitSuspends(11)
+ val e12 = emitSuspends(12)
+ cancel(e9)
+ collect(a, 8); emitResumes(e10); expectReplayOf(10)
+ collect(a, 10) // now b's slow
+ cancel(e11)
+ collect(b, 10); emitResumes(e12); expectReplayOf(12)
+ collect(a, 12)
+ collect(b, 12)
+ sharedFlow.resetReplayCache(); expectReplayOf()
+ sharedFlow.resetReplayCache(); expectReplayOf() // nothing is buffered -- both collectors up to date
+ emitRightNow(13); expectReplayOf(13)
+ collect(b, 13) // a is slow
+ val e14 = emitSuspends(14)
+ val e15 = emitSuspends(15)
+ val e16 = emitSuspends(16)
+ cancel(e14)
+ cancel(a); emitResumes(e15); expectReplayOf(15) // cancelling slow subscriber
+ collect(b, 15); emitResumes(e16); expectReplayOf(16)
+ collect(b, 16)
+ }
+
+ @Test
+ fun testReplay2Extra2DropOldest() =
+ testSharedFlow<Int>(MutableSharedFlow(2, 2, BufferOverflow.DROP_OLDEST)) {
+ emitRightNow(0); expectReplayOf(0)
+ emitRightNow(1); expectReplayOf(0, 1)
+ emitRightNow(2); expectReplayOf(1, 2)
+ emitRightNow(3); expectReplayOf(2, 3)
+ emitRightNow(4); expectReplayOf(3, 4)
+ val a = subscribe("a")
+ collect(a, 3)
+ emitRightNow(5); expectReplayOf(4, 5)
+ emitRightNow(6); expectReplayOf(5, 6)
+ emitRightNow(7); expectReplayOf(6, 7) // buffer 4, 5 | 6, 7
+ emitRightNow(8); expectReplayOf(7, 8) // buffer 5, 6 | 7, 8
+ emitRightNow(9); expectReplayOf(8, 9) // buffer 6, 7 | 8, 9
+ collect(a, 6, 7)
+ val b = subscribe("b")
+ collect(b, 8, 9) // buffer | 8, 9
+ emitRightNow(10); expectReplayOf(9, 10) // buffer 8 | 9, 10
+ collect(a, 8, 9, 10) // buffer | 9, 10, note "b" had not collected 10 yet
+ emitRightNow(11); expectReplayOf(10, 11) // buffer | 10, 11
+ emitRightNow(12); expectReplayOf(11, 12) // buffer 10 | 11, 12
+ emitRightNow(13); expectReplayOf(12, 13) // buffer 10, 11 | 12, 13
+ emitRightNow(14); expectReplayOf(13, 14) // buffer 11, 12 | 13, 14, "b" missed 10
+ collect(b, 11, 12, 13, 14)
+ sharedFlow.resetReplayCache(); expectReplayOf() // buffer 11, 12, 13, 14 |
+ sharedFlow.resetReplayCache(); expectReplayOf()
+ collect(a, 11, 12, 13, 14)
+ emitRightNow(15); expectReplayOf(15)
+ collect(a, 15)
+ collect(b, 15)
+ }
+
+ @Test // https://github.com/Kotlin/kotlinx.coroutines/issues/2320
+ fun testResumeFastSubscriberOnResumedEmitter() =
+ testSharedFlow<Int>(MutableSharedFlow(1)) {
+ // create two subscribers and start collecting
+ val s1 = subscribe("s1"); resumeCollecting(s1)
+ val s2 = subscribe("s2"); resumeCollecting(s2)
+ // now emit 0, make sure it is collected
+ emitRightNow(0); expectReplayOf(0)
+ awaitCollected(s1, 0)
+ awaitCollected(s2, 0)
+ // now emit 1, and only first subscriber continues and collects it
+ emitRightNow(1); expectReplayOf(1)
+ collect(s1, 1)
+ // now emit 2, it suspend (s2 is blocking it)
+ val e2 = emitSuspends(2)
+ resumeCollecting(s1) // resume, but does not collect (e2 is still queued)
+ collect(s2, 1) // resume + collect next --> resumes emitter, thus resumes s1
+ awaitCollected(s1, 2) // <-- S1 collects value from the newly resumed emitter here !!!
+ emitResumes(e2); expectReplayOf(2)
+ // now emit 3, it suspends (s2 blocks it)
+ val e3 = emitSuspends(3)
+ collect(s2, 2)
+ emitResumes(e3); expectReplayOf(3)
+ }
+
+ @Test
+ fun testSuspendedConcurrentEmitAndCancelSubscriberReplay1() =
+ testSharedFlow<Int>(MutableSharedFlow(1)) {
+ val a = subscribe("a");
+ emitRightNow(0); expectReplayOf(0)
+ collect(a, 0)
+ emitRightNow(1); expectReplayOf(1)
+ val e2 = emitSuspends(2) // suspends until 1 is collected
+ val e3 = emitSuspends(3) // suspends until 1 is collected, too
+ cancel(a) // must resume emitters 2 & 3
+ emitResumes(e2)
+ emitResumes(e3)
+ expectReplayOf(3) // but replay size is 1 so only 3 should be kept
+ // Note: originally, SharedFlow was in a broken state here with 3 elements in the buffer
+ val b = subscribe("b")
+ collect(b, 3)
+ emitRightNow(4); expectReplayOf(4)
+ collect(b, 4)
+ }
+
+ @Test
+ fun testSuspendedConcurrentEmitAndCancelSubscriberReplay1ExtraBuffer1() =
+ testSharedFlow<Int>(MutableSharedFlow( replay = 1, extraBufferCapacity = 1)) {
+ val a = subscribe("a");
+ emitRightNow(0); expectReplayOf(0)
+ collect(a, 0)
+ emitRightNow(1); expectReplayOf(1)
+ emitRightNow(2); expectReplayOf(2)
+ val e3 = emitSuspends(3) // suspends until 1 is collected
+ val e4 = emitSuspends(4) // suspends until 1 is collected, too
+ val e5 = emitSuspends(5) // suspends until 1 is collected, too
+ cancel(a) // must resume emitters 3, 4, 5
+ emitResumes(e3)
+ emitResumes(e4)
+ emitResumes(e5)
+ expectReplayOf(5)
+ val b = subscribe("b")
+ collect(b, 5)
+ emitRightNow(6); expectReplayOf(6)
+ collect(b, 6)
+ }
+
+ private fun <T> testSharedFlow(
+ sharedFlow: MutableSharedFlow<T>,
+ scenario: suspend ScenarioDsl<T>.() -> Unit
+ ) = runTest {
+ var dsl: ScenarioDsl<T>? = null
+ try {
+ coroutineScope {
+ dsl = ScenarioDsl<T>(sharedFlow, coroutineContext)
+ dsl!!.scenario()
+ dsl!!.stop()
+ }
+ } catch (e: Throwable) {
+ dsl?.printLog()
+ throw e
+ }
+ }
+
+ private data class TestJob(val job: Job, val name: String) {
+ override fun toString(): String = name
+ }
+
+ private open class Action
+ private data class EmitResumes(val job: TestJob) : Action()
+ private data class Collected(val job: TestJob, val value: Any?) : Action()
+ private data class ResumeCollecting(val job: TestJob) : Action()
+ private data class Cancelled(val job: TestJob) : Action()
+
+ @OptIn(ExperimentalStdlibApi::class)
+ private class ScenarioDsl<T>(
+ val sharedFlow: MutableSharedFlow<T>,
+ coroutineContext: CoroutineContext
+ ) {
+ private val log = ArrayList<String>()
+ private val timeout = 10000L
+ private val scope = CoroutineScope(coroutineContext + Job())
+ private val actions = HashSet<Action>()
+ private val actionWaiters = ArrayDeque<Continuation<Unit>>()
+ private var expectedReplay = emptyList<T>()
+
+ private fun checkReplay() {
+ assertEquals(expectedReplay, sharedFlow.replayCache)
+ }
+
+ private fun wakeupWaiters() {
+ repeat(actionWaiters.size) {
+ actionWaiters.removeFirst().resume(Unit)
+ }
+ }
+
+ private fun addAction(action: Action) {
+ actions.add(action)
+ wakeupWaiters()
+ }
+
+ private suspend fun awaitAction(action: Action) {
+ withTimeoutOrNull(timeout) {
+ while (!actions.remove(action)) {
+ suspendCancellableCoroutine<Unit> { actionWaiters.add(it) }
+ }
+ } ?: error("Timed out waiting for action: $action")
+ wakeupWaiters()
+ }
+
+ private fun launchEmit(a: T): TestJob {
+ val name = "emit($a)"
+ val job = scope.launch(start = CoroutineStart.UNDISPATCHED) {
+ val job = TestJob(coroutineContext[Job]!!, name)
+ try {
+ log(name)
+ sharedFlow.emit(a)
+ log("$name resumes")
+ addAction(EmitResumes(job))
+ } catch(e: CancellationException) {
+ log("$name cancelled")
+ addAction(Cancelled(job))
+ }
+ }
+ return TestJob(job, name)
+ }
+
+ fun expectReplayOf(vararg a: T) {
+ expectedReplay = a.toList()
+ checkReplay()
+ }
+
+ fun emitRightNow(a: T) {
+ val job = launchEmit(a)
+ assertTrue(actions.remove(EmitResumes(job)))
+ }
+
+ fun emitSuspends(a: T): TestJob {
+ val job = launchEmit(a)
+ assertFalse(EmitResumes(job) in actions)
+ checkReplay()
+ return job
+ }
+
+ suspend fun emitResumes(job: TestJob) {
+ awaitAction(EmitResumes(job))
+ }
+
+ suspend fun cancel(job: TestJob) {
+ log("cancel(${job.name})")
+ job.job.cancel()
+ awaitAction(Cancelled(job))
+ }
+
+ fun subscribe(id: String): TestJob {
+ val name = "collect($id)"
+ val job = scope.launch(start = CoroutineStart.UNDISPATCHED) {
+ val job = TestJob(coroutineContext[Job]!!, name)
+ try {
+ awaitAction(ResumeCollecting(job))
+ log("$name start")
+ sharedFlow.collect { value ->
+ log("$name -> $value")
+ addAction(Collected(job, value))
+ awaitAction(ResumeCollecting(job))
+ log("$name -> $value resumes")
+ }
+ error("$name completed")
+ } catch(e: CancellationException) {
+ log("$name cancelled")
+ addAction(Cancelled(job))
+ }
+ }
+ return TestJob(job, name)
+ }
+
+ // collect ~== resumeCollecting + awaitCollected (for each value)
+ suspend fun collect(job: TestJob, vararg a: T) {
+ for (value in a) {
+ checkReplay() // should not have changed
+ resumeCollecting(job)
+ awaitCollected(job, value)
+ }
+ }
+
+ suspend fun resumeCollecting(job: TestJob) {
+ addAction(ResumeCollecting(job))
+ }
+
+ suspend fun awaitCollected(job: TestJob, value: T) {
+ awaitAction(Collected(job, value))
+ }
+
+ fun stop() {
+ log("--- stop")
+ scope.cancel()
+ }
+
+ private fun log(text: String) {
+ log.add(text)
+ }
+
+ fun printLog() {
+ println("--- The most recent log entries ---")
+ log.takeLast(30).forEach(::println)
+ println("--- That's it ---")
+ }
+ }
+}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/common/test/flow/sharing/SharedFlowTest.kt b/kotlinx-coroutines-core/common/test/flow/sharing/SharedFlowTest.kt
new file mode 100644
index 0000000..32d88f3
--- /dev/null
+++ b/kotlinx-coroutines-core/common/test/flow/sharing/SharedFlowTest.kt
@@ -0,0 +1,798 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.flow
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.channels.*
+import kotlin.random.*
+import kotlin.test.*
+
+/**
+ * This test suite contains some basic tests for [SharedFlow]. There are some scenarios here written
+ * using [expect] and they are not very readable. See [SharedFlowScenarioTest] for a better
+ * behavioral test-suit.
+ */
+class SharedFlowTest : TestBase() {
+ @Test
+ fun testRendezvousSharedFlowBasic() = runTest {
+ expect(1)
+ val sh = MutableSharedFlow<Int?>()
+ assertTrue(sh.replayCache.isEmpty())
+ assertEquals(0, sh.subscriptionCount.value)
+ sh.emit(1) // no suspend
+ assertTrue(sh.replayCache.isEmpty())
+ assertEquals(0, sh.subscriptionCount.value)
+ expect(2)
+ // one collector
+ val job1 = launch(start = CoroutineStart.UNDISPATCHED) {
+ expect(3)
+ sh.collect {
+ when(it) {
+ 4 -> expect(5)
+ 6 -> expect(7)
+ 10 -> expect(11)
+ 13 -> expect(14)
+ else -> expectUnreached()
+ }
+ }
+ expectUnreached() // does not complete normally
+ }
+ expect(4)
+ assertEquals(1, sh.subscriptionCount.value)
+ sh.emit(4)
+ assertTrue(sh.replayCache.isEmpty())
+ expect(6)
+ sh.emit(6)
+ expect(8)
+ // one more collector
+ val job2 = launch(start = CoroutineStart.UNDISPATCHED) {
+ expect(9)
+ sh.collect {
+ when(it) {
+ 10 -> expect(12)
+ 13 -> expect(15)
+ 17 -> expect(18)
+ null -> expect(20)
+ 21 -> expect(22)
+ else -> expectUnreached()
+ }
+ }
+ expectUnreached() // does not complete normally
+ }
+ expect(10)
+ assertEquals(2, sh.subscriptionCount.value)
+ sh.emit(10) // to both collectors now!
+ assertTrue(sh.replayCache.isEmpty())
+ expect(13)
+ sh.emit(13)
+ expect(16)
+ job1.cancel() // cancel the first collector
+ yield()
+ assertEquals(1, sh.subscriptionCount.value)
+ expect(17)
+ sh.emit(17) // only to second collector
+ expect(19)
+ sh.emit(null) // emit null to the second collector
+ expect(21)
+ sh.emit(21) // non-null again
+ expect(23)
+ job2.cancel() // cancel the second collector
+ yield()
+ assertEquals(0, sh.subscriptionCount.value)
+ expect(24)
+ sh.emit(24) // does not go anywhere
+ assertEquals(0, sh.subscriptionCount.value)
+ assertTrue(sh.replayCache.isEmpty())
+ finish(25)
+ }
+
+ @Test
+ fun testRendezvousSharedFlowReset() = runTest {
+ expect(1)
+ val sh = MutableSharedFlow<Int>()
+ val barrier = Channel<Unit>(1)
+ val job = launch(start = CoroutineStart.UNDISPATCHED) {
+ expect(2)
+ sh.collect {
+ when (it) {
+ 3 -> {
+ expect(4)
+ barrier.receive() // hold on before collecting next one
+ }
+ 6 -> expect(10)
+ else -> expectUnreached()
+ }
+ }
+ expectUnreached() // does not complete normally
+ }
+ expect(3)
+ sh.emit(3) // rendezvous
+ expect(5)
+ assertFalse(sh.tryEmit(5)) // collector is not ready now
+ launch(start = CoroutineStart.UNDISPATCHED) {
+ expect(6)
+ sh.emit(6) // suspends
+ expect(12)
+ }
+ expect(7)
+ yield() // no wakeup -> all suspended
+ expect(8)
+ // now reset cache -> nothing happens, there is no cache
+ sh.resetReplayCache()
+ yield()
+ expect(9)
+ // now resume collector
+ barrier.send(Unit)
+ yield() // to collector
+ expect(11)
+ yield() // to emitter
+ expect(13)
+ assertFalse(sh.tryEmit(13)) // rendezvous does not work this way
+ job.cancel()
+ finish(14)
+ }
+
+ @Test
+ fun testReplay1SharedFlowBasic() = runTest {
+ expect(1)
+ val sh = MutableSharedFlow<Int?>(1)
+ assertTrue(sh.replayCache.isEmpty())
+ assertEquals(0, sh.subscriptionCount.value)
+ sh.emit(1) // no suspend
+ assertEquals(listOf(1), sh.replayCache)
+ assertEquals(0, sh.subscriptionCount.value)
+ expect(2)
+ sh.emit(2) // no suspend
+ assertEquals(listOf(2), sh.replayCache)
+ expect(3)
+ // one collector
+ val job1 = launch(start = CoroutineStart.UNDISPATCHED) {
+ expect(4)
+ sh.collect {
+ when(it) {
+ 2 -> expect(5) // got it immediately from replay cache
+ 6 -> expect(8)
+ null -> expect(14)
+ 17 -> expect(18)
+ else -> expectUnreached()
+ }
+ }
+ expectUnreached() // does not complete normally
+ }
+ expect(6)
+ assertEquals(1, sh.subscriptionCount.value)
+ sh.emit(6) // does not suspend, but buffers
+ assertEquals(listOf(6), sh.replayCache)
+ expect(7)
+ yield()
+ expect(9)
+ // one more collector
+ val job2 = launch(start = CoroutineStart.UNDISPATCHED) {
+ expect(10)
+ sh.collect {
+ when(it) {
+ 6 -> expect(11) // from replay cache
+ null -> expect(15)
+ else -> expectUnreached()
+ }
+ }
+ expectUnreached() // does not complete normally
+ }
+ expect(12)
+ assertEquals(2, sh.subscriptionCount.value)
+ sh.emit(null)
+ expect(13)
+ assertEquals(listOf(null), sh.replayCache)
+ yield()
+ assertEquals(listOf(null), sh.replayCache)
+ expect(16)
+ job2.cancel()
+ yield()
+ assertEquals(1, sh.subscriptionCount.value)
+ expect(17)
+ sh.emit(17)
+ assertEquals(listOf(17), sh.replayCache)
+ yield()
+ expect(19)
+ job1.cancel()
+ yield()
+ assertEquals(0, sh.subscriptionCount.value)
+ assertEquals(listOf(17), sh.replayCache)
+ finish(20)
+ }
+
+ @Test
+ fun testReplay1() = runTest {
+ expect(1)
+ val sh = MutableSharedFlow<Int>(1)
+ assertEquals(listOf(), sh.replayCache)
+ val barrier = Channel<Unit>(1)
+ val job = launch(start = CoroutineStart.UNDISPATCHED) {
+ expect(2)
+ sh.collect {
+ when (it) {
+ 3 -> {
+ expect(4)
+ barrier.receive() // collector waits
+ }
+ 5 -> expect(10)
+ 6 -> expect(11)
+ else -> expectUnreached()
+ }
+ }
+ expectUnreached() // does not complete normally
+ }
+ expect(3)
+ assertTrue(sh.tryEmit(3)) // buffered
+ assertEquals(listOf(3), sh.replayCache)
+ yield() // to collector
+ expect(5)
+ assertTrue(sh.tryEmit(5)) // buffered
+ assertEquals(listOf(5), sh.replayCache)
+ launch(start = CoroutineStart.UNDISPATCHED) {
+ expect(6)
+ sh.emit(6) // buffer full, suspended
+ expect(13)
+ }
+ expect(7)
+ assertEquals(listOf(5), sh.replayCache)
+ sh.resetReplayCache() // clear cache
+ assertEquals(listOf(), sh.replayCache)
+ expect(8)
+ yield() // emitter still suspended
+ expect(9)
+ assertEquals(listOf(), sh.replayCache)
+ assertFalse(sh.tryEmit(10)) // still no buffer space
+ assertEquals(listOf(), sh.replayCache)
+ barrier.send(Unit) // resume collector
+ yield() // to collector
+ expect(12)
+ yield() // to emitter, that should have resumed
+ expect(14)
+ job.cancel()
+ assertEquals(listOf(6), sh.replayCache)
+ finish(15)
+ }
+
+ @Test
+ fun testReplay2Extra1() = runTest {
+ expect(1)
+ val sh = MutableSharedFlow<Int>(
+ replay = 2,
+ extraBufferCapacity = 1
+ )
+ assertEquals(listOf(), sh.replayCache)
+ assertTrue(sh.tryEmit(0))
+ assertEquals(listOf(0), sh.replayCache)
+ val job = launch(start = CoroutineStart.UNDISPATCHED) {
+ expect(2)
+ var cnt = 0
+ sh.collect {
+ when (it) {
+ 0 -> when (cnt++) {
+ 0 -> expect(3)
+ 1 -> expect(14)
+ else -> expectUnreached()
+ }
+ 1 -> expect(6)
+ 2 -> expect(7)
+ 3 -> expect(8)
+ 4 -> expect(12)
+ 5 -> expect(13)
+ 16 -> expect(17)
+ else -> expectUnreached()
+ }
+ }
+ expectUnreached() // does not complete normally
+ }
+ expect(4)
+ assertTrue(sh.tryEmit(1)) // buffered
+ assertEquals(listOf(0, 1), sh.replayCache)
+ assertTrue(sh.tryEmit(2)) // buffered
+ assertEquals(listOf(1, 2), sh.replayCache)
+ assertTrue(sh.tryEmit(3)) // buffered (buffer size is 3)
+ assertEquals(listOf(2, 3), sh.replayCache)
+ expect(5)
+ yield() // to collector
+ expect(9)
+ assertEquals(listOf(2, 3), sh.replayCache)
+ assertTrue(sh.tryEmit(4)) // can buffer now
+ assertEquals(listOf(3, 4), sh.replayCache)
+ assertTrue(sh.tryEmit(5)) // can buffer now
+ assertEquals(listOf(4, 5), sh.replayCache)
+ assertTrue(sh.tryEmit(0)) // can buffer one more, let it be zero again
+ assertEquals(listOf(5, 0), sh.replayCache)
+ expect(10)
+ assertFalse(sh.tryEmit(10)) // cannot buffer anymore!
+ sh.resetReplayCache() // replay cache
+ assertEquals(listOf(), sh.replayCache) // empty
+ assertFalse(sh.tryEmit(0)) // still cannot buffer anymore (reset does not help)
+ assertEquals(listOf(), sh.replayCache) // empty
+ expect(11)
+ yield() // resume collector, will get next values
+ expect(15)
+ sh.resetReplayCache() // reset again, nothing happens
+ assertEquals(listOf(), sh.replayCache) // empty
+ yield() // collector gets nothing -- no change
+ expect(16)
+ assertTrue(sh.tryEmit(16))
+ assertEquals(listOf(16), sh.replayCache)
+ yield() // gets it
+ expect(18)
+ job.cancel()
+ finish(19)
+ }
+
+ @Test
+ fun testBufferNoReplayCancelWhileBuffering() = runTest {
+ val n = 123
+ val sh = MutableSharedFlow<Int>(replay = 0, extraBufferCapacity = n)
+ repeat(3) {
+ val m = n / 2 // collect half, then suspend
+ val barrier = Channel<Int>(1)
+ val collectorJob = sh
+ .onSubscription {
+ barrier.send(1)
+ }
+ .onEach { value ->
+ if (value == m) {
+ barrier.send(2)
+ delay(Long.MAX_VALUE)
+ }
+ }
+ .launchIn(this)
+ assertEquals(1, barrier.receive()) // make sure it subscribes
+ launch(start = CoroutineStart.UNDISPATCHED) {
+ for (i in 0 until n + m) sh.emit(i) // these emits should go Ok
+ barrier.send(3)
+ sh.emit(n + 4) // this emit will suspend on buffer overflow
+ barrier.send(4)
+ }
+ assertEquals(2, barrier.receive()) // wait until m collected
+ assertEquals(3, barrier.receive()) // wait until all are emitted
+ collectorJob.cancel() // cancelling collector job must clear buffer and resume emitter
+ assertEquals(4, barrier.receive()) // verify that emitter resumes
+ }
+ }
+
+ @Test
+ fun testRepeatedResetWithReplay() = runTest {
+ val n = 10
+ val sh = MutableSharedFlow<Int>(n)
+ var i = 0
+ repeat(3) {
+ // collector is slow
+ val collector = sh.onEach { delay(Long.MAX_VALUE) }.launchIn(this)
+ val emitter = launch {
+ repeat(3 * n) { sh.emit(i); i++ }
+ }
+ repeat(3) { yield() } // enough to run it to suspension
+ assertEquals((i - n until i).toList(), sh.replayCache)
+ sh.resetReplayCache()
+ assertEquals(emptyList(), sh.replayCache)
+ repeat(3) { yield() } // enough to run it to suspension
+ assertEquals(emptyList(), sh.replayCache) // still blocked
+ collector.cancel()
+ emitter.cancel()
+ repeat(3) { yield() } // enough to run it to suspension
+ }
+ }
+
+ @Test
+ fun testSynchronousSharedFlowEmitterCancel() = runTest {
+ expect(1)
+ val sh = MutableSharedFlow<Int>()
+ val barrier1 = Job()
+ val barrier2 = Job()
+ val barrier3 = Job()
+ val collector1 = sh.onEach {
+ when (it) {
+ 1 -> expect(3)
+ 2 -> {
+ expect(6)
+ barrier2.complete()
+ }
+ 3 -> {
+ expect(9)
+ barrier3.complete()
+ }
+ else -> expectUnreached()
+ }
+ }.launchIn(this)
+ val collector2 = sh.onEach {
+ when (it) {
+ 1 -> {
+ expect(4)
+ barrier1.complete()
+ delay(Long.MAX_VALUE)
+ }
+ else -> expectUnreached()
+ }
+ }.launchIn(this)
+ repeat(2) { yield() } // launch both subscribers
+ val emitter = launch(start = CoroutineStart.UNDISPATCHED) {
+ expect(2)
+ sh.emit(1)
+ barrier1.join()
+ expect(5)
+ sh.emit(2) // suspends because of slow collector2
+ expectUnreached() // will be cancelled
+ }
+ barrier2.join() // wait
+ expect(7)
+ // Now cancel the emitter!
+ emitter.cancel()
+ yield()
+ // Cancel slow collector
+ collector2.cancel()
+ yield()
+ // emit to fast collector1
+ expect(8)
+ sh.emit(3)
+ barrier3.join()
+ expect(10)
+ // cancel it, too
+ collector1.cancel()
+ finish(11)
+ }
+
+ @Test
+ fun testDifferentBufferedFlowCapacities() {
+ for (replay in 0..10) {
+ for (extraBufferCapacity in 0..5) {
+ if (replay == 0 && extraBufferCapacity == 0) continue // test only buffered shared flows
+ try {
+ val sh = MutableSharedFlow<Int>(replay, extraBufferCapacity)
+ // repeat the whole test a few times to make sure it works correctly when slots are reused
+ repeat(3) {
+ testBufferedFlow(sh, replay)
+ }
+ } catch (e: Throwable) {
+ error("Failed for replay=$replay, extraBufferCapacity=$extraBufferCapacity", e)
+ }
+ }
+ }
+ }
+
+ private fun testBufferedFlow(sh: MutableSharedFlow<Int>, replay: Int) = runTest {
+ reset()
+ expect(1)
+ val n = 100 // initially emitted to fill buffer
+ for (i in 1..n) assertTrue(sh.tryEmit(i))
+ // initial expected replayCache
+ val rcStart = n - replay + 1
+ val rcRange = rcStart..n
+ val rcSize = n - rcStart + 1
+ assertEquals(rcRange.toList(), sh.replayCache)
+ // create collectors
+ val m = 10 // collectors created
+ var ofs = 0
+ val k = 42 // emissions to collectors
+ val ecRange = n + 1..n + k
+ val jobs = List(m) { jobIndex ->
+ launch(start = CoroutineStart.UNDISPATCHED) {
+ sh.collect { i ->
+ when (i) {
+ in rcRange -> expect(2 + i - rcStart + jobIndex * rcSize)
+ in ecRange -> expect(2 + ofs + jobIndex)
+ else -> expectUnreached()
+ }
+ }
+ expectUnreached() // does not complete normally
+ }
+ }
+ ofs = rcSize * m + 2
+ expect(ofs)
+ // emit to all k times
+ for (p in ecRange) {
+ sh.emit(p)
+ expect(1 + ofs) // buffered, no suspend
+ yield()
+ ofs += 2 + m
+ expect(ofs)
+ }
+ assertEquals(ecRange.toList().takeLast(replay), sh.replayCache)
+ // cancel all collectors
+ jobs.forEach { it.cancel() }
+ yield()
+ // replay cache is still there
+ assertEquals(ecRange.toList().takeLast(replay), sh.replayCache)
+ finish(1 + ofs)
+ }
+
+ @Test
+ fun testDropLatest() = testDropLatestOrOldest(BufferOverflow.DROP_LATEST)
+
+ @Test
+ fun testDropOldest() = testDropLatestOrOldest(BufferOverflow.DROP_OLDEST)
+
+ private fun testDropLatestOrOldest(bufferOverflow: BufferOverflow) = runTest {
+ reset()
+ expect(1)
+ val sh = MutableSharedFlow<Int?>(1, onBufferOverflow = bufferOverflow)
+ sh.emit(1)
+ sh.emit(2)
+ // always keeps last w/o collectors
+ assertEquals(listOf(2), sh.replayCache)
+ assertEquals(0, sh.subscriptionCount.value)
+ // one collector
+ val valueAfterOverflow = when (bufferOverflow) {
+ BufferOverflow.DROP_OLDEST -> 5
+ BufferOverflow.DROP_LATEST -> 4
+ else -> error("not supported in this test: $bufferOverflow")
+ }
+ val job = launch(start = CoroutineStart.UNDISPATCHED) {
+ expect(2)
+ sh.collect {
+ when(it) {
+ 2 -> { // replayed
+ expect(3)
+ yield() // and suspends, busy waiting
+ }
+ valueAfterOverflow -> expect(7)
+ 8 -> expect(9)
+ else -> expectUnreached()
+ }
+ }
+ expectUnreached() // does not complete normally
+ }
+ expect(4)
+ assertEquals(1, sh.subscriptionCount.value)
+ assertEquals(listOf(2), sh.replayCache)
+ sh.emit(4) // buffering, collector is busy
+ assertEquals(listOf(4), sh.replayCache)
+ expect(5)
+ sh.emit(5) // Buffer overflow here, will not suspend
+ assertEquals(listOf(valueAfterOverflow), sh.replayCache)
+ expect(6)
+ yield() // to the job
+ expect(8)
+ sh.emit(8) // not busy now
+ assertEquals(listOf(8), sh.replayCache) // buffered
+ yield() // to process
+ expect(10)
+ job.cancel() // cancel the job
+ yield()
+ assertEquals(0, sh.subscriptionCount.value)
+ finish(11)
+ }
+
+ @Test
+ public fun testOnSubscription() = runTest {
+ expect(1)
+ val sh = MutableSharedFlow<String>()
+ fun share(s: String) { launch(start = CoroutineStart.UNDISPATCHED) { sh.emit(s) } }
+ sh
+ .onSubscription {
+ emit("collector->A")
+ share("share->A")
+ }
+ .onSubscription {
+ emit("collector->B")
+ share("share->B")
+ }
+ .onStart {
+ emit("collector->C")
+ share("share->C") // get's lost, no subscribers yet
+ }
+ .onStart {
+ emit("collector->D")
+ share("share->D") // get's lost, no subscribers yet
+ }
+ .onEach {
+ when (it) {
+ "collector->D" -> expect(2)
+ "collector->C" -> expect(3)
+ "collector->A" -> expect(4)
+ "collector->B" -> expect(5)
+ "share->A" -> expect(6)
+ "share->B" -> {
+ expect(7)
+ currentCoroutineContext().cancel()
+ }
+ else -> expectUnreached()
+ }
+ }
+ .launchIn(this)
+ .join()
+ finish(8)
+ }
+
+ @Test
+ fun onSubscriptionThrows() = runTest {
+ expect(1)
+ val sh = MutableSharedFlow<String>(1)
+ sh.tryEmit("OK") // buffer a string
+ assertEquals(listOf("OK"), sh.replayCache)
+ sh
+ .onSubscription {
+ expect(2)
+ throw TestException()
+ }
+ .catch { e ->
+ assertTrue(e is TestException)
+ expect(3)
+ }
+ .collect {
+ // onSubscription throw before replay is emitted, so no value is collected if it throws
+ expectUnreached()
+ }
+ assertEquals(0, sh.subscriptionCount.value)
+ finish(4)
+ }
+
+ @Test
+ fun testBigReplayManySubscribers() = testManySubscribers(true)
+
+ @Test
+ fun testBigBufferManySubscribers() = testManySubscribers(false)
+
+ private fun testManySubscribers(replay: Boolean) = runTest {
+ val n = 100
+ val rnd = Random(replay.hashCode())
+ val sh = MutableSharedFlow<Int>(
+ replay = if (replay) n else 0,
+ extraBufferCapacity = if (replay) 0 else n
+ )
+ val subs = ArrayList<SubJob>()
+ for (i in 1..n) {
+ sh.emit(i)
+ val subBarrier = Channel<Unit>()
+ val subJob = SubJob()
+ subs += subJob
+ // will receive all starting from replay or from new emissions only
+ subJob.lastReceived = if (replay) 0 else i
+ subJob.job = sh
+ .onSubscription {
+ subBarrier.send(Unit) // signal subscribed
+ }
+ .onEach { value ->
+ assertEquals(subJob.lastReceived + 1, value)
+ subJob.lastReceived = value
+ }
+ .launchIn(this)
+ subBarrier.receive() // wait until subscribed
+ // must have also receive all from the replay buffer directly after being subscribed
+ assertEquals(subJob.lastReceived, i)
+ // 50% of time cancel one subscriber
+ if (i % 2 == 0) {
+ val victim = subs.removeAt(rnd.nextInt(subs.size))
+ yield() // make sure victim processed all emissions
+ assertEquals(victim.lastReceived, i)
+ victim.job.cancel()
+ }
+ }
+ yield() // make sure the last emission is processed
+ for (subJob in subs) {
+ assertEquals(subJob.lastReceived, n)
+ subJob.job.cancel()
+ }
+ }
+
+ private class SubJob {
+ lateinit var job: Job
+ var lastReceived = 0
+ }
+
+ @Test
+ fun testStateFlowModel() = runTest {
+ val stateFlow = MutableStateFlow<Data?>(null)
+ val expect = modelLog(stateFlow)
+ val sharedFlow = MutableSharedFlow<Data?>(
+ replay = 1,
+ onBufferOverflow = BufferOverflow.DROP_OLDEST
+ )
+ sharedFlow.tryEmit(null) // initial value
+ val actual = modelLog(sharedFlow) { distinctUntilChanged() }
+ for (i in 0 until minOf(expect.size, actual.size)) {
+ if (actual[i] != expect[i]) {
+ for (j in maxOf(0, i - 10)..i) println("Actual log item #$j: ${actual[j]}")
+ assertEquals(expect[i], actual[i], "Log item #$i")
+ }
+ }
+ assertEquals(expect.size, actual.size)
+ }
+
+ private suspend fun modelLog(
+ sh: MutableSharedFlow<Data?>,
+ op: Flow<Data?>.() -> Flow<Data?> = { this }
+ ): List<String> = coroutineScope {
+ val rnd = Random(1)
+ val result = ArrayList<String>()
+ val job = launch {
+ sh.op().collect { value ->
+ result.add("Collect: $value")
+ repeat(rnd.nextInt(0..2)) {
+ result.add("Collect: yield")
+ yield()
+ }
+ }
+ }
+ repeat(1000) {
+ val value = if (rnd.nextBoolean()) null else rnd.nextData()
+ if (rnd.nextInt(20) == 0) {
+ result.add("resetReplayCache & emit: $value")
+ if (sh !is StateFlow<*>) sh.resetReplayCache()
+ assertTrue(sh.tryEmit(value))
+ } else {
+ result.add("Emit: $value")
+ sh.emit(value)
+ }
+ repeat(rnd.nextInt(0..2)) {
+ result.add("Emit: yield")
+ yield()
+ }
+ }
+ result.add("main: cancel")
+ job.cancel()
+ result.add("main: yield")
+ yield()
+ result.add("main: join")
+ job.join()
+ result
+ }
+
+ data class Data(val x: Int)
+ private val dataCache = (1..5).associateWith { Data(it) }
+
+ // Note that we test proper null support here, too
+ private fun Random.nextData(): Data? {
+ val x = nextInt(0..5)
+ if (x == 0) return null
+ // randomly reuse ref or create a new instance
+ return if(nextBoolean()) dataCache[x] else Data(x)
+ }
+
+ @Test
+ fun testOperatorFusion() {
+ val sh = MutableSharedFlow<String>()
+ assertSame(sh, (sh as Flow<*>).cancellable())
+ assertSame(sh, (sh as Flow<*>).flowOn(Dispatchers.Default))
+ assertSame(sh, sh.buffer(Channel.RENDEZVOUS))
+ }
+
+ @Test
+ fun testIllegalArgumentException() {
+ assertFailsWith<IllegalArgumentException> { MutableSharedFlow<Int>(-1) }
+ assertFailsWith<IllegalArgumentException> { MutableSharedFlow<Int>(0, extraBufferCapacity = -1) }
+ assertFailsWith<IllegalArgumentException> { MutableSharedFlow<Int>(0, onBufferOverflow = BufferOverflow.DROP_LATEST) }
+ assertFailsWith<IllegalArgumentException> { MutableSharedFlow<Int>(0, onBufferOverflow = BufferOverflow.DROP_OLDEST) }
+ }
+
+ @Test
+ public fun testReplayCancellability() = testCancellability(fromReplay = true)
+
+ @Test
+ public fun testEmitCancellability() = testCancellability(fromReplay = false)
+
+ private fun testCancellability(fromReplay: Boolean) = runTest {
+ expect(1)
+ val sh = MutableSharedFlow<Int>(5)
+ fun emitTestData() {
+ for (i in 1..5) assertTrue(sh.tryEmit(i))
+ }
+ if (fromReplay) emitTestData() // fill in replay first
+ var subscribed = true
+ val job = sh
+ .onSubscription { subscribed = true }
+ .onEach { i ->
+ when (i) {
+ 1 -> expect(2)
+ 2 -> expect(3)
+ 3 -> {
+ expect(4)
+ currentCoroutineContext().cancel()
+ }
+ else -> expectUnreached() // shall check for cancellation
+ }
+ }
+ .launchIn(this)
+ yield()
+ assertTrue(subscribed) // yielding in enough
+ if (!fromReplay) emitTestData() // emit after subscription
+ job.join()
+ finish(5)
+ }
+}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/common/test/flow/sharing/SharingStartedTest.kt b/kotlinx-coroutines-core/common/test/flow/sharing/SharingStartedTest.kt
new file mode 100644
index 0000000..496fb7f
--- /dev/null
+++ b/kotlinx-coroutines-core/common/test/flow/sharing/SharingStartedTest.kt
@@ -0,0 +1,183 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.flow
+
+import kotlinx.coroutines.*
+import kotlin.coroutines.*
+import kotlin.test.*
+
+/**
+ * Functional tests for [SharingStarted] using [withVirtualTime] and a DSL to describe
+ * testing scenarios and expected behavior for different implementations.
+ */
+class SharingStartedTest : TestBase() {
+ @Test
+ fun testEagerly() =
+ testSharingStarted(SharingStarted.Eagerly, SharingCommand.START) {
+ subscriptions(1)
+ rampUpAndDown()
+ subscriptions(0)
+ delay(100)
+ }
+
+ @Test
+ fun testLazily() =
+ testSharingStarted(SharingStarted.Lazily) {
+ subscriptions(1, SharingCommand.START)
+ rampUpAndDown()
+ subscriptions(0)
+ }
+
+ @Test
+ fun testWhileSubscribed() =
+ testSharingStarted(SharingStarted.WhileSubscribed()) {
+ subscriptions(1, SharingCommand.START)
+ rampUpAndDown()
+ subscriptions(0, SharingCommand.STOP)
+ delay(100)
+ }
+
+ @Test
+ fun testWhileSubscribedExpireImmediately() =
+ testSharingStarted(SharingStarted.WhileSubscribed(replayExpirationMillis = 0)) {
+ subscriptions(1, SharingCommand.START)
+ rampUpAndDown()
+ subscriptions(0, SharingCommand.STOP_AND_RESET_REPLAY_CACHE)
+ delay(100)
+ }
+
+ @Test
+ fun testWhileSubscribedWithTimeout() =
+ testSharingStarted(SharingStarted.WhileSubscribed(stopTimeoutMillis = 100)) {
+ subscriptions(1, SharingCommand.START)
+ rampUpAndDown()
+ subscriptions(0)
+ delay(50) // don't give it time to stop
+ subscriptions(1) // resubscribe again
+ rampUpAndDown()
+ subscriptions(0)
+ afterTime(100, SharingCommand.STOP)
+ delay(100)
+ }
+
+ @Test
+ fun testWhileSubscribedExpiration() =
+ testSharingStarted(SharingStarted.WhileSubscribed(replayExpirationMillis = 200)) {
+ subscriptions(1, SharingCommand.START)
+ rampUpAndDown()
+ subscriptions(0, SharingCommand.STOP)
+ delay(150) // don't give it time to reset cache
+ subscriptions(1, SharingCommand.START)
+ rampUpAndDown()
+ subscriptions(0, SharingCommand.STOP)
+ afterTime(200, SharingCommand.STOP_AND_RESET_REPLAY_CACHE)
+ }
+
+ @Test
+ fun testWhileSubscribedStopAndExpiration() =
+ testSharingStarted(SharingStarted.WhileSubscribed(stopTimeoutMillis = 400, replayExpirationMillis = 300)) {
+ subscriptions(1, SharingCommand.START)
+ rampUpAndDown()
+ subscriptions(0)
+ delay(350) // don't give it time to stop
+ subscriptions(1)
+ rampUpAndDown()
+ subscriptions(0)
+ afterTime(400, SharingCommand.STOP)
+ delay(250) // don't give it time to reset cache
+ subscriptions(1, SharingCommand.START)
+ rampUpAndDown()
+ subscriptions(0)
+ afterTime(400, SharingCommand.STOP)
+ afterTime(300, SharingCommand.STOP_AND_RESET_REPLAY_CACHE)
+ delay(100)
+ }
+
+ private suspend fun SharingStartedDsl.rampUpAndDown() {
+ for (i in 2..10) {
+ delay(100)
+ subscriptions(i)
+ }
+ delay(1000)
+ for (i in 9 downTo 1) {
+ subscriptions(i)
+ delay(100)
+ }
+ }
+
+ private fun testSharingStarted(
+ started: SharingStarted,
+ initialCommand: SharingCommand? = null,
+ scenario: suspend SharingStartedDsl.() -> Unit
+ ) = withVirtualTime {
+ expect(1)
+ val dsl = SharingStartedDsl(started, initialCommand, coroutineContext)
+ dsl.launch()
+ // repeat every scenario 3 times
+ repeat(3) {
+ dsl.scenario()
+ delay(1000)
+ }
+ dsl.stop()
+ finish(2)
+ }
+
+ private class SharingStartedDsl(
+ val started: SharingStarted,
+ initialCommand: SharingCommand?,
+ coroutineContext: CoroutineContext
+ ) {
+ val subscriptionCount = MutableStateFlow(0)
+ var previousCommand: SharingCommand? = null
+ var expectedCommand: SharingCommand? = initialCommand
+ var expectedTime = 0L
+
+ val dispatcher = coroutineContext[ContinuationInterceptor] as VirtualTimeDispatcher
+ val scope = CoroutineScope(coroutineContext + Job())
+
+ suspend fun launch() {
+ started
+ .command(subscriptionCount.asStateFlow())
+ .onEach { checkCommand(it) }
+ .launchIn(scope)
+ letItRun()
+ }
+
+ fun checkCommand(command: SharingCommand) {
+ assertTrue(command != previousCommand)
+ previousCommand = command
+ assertEquals(expectedCommand, command)
+ assertEquals(expectedTime, dispatcher.currentTime)
+ }
+
+ suspend fun subscriptions(count: Int, command: SharingCommand? = null) {
+ expectedTime = dispatcher.currentTime
+ subscriptionCount.value = count
+ if (command != null) {
+ afterTime(0, command)
+ } else {
+ letItRun()
+ }
+ }
+
+ suspend fun afterTime(time: Long = 0, command: SharingCommand) {
+ expectedCommand = command
+ val remaining = (time - 1).coerceAtLeast(0) // previous letItRun delayed 1ms
+ expectedTime += remaining
+ delay(remaining)
+ letItRun()
+ }
+
+ private suspend fun letItRun() {
+ delay(1)
+ assertEquals(expectedCommand, previousCommand) // make sure expected command was emitted
+ expectedTime++ // make one more time tick we've delayed
+ }
+
+ fun stop() {
+ scope.cancel()
+ }
+ }
+}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/common/test/flow/sharing/SharingStartedWhileSubscribedTest.kt b/kotlinx-coroutines-core/common/test/flow/sharing/SharingStartedWhileSubscribedTest.kt
new file mode 100644
index 0000000..bcf626e
--- /dev/null
+++ b/kotlinx-coroutines-core/common/test/flow/sharing/SharingStartedWhileSubscribedTest.kt
@@ -0,0 +1,42 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.flow
+
+import kotlinx.coroutines.*
+import kotlin.test.*
+import kotlin.time.*
+
+class SharingStartedWhileSubscribedTest : TestBase() {
+ @Test // make sure equals works properly, or otherwise other tests don't make sense
+ fun testEqualsAndHashcode() {
+ val params = listOf(0L, 1L, 10L, 100L, 213L, Long.MAX_VALUE)
+ // HashMap will simultaneously test equals, hashcode and their consistency
+ val map = HashMap<SharingStarted, Pair<Long, Long>>()
+ for (i in params) {
+ for (j in params) {
+ map[SharingStarted.WhileSubscribed(i, j)] = i to j
+ }
+ }
+ for (i in params) {
+ for (j in params) {
+ assertEquals(i to j, map[SharingStarted.WhileSubscribed(i, j)])
+ }
+ }
+ }
+
+ @OptIn(ExperimentalTime::class)
+ @Test
+ fun testDurationParams() {
+ assertEquals(SharingStarted.WhileSubscribed(0), SharingStarted.WhileSubscribed(Duration.ZERO))
+ assertEquals(SharingStarted.WhileSubscribed(10), SharingStarted.WhileSubscribed(10.milliseconds))
+ assertEquals(SharingStarted.WhileSubscribed(1000), SharingStarted.WhileSubscribed(1.seconds))
+ assertEquals(SharingStarted.WhileSubscribed(Long.MAX_VALUE), SharingStarted.WhileSubscribed(Duration.INFINITE))
+ assertEquals(SharingStarted.WhileSubscribed(replayExpirationMillis = 0), SharingStarted.WhileSubscribed(replayExpiration = Duration.ZERO))
+ assertEquals(SharingStarted.WhileSubscribed(replayExpirationMillis = 3), SharingStarted.WhileSubscribed(replayExpiration = 3.milliseconds))
+ assertEquals(SharingStarted.WhileSubscribed(replayExpirationMillis = 7000), SharingStarted.WhileSubscribed(replayExpiration = 7.seconds))
+ assertEquals(SharingStarted.WhileSubscribed(replayExpirationMillis = Long.MAX_VALUE), SharingStarted.WhileSubscribed(replayExpiration = Duration.INFINITE))
+ }
+}
+
diff --git a/kotlinx-coroutines-core/common/test/flow/sharing/StateFlowTest.kt b/kotlinx-coroutines-core/common/test/flow/sharing/StateFlowTest.kt
new file mode 100644
index 0000000..0a2c045
--- /dev/null
+++ b/kotlinx-coroutines-core/common/test/flow/sharing/StateFlowTest.kt
@@ -0,0 +1,196 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.flow
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.channels.*
+import kotlin.test.*
+
+class StateFlowTest : TestBase() {
+ @Test
+ fun testNormalAndNull() = runTest {
+ expect(1)
+ val state = MutableStateFlow<Int?>(0)
+ val job = launch(start = CoroutineStart.UNDISPATCHED) {
+ expect(2)
+ assertFailsWith<CancellationException> {
+ state.collect { value ->
+ when (value) {
+ 0 -> expect(3)
+ 1 -> expect(5)
+ null -> expect(8)
+ 2 -> expect(10)
+ else -> expectUnreached()
+ }
+ }
+ }
+ expect(12)
+ }
+ expect(4) // collector is waiting
+ state.value = 1 // fire in the hole!
+ assertEquals(1, state.value)
+ yield()
+ expect(6)
+ state.value = 1 // same value, nothing happens
+ yield()
+ expect(7)
+ state.value = null // null value
+ assertNull(state.value)
+ yield()
+ expect(9)
+ state.value = 2 // another value
+ assertEquals(2, state.value)
+ yield()
+ expect(11)
+ job.cancel()
+ yield()
+ finish(13)
+ }
+
+ @Test
+ fun testEqualsConflation() = runTest {
+ expect(1)
+ val state = MutableStateFlow(Data(0))
+ val job = launch(start = CoroutineStart.UNDISPATCHED) {
+ expect(2)
+ assertFailsWith<CancellationException> {
+ state.collect { value ->
+ when (value.i) {
+ 0 -> expect(3) // initial value
+ 2 -> expect(5)
+ 4 -> expect(7)
+ else -> error("Unexpected $value")
+ }
+ }
+ }
+ expect(9)
+ }
+ state.value = Data(1) // conflated
+ state.value = Data(0) // equals to last emitted
+ yield() // no repeat zero
+ state.value = Data(3) // conflated
+ state.value = Data(2) // delivered
+ expect(4)
+ yield()
+ state.value = Data(2) // equals to last one, dropped
+ yield()
+ state.value = Data(5) // conflated
+ state.value = Data(4) // delivered
+ expect(6)
+ yield()
+ expect(8)
+ job.cancel()
+ yield()
+ finish(10)
+ }
+
+ data class Data(val i: Int)
+
+ @Test
+ fun testDataModel() = runTest {
+ val s = CounterModel()
+ launch {
+ val sum = s.counter.take(11).sum()
+ assertEquals(55, sum)
+ }
+ repeat(10) {
+ yield()
+ s.inc()
+ }
+ }
+
+ class CounterModel {
+ // private data flow
+ private val _counter = MutableStateFlow(0)
+
+ // publicly exposed as a flow
+ val counter: StateFlow<Int> get() = _counter
+
+ fun inc() {
+ _counter.value++
+ }
+ }
+
+ @Test
+ public fun testOnSubscriptionWithException() = runTest {
+ expect(1)
+ val state = MutableStateFlow("A")
+ state
+ .onSubscription {
+ emit("collector->A")
+ state.value = "A"
+ }
+ .onSubscription {
+ emit("collector->B")
+ state.value = "B"
+ throw TestException()
+ }
+ .onStart {
+ emit("collector->C")
+ state.value = "C"
+ }
+ .onStart {
+ emit("collector->D")
+ state.value = "D"
+ }
+ .onEach {
+ when (it) {
+ "collector->D" -> expect(2)
+ "collector->C" -> expect(3)
+ "collector->A" -> expect(4)
+ "collector->B" -> expect(5)
+ else -> expectUnreached()
+ }
+ }
+ .catch { e ->
+ assertTrue(e is TestException)
+ expect(6)
+ }
+ .launchIn(this)
+ .join()
+ assertEquals(0, state.subscriptionCount.value)
+ finish(7)
+ }
+
+ @Test
+ fun testOperatorFusion() {
+ val state = MutableStateFlow(String)
+ assertSame(state, (state as Flow<*>).cancellable())
+ assertSame(state, (state as Flow<*>).distinctUntilChanged())
+ assertSame(state, (state as Flow<*>).flowOn(Dispatchers.Default))
+ assertSame(state, (state as Flow<*>).conflate())
+ assertSame(state, state.buffer(Channel.CONFLATED))
+ assertSame(state, state.buffer(Channel.RENDEZVOUS))
+ }
+
+ @Test
+ fun testResetUnsupported() {
+ val state = MutableStateFlow(42)
+ assertFailsWith<UnsupportedOperationException> { state.resetReplayCache() }
+ assertEquals(42, state.value)
+ assertEquals(listOf(42), state.replayCache)
+ }
+
+ @Test
+ fun testReferenceUpdatesAndCAS() {
+ val d0 = Data(0)
+ val d0_1 = Data(0)
+ val d1 = Data(1)
+ val d1_1 = Data(1)
+ val d1_2 = Data(1)
+ val state = MutableStateFlow(d0)
+ assertSame(d0, state.value)
+ state.value = d0_1 // equal, nothing changes
+ assertSame(d0, state.value)
+ state.value = d1 // updates
+ assertSame(d1, state.value)
+ assertFalse(state.compareAndSet(d0, d0)) // wrong value
+ assertSame(d1, state.value)
+ assertTrue(state.compareAndSet(d1_1, d1_2)) // "updates", but ref stays
+ assertSame(d1, state.value)
+ assertTrue(state.compareAndSet(d1_1, d0)) // updates, reference changes
+ assertSame(d0, state.value)
+ }
+}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/common/test/flow/sharing/StateInTest.kt b/kotlinx-coroutines-core/common/test/flow/sharing/StateInTest.kt
new file mode 100644
index 0000000..d0e76c4
--- /dev/null
+++ b/kotlinx-coroutines-core/common/test/flow/sharing/StateInTest.kt
@@ -0,0 +1,89 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.flow
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.channels.*
+import kotlin.test.*
+
+/**
+ * It is mostly covered by [ShareInTest], this just add state-specific checks.
+ */
+class StateInTest : TestBase() {
+ @Test
+ fun testOperatorFusion() = runTest {
+ val state = flowOf("OK").stateIn(this)
+ assertTrue(state !is MutableStateFlow<*>) // cannot be cast to mutable state flow
+ assertSame(state, (state as Flow<*>).cancellable())
+ assertSame(state, (state as Flow<*>).distinctUntilChanged())
+ assertSame(state, (state as Flow<*>).flowOn(Dispatchers.Default))
+ assertSame(state, (state as Flow<*>).conflate())
+ assertSame(state, state.buffer(Channel.CONFLATED))
+ assertSame(state, state.buffer(Channel.RENDEZVOUS))
+ assertSame(state, state.buffer(onBufferOverflow = BufferOverflow.DROP_OLDEST))
+ assertSame(state, state.buffer(0, onBufferOverflow = BufferOverflow.DROP_OLDEST))
+ assertSame(state, state.buffer(1, onBufferOverflow = BufferOverflow.DROP_OLDEST))
+ coroutineContext.cancelChildren()
+ }
+
+ @Test
+ fun testUpstreamCompletedNoInitialValue() =
+ testUpstreamCompletedOrFailedReset(failed = false, withInitialValue = false)
+
+ @Test
+ fun testUpstreamFailedNoInitialValue() =
+ testUpstreamCompletedOrFailedReset(failed = true, withInitialValue = false)
+
+ @Test
+ fun testUpstreamCompletedWithInitialValue() =
+ testUpstreamCompletedOrFailedReset(failed = false, withInitialValue = true)
+
+ @Test
+ fun testUpstreamFailedWithInitialValue() =
+ testUpstreamCompletedOrFailedReset(failed = true, withInitialValue = true)
+
+ private fun testUpstreamCompletedOrFailedReset(failed: Boolean, withInitialValue: Boolean) = runTest {
+ val emitted = Job()
+ val terminate = Job()
+ val sharingJob = CompletableDeferred<Unit>()
+ val upstream = flow {
+ emit("OK")
+ emitted.complete()
+ terminate.join()
+ if (failed) throw TestException()
+ }
+ val scope = this + sharingJob
+ val shared: StateFlow<String?>
+ if (withInitialValue) {
+ shared = upstream.stateIn(scope, SharingStarted.Eagerly, null)
+ assertEquals(null, shared.value)
+ } else {
+ shared = upstream.stateIn(scope)
+ assertEquals("OK", shared.value) // waited until upstream emitted
+ }
+ emitted.join() // should start sharing, emit & cache
+ assertEquals("OK", shared.value)
+ terminate.complete()
+ sharingJob.complete(Unit)
+ sharingJob.join() // should complete sharing
+ assertEquals("OK", shared.value) // value is still there
+ if (failed) {
+ assertTrue(sharingJob.getCompletionExceptionOrNull() is TestException)
+ } else {
+ assertNull(sharingJob.getCompletionExceptionOrNull())
+ }
+ }
+
+ @Test
+ fun testUpstreamFailedImmediatelyWithInitialValue() = runTest {
+ val ceh = CoroutineExceptionHandler { _, _ -> expect(2) }
+ val flow = flow<Int> {
+ expect(1)
+ throw TestException()
+ }
+ assertFailsWith<TestException> { flow.stateIn(CoroutineScope(currentCoroutineContext() + Job() + ceh)) }
+ finish(3)
+ }
+}
diff --git a/kotlinx-coroutines-core/common/test/flow/terminal/FirstTest.kt b/kotlinx-coroutines-core/common/test/flow/terminal/FirstTest.kt
index edb9f00..fa7fc9c 100644
--- a/kotlinx-coroutines-core/common/test/flow/terminal/FirstTest.kt
+++ b/kotlinx-coroutines-core/common/test/flow/terminal/FirstTest.kt
@@ -129,6 +129,12 @@
}
@Test
+ fun testFirstOrNullWithNullElement() = runTest {
+ assertNull(flowOf<String?>(null).firstOrNull())
+ assertNull(flowOf<String?>(null).firstOrNull { true })
+ }
+
+ @Test
fun testFirstOrNullWhenErrorCancelsUpstream() = runTest {
val latch = Channel<Unit>()
val flow = flow {
diff --git a/kotlinx-coroutines-core/common/test/flow/terminal/SingleTest.kt b/kotlinx-coroutines-core/common/test/flow/terminal/SingleTest.kt
index 4e89b93..2c1277b 100644
--- a/kotlinx-coroutines-core/common/test/flow/terminal/SingleTest.kt
+++ b/kotlinx-coroutines-core/common/test/flow/terminal/SingleTest.kt
@@ -7,7 +7,7 @@
import kotlinx.coroutines.*
import kotlin.test.*
-class SingleTest : TestBase() {
+class SingleTest : TestBase() {
@Test
fun testSingle() = runTest {
@@ -25,8 +25,8 @@
emit(239L)
emit(240L)
}
- assertFailsWith<RuntimeException> { flow.single() }
- assertFailsWith<RuntimeException> { flow.singleOrNull() }
+ assertFailsWith<IllegalArgumentException> { flow.single() }
+ assertNull(flow.singleOrNull())
}
@Test
@@ -61,6 +61,10 @@
assertEquals(1, flowOf<Int?>(1).single())
assertNull(flowOf<Int?>(null).single())
assertFailsWith<NoSuchElementException> { flowOf<Int?>().single() }
+
+ assertEquals(1, flowOf<Int?>(1).singleOrNull())
+ assertNull(flowOf<Int?>(null).singleOrNull())
+ assertNull(flowOf<Int?>().singleOrNull())
}
@Test
@@ -69,5 +73,22 @@
val flow = flowOf(instance)
assertSame(instance, flow.single())
assertSame(instance, flow.singleOrNull())
+
+ val flow2 = flow {
+ emit(BadClass())
+ emit(BadClass())
+ }
+ assertFailsWith<IllegalArgumentException> { flow2.single() }
+ }
+
+ @Test
+ fun testSingleNoWait() = runTest {
+ val flow = flow {
+ emit(1)
+ emit(2)
+ awaitCancellation()
+ }
+
+ assertNull(flow.singleOrNull())
}
}
diff --git a/kotlinx-coroutines-core/common/test/selects/SelectLoopTest.kt b/kotlinx-coroutines-core/common/test/selects/SelectLoopTest.kt
index 5af68f6..e31ccfc 100644
--- a/kotlinx-coroutines-core/common/test/selects/SelectLoopTest.kt
+++ b/kotlinx-coroutines-core/common/test/selects/SelectLoopTest.kt
@@ -24,19 +24,20 @@
expect(3)
throw TestException()
}
- var isDone = false
- while (!isDone) {
- select<Unit> {
- channel.onReceiveOrNull {
- expect(4)
- assertEquals(Unit, it)
- }
- job.onJoin {
- expect(5)
- isDone = true
+ try {
+ while (true) {
+ select<Unit> {
+ channel.onReceiveOrNull {
+ expectUnreached()
+ }
+ job.onJoin {
+ expectUnreached()
+ }
}
}
+ } catch (e: CancellationException) {
+ // select will get cancelled because of the failure of job
+ finish(4)
}
- finish(6)
}
}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/js/src/Dispatchers.kt b/kotlinx-coroutines-core/js/src/Dispatchers.kt
index 033b39c..06b938d 100644
--- a/kotlinx-coroutines-core/js/src/Dispatchers.kt
+++ b/kotlinx-coroutines-core/js/src/Dispatchers.kt
@@ -7,24 +7,19 @@
import kotlin.coroutines.*
public actual object Dispatchers {
-
public actual val Default: CoroutineDispatcher = createDefaultDispatcher()
-
- public actual val Main: MainCoroutineDispatcher = JsMainDispatcher(Default)
-
+ public actual val Main: MainCoroutineDispatcher = JsMainDispatcher(Default, false)
public actual val Unconfined: CoroutineDispatcher = kotlinx.coroutines.Unconfined
}
-private class JsMainDispatcher(val delegate: CoroutineDispatcher) : MainCoroutineDispatcher() {
-
- override val immediate: MainCoroutineDispatcher
- get() = throw UnsupportedOperationException("Immediate dispatching is not supported on JS")
-
+private class JsMainDispatcher(
+ val delegate: CoroutineDispatcher,
+ private val invokeImmediately: Boolean
+) : MainCoroutineDispatcher() {
+ override val immediate: MainCoroutineDispatcher =
+ if (invokeImmediately) this else JsMainDispatcher(delegate, true)
+ override fun isDispatchNeeded(context: CoroutineContext): Boolean = !invokeImmediately
override fun dispatch(context: CoroutineContext, block: Runnable) = delegate.dispatch(context, block)
-
- override fun isDispatchNeeded(context: CoroutineContext): Boolean = delegate.isDispatchNeeded(context)
-
override fun dispatchYield(context: CoroutineContext, block: Runnable) = delegate.dispatchYield(context, block)
-
override fun toString(): String = toStringInternalImpl() ?: delegate.toString()
}
diff --git a/kotlinx-coroutines-core/js/src/JSDispatcher.kt b/kotlinx-coroutines-core/js/src/JSDispatcher.kt
index a0dfcba..e1b3dcd 100644
--- a/kotlinx-coroutines-core/js/src/JSDispatcher.kt
+++ b/kotlinx-coroutines-core/js/src/JSDispatcher.kt
@@ -35,7 +35,7 @@
messageQueue.enqueue(block)
}
- override fun invokeOnTimeout(timeMillis: Long, block: Runnable): DisposableHandle {
+ override fun invokeOnTimeout(timeMillis: Long, block: Runnable, context: CoroutineContext): DisposableHandle {
val handle = setTimeout({ block.run() }, delayToInt(timeMillis))
return ClearTimeout(handle)
}
@@ -81,7 +81,7 @@
window.setTimeout({ with(continuation) { resumeUndispatched(Unit) } }, delayToInt(timeMillis))
}
- override fun invokeOnTimeout(timeMillis: Long, block: Runnable): DisposableHandle {
+ override fun invokeOnTimeout(timeMillis: Long, block: Runnable, context: CoroutineContext): DisposableHandle {
val handle = window.setTimeout({ block.run() }, delayToInt(timeMillis))
return object : DisposableHandle {
override fun dispose() {
diff --git a/kotlinx-coroutines-core/js/src/Promise.kt b/kotlinx-coroutines-core/js/src/Promise.kt
index 6c3de76..ab20032 100644
--- a/kotlinx-coroutines-core/js/src/Promise.kt
+++ b/kotlinx-coroutines-core/js/src/Promise.kt
@@ -62,6 +62,8 @@
* This suspending function is cancellable.
* If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function
* stops waiting for the promise and immediately resumes with [CancellationException].
+ * There is a **prompt cancellation guarantee**. If the job was cancelled while this function was
+ * suspended, it will not resume successfully. See [suspendCancellableCoroutine] documentation for low-level details.
*/
public suspend fun <T> Promise<T>.await(): T = suspendCancellableCoroutine { cont: CancellableContinuation<T> ->
this@await.then(
diff --git a/kotlinx-coroutines-core/js/src/internal/LinkedList.kt b/kotlinx-coroutines-core/js/src/internal/LinkedList.kt
index 342b11c..b698505 100644
--- a/kotlinx-coroutines-core/js/src/internal/LinkedList.kt
+++ b/kotlinx-coroutines-core/js/src/internal/LinkedList.kt
@@ -124,6 +124,8 @@
return null
}
+ actual open fun onRemoved(affected: Node) {}
+
actual final override fun prepare(op: AtomicOp<*>): Any? {
val affected = affectedNode
val failure = failure(affected)
diff --git a/kotlinx-coroutines-core/js/src/internal/LocalAtomics.kt b/kotlinx-coroutines-core/js/src/internal/LocalAtomics.kt
new file mode 100644
index 0000000..fffd76c
--- /dev/null
+++ b/kotlinx-coroutines-core/js/src/internal/LocalAtomics.kt
@@ -0,0 +1,15 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.internal
+
+internal actual class LocalAtomicInt actual constructor(private var value: Int) {
+ actual fun set(value: Int) {
+ this.value = value
+ }
+
+ actual fun get(): Int = value
+
+ actual fun decrementAndGet(): Int = --value
+}
diff --git a/kotlinx-coroutines-core/js/test/ImmediateDispatcherTest.kt b/kotlinx-coroutines-core/js/test/ImmediateDispatcherTest.kt
new file mode 100644
index 0000000..7ca6a24
--- /dev/null
+++ b/kotlinx-coroutines-core/js/test/ImmediateDispatcherTest.kt
@@ -0,0 +1,32 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines
+
+import kotlin.test.*
+
+class ImmediateDispatcherTest : TestBase() {
+
+ @Test
+ fun testImmediate() = runTest {
+ expect(1)
+ val job = launch { expect(3) }
+ withContext(Dispatchers.Main.immediate) {
+ expect(2)
+ }
+ job.join()
+ finish(4)
+ }
+
+ @Test
+ fun testMain() = runTest {
+ expect(1)
+ val job = launch { expect(2) }
+ withContext(Dispatchers.Main) {
+ expect(3)
+ }
+ job.join()
+ finish(4)
+ }
+}
diff --git a/kotlinx-coroutines-core/jvm/resources/DebugProbesKt.bin b/kotlinx-coroutines-core/jvm/resources/DebugProbesKt.bin
index 8a7160f..76ee411 100644
--- a/kotlinx-coroutines-core/jvm/resources/DebugProbesKt.bin
+++ b/kotlinx-coroutines-core/jvm/resources/DebugProbesKt.bin
Binary files differ
diff --git a/kotlinx-coroutines-core/jvm/resources/META-INF/proguard/coroutines.pro b/kotlinx-coroutines-core/jvm/resources/META-INF/proguard/coroutines.pro
index d69e573..60c8d61 100644
--- a/kotlinx-coroutines-core/jvm/resources/META-INF/proguard/coroutines.pro
+++ b/kotlinx-coroutines-core/jvm/resources/META-INF/proguard/coroutines.pro
@@ -12,3 +12,9 @@
volatile <fields>;
}
+# These classes are only required by kotlinx.coroutines.debug.AgentPremain, which is only loaded when
+# kotlinx-coroutines-core is used as a Java agent, so these are not needed in contexts where ProGuard is used.
+-dontwarn java.lang.instrument.ClassFileTransformer
+-dontwarn sun.misc.SignalHandler
+-dontwarn java.lang.instrument.Instrumentation
+-dontwarn sun.misc.Signal
diff --git a/kotlinx-coroutines-core/jvm/src/CommonPool.kt b/kotlinx-coroutines-core/jvm/src/CommonPool.kt
index 60f30cf..2203313 100644
--- a/kotlinx-coroutines-core/jvm/src/CommonPool.kt
+++ b/kotlinx-coroutines-core/jvm/src/CommonPool.kt
@@ -103,6 +103,8 @@
(pool ?: getOrCreatePoolSync()).execute(wrapTask(block))
} catch (e: RejectedExecutionException) {
unTrackTask()
+ // CommonPool only rejects execution when it is being closed and this behavior is reserved
+ // for testing purposes, so we don't have to worry about cancelling the affected Job here.
DefaultExecutor.enqueue(block)
}
}
diff --git a/kotlinx-coroutines-core/jvm/src/DebugStrings.kt b/kotlinx-coroutines-core/jvm/src/DebugStrings.kt
index 184fb65..2ccfebc 100644
--- a/kotlinx-coroutines-core/jvm/src/DebugStrings.kt
+++ b/kotlinx-coroutines-core/jvm/src/DebugStrings.kt
@@ -4,6 +4,7 @@
package kotlinx.coroutines
+import kotlinx.coroutines.internal.*
import kotlin.coroutines.*
// internal debugging tools for string representation
diff --git a/kotlinx-coroutines-core/jvm/src/DefaultExecutor.kt b/kotlinx-coroutines-core/jvm/src/DefaultExecutor.kt
index ed84f55..787cbf9 100644
--- a/kotlinx-coroutines-core/jvm/src/DefaultExecutor.kt
+++ b/kotlinx-coroutines-core/jvm/src/DefaultExecutor.kt
@@ -5,6 +5,7 @@
package kotlinx.coroutines
import java.util.concurrent.*
+import kotlin.coroutines.*
internal actual val DefaultDelay: Delay = DefaultExecutor
@@ -54,7 +55,7 @@
* Livelock is possible only if `runBlocking` is called on internal default executed (which is used by default [delay]),
* but it's not exposed as public API.
*/
- override fun invokeOnTimeout(timeMillis: Long, block: Runnable): DisposableHandle =
+ override fun invokeOnTimeout(timeMillis: Long, block: Runnable, context: CoroutineContext): DisposableHandle =
scheduleInvokeOnTimeout(timeMillis, block)
override fun run() {
diff --git a/kotlinx-coroutines-core/jvm/src/Dispatchers.kt b/kotlinx-coroutines-core/jvm/src/Dispatchers.kt
index 8cd3bb1..8033fb3 100644
--- a/kotlinx-coroutines-core/jvm/src/Dispatchers.kt
+++ b/kotlinx-coroutines-core/jvm/src/Dispatchers.kt
@@ -97,7 +97,7 @@
* The [CoroutineDispatcher] that is designed for offloading blocking IO tasks to a shared pool of threads.
*
* Additional threads in this pool are created and are shutdown on demand.
- * The number of threads used by this dispatcher is limited by the value of
+ * The number of threads used by tasks in this dispatcher is limited by the value of
* "`kotlinx.coroutines.io.parallelism`" ([IO_PARALLELISM_PROPERTY_NAME]) system property.
* It defaults to the limit of 64 threads or the number of cores (whichever is larger).
*
@@ -106,9 +106,13 @@
* If you need a higher number of parallel threads,
* you should use a custom dispatcher backed by your own thread pool.
*
+ * ### Implementation note
+ *
* This dispatcher shares threads with a [Default][Dispatchers.Default] dispatcher, so using
* `withContext(Dispatchers.IO) { ... }` does not lead to an actual switching to another thread —
* typically execution continues in the same thread.
+ * As a result of thread sharing, more than 64 (default parallelism) threads can be created (but not used)
+ * during operations over IO dispatcher.
*/
@JvmStatic
public val IO: CoroutineDispatcher = DefaultScheduler.IO
diff --git a/kotlinx-coroutines-core/jvm/src/Executors.kt b/kotlinx-coroutines-core/jvm/src/Executors.kt
index a4d6b46..8ffc22d 100644
--- a/kotlinx-coroutines-core/jvm/src/Executors.kt
+++ b/kotlinx-coroutines-core/jvm/src/Executors.kt
@@ -14,7 +14,7 @@
* Instances of [ExecutorCoroutineDispatcher] should be closed by the owner of the dispatcher.
*
* This class is generally used as a bridge between coroutine-based API and
- * asynchronous API which requires instance of the [Executor].
+ * asynchronous API that requires an instance of the [Executor].
*/
public abstract class ExecutorCoroutineDispatcher: CoroutineDispatcher(), Closeable {
/** @suppress */
@@ -38,6 +38,12 @@
/**
* Converts an instance of [ExecutorService] to an implementation of [ExecutorCoroutineDispatcher].
+ *
+ * If the underlying executor throws [RejectedExecutionException] on
+ * attempt to submit a continuation task (it happens when [closing][ExecutorCoroutineDispatcher.close] the
+ * resulting dispatcher, on underlying executor [shutdown][ExecutorService.shutdown], or when it uses limited queues),
+ * then the [Job] of the affected task is [cancelled][Job.cancel] and the task is submitted to the
+ * [Dispatchers.IO], so that the affected coroutine can cleanup its resources and promptly complete.
*/
@JvmName("from") // this is for a nice Java API, see issue #255
public fun ExecutorService.asCoroutineDispatcher(): ExecutorCoroutineDispatcher =
@@ -45,6 +51,12 @@
/**
* Converts an instance of [Executor] to an implementation of [CoroutineDispatcher].
+ *
+ * If the underlying executor throws [RejectedExecutionException] on
+ * attempt to submit a continuation task (it happens when [closing][ExecutorCoroutineDispatcher.close] the
+ * resulting dispatcher, on underlying executor [shutdown][ExecutorService.shutdown], or when it uses limited queues),
+ * then the [Job] of the affected task is [cancelled][Job.cancel] and the task is submitted to the
+ * [Dispatchers.IO], so that the affected coroutine can cleanup its resources and promptly complete.
*/
@JvmName("from") // this is for a nice Java API, see issue #255
public fun Executor.asCoroutineDispatcher(): CoroutineDispatcher =
@@ -82,7 +94,8 @@
executor.execute(wrapTask(block))
} catch (e: RejectedExecutionException) {
unTrackTask()
- DefaultExecutor.enqueue(block)
+ cancelJobOnRejection(context, e)
+ Dispatchers.IO.dispatch(context, block)
}
}
@@ -93,7 +106,7 @@
*/
override fun scheduleResumeAfterDelay(timeMillis: Long, continuation: CancellableContinuation<Unit>) {
val future = if (removesFutureOnCancellation) {
- scheduleBlock(ResumeUndispatchedRunnable(this, continuation), timeMillis, TimeUnit.MILLISECONDS)
+ scheduleBlock(ResumeUndispatchedRunnable(this, continuation), continuation.context, timeMillis)
} else {
null
}
@@ -106,24 +119,31 @@
DefaultExecutor.scheduleResumeAfterDelay(timeMillis, continuation)
}
- override fun invokeOnTimeout(timeMillis: Long, block: Runnable): DisposableHandle {
+ override fun invokeOnTimeout(timeMillis: Long, block: Runnable, context: CoroutineContext): DisposableHandle {
val future = if (removesFutureOnCancellation) {
- scheduleBlock(block, timeMillis, TimeUnit.MILLISECONDS)
+ scheduleBlock(block, context, timeMillis)
} else {
null
}
-
- return if (future != null ) DisposableFutureHandle(future) else DefaultExecutor.invokeOnTimeout(timeMillis, block)
+ return when {
+ future != null -> DisposableFutureHandle(future)
+ else -> DefaultExecutor.invokeOnTimeout(timeMillis, block, context)
+ }
}
- private fun scheduleBlock(block: Runnable, time: Long, unit: TimeUnit): ScheduledFuture<*>? {
+ private fun scheduleBlock(block: Runnable, context: CoroutineContext, timeMillis: Long): ScheduledFuture<*>? {
return try {
- (executor as? ScheduledExecutorService)?.schedule(block, time, unit)
+ (executor as? ScheduledExecutorService)?.schedule(block, timeMillis, TimeUnit.MILLISECONDS)
} catch (e: RejectedExecutionException) {
+ cancelJobOnRejection(context, e)
null
}
}
+ private fun cancelJobOnRejection(context: CoroutineContext, exception: RejectedExecutionException) {
+ context.cancel(CancellationException("The task was rejected", exception))
+ }
+
override fun close() {
(executor as? ExecutorService)?.shutdown()
}
diff --git a/kotlinx-coroutines-core/jvm/src/Interruptible.kt b/kotlinx-coroutines-core/jvm/src/Interruptible.kt
index f50e093..070aa62 100644
--- a/kotlinx-coroutines-core/jvm/src/Interruptible.kt
+++ b/kotlinx-coroutines-core/jvm/src/Interruptible.kt
@@ -40,8 +40,7 @@
private fun <T> runInterruptibleInExpectedContext(coroutineContext: CoroutineContext, block: () -> T): T {
try {
- val job = coroutineContext[Job]!! // withContext always creates a job
- val threadState = ThreadState(job)
+ val threadState = ThreadState(coroutineContext.job)
threadState.setup()
try {
return block()
diff --git a/kotlinx-coroutines-core/jvm/src/ThreadPoolDispatcher.kt b/kotlinx-coroutines-core/jvm/src/ThreadPoolDispatcher.kt
index a0e1ffa..aa18cd3 100644
--- a/kotlinx-coroutines-core/jvm/src/ThreadPoolDispatcher.kt
+++ b/kotlinx-coroutines-core/jvm/src/ThreadPoolDispatcher.kt
@@ -14,6 +14,11 @@
* **NOTE: The resulting [ExecutorCoroutineDispatcher] owns native resources (its thread).
* Resources are reclaimed by [ExecutorCoroutineDispatcher.close].**
*
+ * If the resulting dispatcher is [closed][ExecutorCoroutineDispatcher.close] and
+ * attempt to submit a continuation task is made,
+ * then the [Job] of the affected task is [cancelled][Job.cancel] and the task is submitted to the
+ * [Dispatchers.IO], so that the affected coroutine can cleanup its resources and promptly complete.
+ *
* **NOTE: This API will be replaced in the future**. A different API to create thread-limited thread pools
* that is based on a shared thread-pool and does not require the resulting dispatcher to be explicitly closed
* will be provided, thus avoiding potential thread leaks and also significantly improving performance, due
@@ -35,6 +40,11 @@
* **NOTE: The resulting [ExecutorCoroutineDispatcher] owns native resources (its threads).
* Resources are reclaimed by [ExecutorCoroutineDispatcher.close].**
*
+ * If the resulting dispatcher is [closed][ExecutorCoroutineDispatcher.close] and
+ * attempt to submit a continuation task is made,
+ * then the [Job] of the affected task is [cancelled][Job.cancel] and the task is submitted to the
+ * [Dispatchers.IO], so that the affected coroutine can cleanup its resources and promptly complete.
+ *
* **NOTE: This API will be replaced in the future**. A different API to create thread-limited thread pools
* that is based on a shared thread-pool and does not require the resulting dispatcher to be explicitly closed
* will be provided, thus avoiding potential thread leaks and also significantly improving performance, due
diff --git a/kotlinx-coroutines-core/jvm/src/debug/AgentPremain.kt b/kotlinx-coroutines-core/jvm/src/debug/AgentPremain.kt
index df10501..5a1a1ed 100644
--- a/kotlinx-coroutines-core/jvm/src/debug/AgentPremain.kt
+++ b/kotlinx-coroutines-core/jvm/src/debug/AgentPremain.kt
@@ -21,9 +21,9 @@
public var isInstalledStatically = false
- private val enableCreationStackTraces =
+ private val enableCreationStackTraces = runCatching {
System.getProperty("kotlinx.coroutines.debug.enable.creation.stack.trace")?.toBoolean()
- ?: DebugProbesImpl.enableCreationStackTraces
+ }.getOrNull() ?: DebugProbesImpl.enableCreationStackTraces
@JvmStatic
public fun premain(args: String?, instrumentation: Instrumentation) {
diff --git a/kotlinx-coroutines-core/jvm/src/debug/internal/DebugProbesImpl.kt b/kotlinx-coroutines-core/jvm/src/debug/internal/DebugProbesImpl.kt
index 9dd6c5a..83bc02c 100644
--- a/kotlinx-coroutines-core/jvm/src/debug/internal/DebugProbesImpl.kt
+++ b/kotlinx-coroutines-core/jvm/src/debug/internal/DebugProbesImpl.kt
@@ -111,7 +111,7 @@
check(isInstalled) { "Debug probes are not installed" }
val jobToStack = capturedCoroutines
.filter { it.delegate.context[Job] != null }
- .associateBy({ it.delegate.context[Job]!! }, { it.info })
+ .associateBy({ it.delegate.context.job }, { it.info })
return buildString {
job.build(jobToStack, this, "")
}
@@ -156,7 +156,11 @@
// Stable ordering of coroutines by their sequence number
.sortedBy { it.info.sequenceNumber }
// Leave in the dump only the coroutines that were not collected while we were dumping them
- .mapNotNull { owner -> owner.info.context?.let { context -> create(owner, context) } }
+ .mapNotNull { owner ->
+ // Fuse map and filter into one operation to save an inline
+ if (owner.isFinished()) null
+ else owner.info.context?.let { context -> create(owner, context) }
+ }
}
/*
@@ -183,10 +187,27 @@
dumpCoroutinesSynchronized(out)
}
+ /*
+ * Filters out coroutines that do not call probeCoroutineCompleted,
+ * are completed, but not yet garbage collected.
+ *
+ * Typically, we intercept completion of the coroutine so it invokes "probeCoroutineCompleted",
+ * but it's not the case for lazy coroutines that get cancelled before start.
+ */
+ private fun CoroutineOwner<*>.isFinished(): Boolean {
+ // Guarded by lock
+ val job = info.context?.get(Job) ?: return false
+ if (!job.isCompleted) return false
+ capturedCoroutinesMap.remove(this) // Clean it up by the way
+ return true
+ }
+
private fun dumpCoroutinesSynchronized(out: PrintStream): Unit = coroutineStateLock.write {
check(isInstalled) { "Debug probes are not installed" }
out.print("Coroutines dump ${dateFormat.format(System.currentTimeMillis())}")
capturedCoroutines
+ .asSequence()
+ .filter { !it.isFinished() }
.sortedBy { it.info.sequenceNumber }
.forEach { owner ->
val info = owner.info
diff --git a/kotlinx-coroutines-core/jvm/src/flow/internal/SafeCollector.kt b/kotlinx-coroutines-core/jvm/src/flow/internal/SafeCollector.kt
index a8e04f0..ab42b63 100644
--- a/kotlinx-coroutines-core/jvm/src/flow/internal/SafeCollector.kt
+++ b/kotlinx-coroutines-core/jvm/src/flow/internal/SafeCollector.kt
@@ -21,7 +21,11 @@
internal actual class SafeCollector<T> actual constructor(
@JvmField internal actual val collector: FlowCollector<T>,
@JvmField internal actual val collectContext: CoroutineContext
-) : FlowCollector<T>, ContinuationImpl(NoOpContinuation, EmptyCoroutineContext) {
+) : FlowCollector<T>, ContinuationImpl(NoOpContinuation, EmptyCoroutineContext), CoroutineStackFrame {
+
+ override val callerFrame: CoroutineStackFrame? get() = completion as? CoroutineStackFrame
+
+ override fun getStackTraceElement(): StackTraceElement? = null
@JvmField // Note, it is non-capturing lambda, so no extra allocation during init of SafeCollector
internal actual val collectContextSize = collectContext.fold(0) { count, _ -> count + 1 }
diff --git a/kotlinx-coroutines-core/jvm/src/internal/LocalAtomics.kt b/kotlinx-coroutines-core/jvm/src/internal/LocalAtomics.kt
new file mode 100644
index 0000000..f508749
--- /dev/null
+++ b/kotlinx-coroutines-core/jvm/src/internal/LocalAtomics.kt
@@ -0,0 +1,8 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.internal
+
+@Suppress("ACTUAL_WITHOUT_EXPECT")
+internal actual typealias LocalAtomicInt = java.util.concurrent.atomic.AtomicInteger
diff --git a/kotlinx-coroutines-core/jvm/src/internal/LockFreeLinkedList.kt b/kotlinx-coroutines-core/jvm/src/internal/LockFreeLinkedList.kt
index 29f37da..97f9978 100644
--- a/kotlinx-coroutines-core/jvm/src/internal/LockFreeLinkedList.kt
+++ b/kotlinx-coroutines-core/jvm/src/internal/LockFreeLinkedList.kt
@@ -416,20 +416,26 @@
val next = this.next
val removed = next.removed()
if (affected._next.compareAndSet(this, removed)) {
+ // The element was actually removed
+ desc.onRemoved(affected)
// Complete removal operation here. It bails out if next node is also removed and it becomes
// responsibility of the next's removes to call correctPrev which would help fix all the links.
next.correctPrev(null)
}
return REMOVE_PREPARED
}
- val isDecided = if (decision != null) {
+ // We need to ensure progress even if it operation result consensus was already decided
+ val consensus = if (decision != null) {
// some other logic failure, including RETRY_ATOMIC -- reach consensus on decision fail reason ASAP
atomicOp.decide(decision)
- true // atomicOp.isDecided will be true as a result
} else {
- atomicOp.isDecided // consult with current decision status like in Harris DCSS
+ atomicOp.consensus // consult with current decision status like in Harris DCSS
}
- val update: Any = if (isDecided) next else atomicOp // restore if decision was already reached
+ val update: Any = when {
+ consensus === NO_DECISION -> atomicOp // desc.onPrepare returned null -> start doing atomic op
+ consensus == null -> desc.updatedNext(affected, next) // move forward if consensus on success
+ else -> next // roll back if consensus if failure
+ }
affected._next.compareAndSet(this, update)
return null
}
@@ -445,9 +451,10 @@
protected open fun takeAffectedNode(op: OpDescriptor): Node? = affectedNode!! // null for RETRY_ATOMIC
protected open fun failure(affected: Node): Any? = null // next: Node | Removed
protected open fun retry(affected: Node, next: Any): Boolean = false // next: Node | Removed
- protected abstract fun updatedNext(affected: Node, next: Node): Any
protected abstract fun finishOnSuccess(affected: Node, next: Node)
+ public abstract fun updatedNext(affected: Node, next: Node): Any
+
public abstract fun finishPrepare(prepareOp: PrepareOp)
// non-null on failure
@@ -456,6 +463,8 @@
return null
}
+ public open fun onRemoved(affected: Node) {} // called once when node was prepared & later removed
+
@Suppress("UNCHECKED_CAST")
final override fun prepare(op: AtomicOp<*>): Any? {
while (true) { // lock free loop on next
diff --git a/kotlinx-coroutines-core/jvm/src/internal/MainDispatchers.kt b/kotlinx-coroutines-core/jvm/src/internal/MainDispatchers.kt
index ddfcdbb..5b2b9ff 100644
--- a/kotlinx-coroutines-core/jvm/src/internal/MainDispatchers.kt
+++ b/kotlinx-coroutines-core/jvm/src/internal/MainDispatchers.kt
@@ -87,17 +87,14 @@
override val immediate: MainCoroutineDispatcher get() = this
- override fun isDispatchNeeded(context: CoroutineContext): Boolean {
+ override fun isDispatchNeeded(context: CoroutineContext): Boolean =
missing()
- }
- override suspend fun delay(time: Long) {
+ override suspend fun delay(time: Long) =
missing()
- }
- override fun invokeOnTimeout(timeMillis: Long, block: Runnable): DisposableHandle {
+ override fun invokeOnTimeout(timeMillis: Long, block: Runnable, context: CoroutineContext): DisposableHandle =
missing()
- }
override fun dispatch(context: CoroutineContext, block: Runnable) =
missing()
diff --git a/kotlinx-coroutines-core/jvm/src/scheduling/Dispatcher.kt b/kotlinx-coroutines-core/jvm/src/scheduling/Dispatcher.kt
index e0890ef..202c6e1 100644
--- a/kotlinx-coroutines-core/jvm/src/scheduling/Dispatcher.kt
+++ b/kotlinx-coroutines-core/jvm/src/scheduling/Dispatcher.kt
@@ -65,6 +65,8 @@
try {
coroutineScheduler.dispatch(block)
} catch (e: RejectedExecutionException) {
+ // CoroutineScheduler only rejects execution when it is being closed and this behavior is reserved
+ // for testing purposes, so we don't have to worry about cancelling the affected Job here.
DefaultExecutor.dispatch(context, block)
}
@@ -72,6 +74,8 @@
try {
coroutineScheduler.dispatch(block, tailDispatch = true)
} catch (e: RejectedExecutionException) {
+ // CoroutineScheduler only rejects execution when it is being closed and this behavior is reserved
+ // for testing purposes, so we don't have to worry about cancelling the affected Job here.
DefaultExecutor.dispatchYield(context, block)
}
@@ -110,7 +114,9 @@
try {
coroutineScheduler.dispatch(block, context, tailDispatch)
} catch (e: RejectedExecutionException) {
- // Context shouldn't be lost here to properly invoke before/after task
+ // CoroutineScheduler only rejects execution when it is being closed and this behavior is reserved
+ // for testing purposes, so we don't have to worry about cancelling the affected Job here.
+ // TaskContext shouldn't be lost here to properly invoke before/after task
DefaultExecutor.enqueue(coroutineScheduler.createTask(block, context))
}
}
diff --git a/kotlinx-coroutines-core/jvm/src/test_/TestCoroutineContext.kt b/kotlinx-coroutines-core/jvm/src/test_/TestCoroutineContext.kt
index e7c8b6b..649c953 100644
--- a/kotlinx-coroutines-core/jvm/src/test_/TestCoroutineContext.kt
+++ b/kotlinx-coroutines-core/jvm/src/test_/TestCoroutineContext.kt
@@ -230,7 +230,7 @@
}, timeMillis)
}
- override fun invokeOnTimeout(timeMillis: Long, block: Runnable): DisposableHandle {
+ override fun invokeOnTimeout(timeMillis: Long, block: Runnable, context: CoroutineContext): DisposableHandle {
val node = postDelayed(block, timeMillis)
return object : DisposableHandle {
override fun dispose() {
diff --git a/kotlinx-coroutines-core/jvm/test/AtomicCancellationTest.kt b/kotlinx-coroutines-core/jvm/test/AtomicCancellationTest.kt
index 8a7dce0..2612b84 100644
--- a/kotlinx-coroutines-core/jvm/test/AtomicCancellationTest.kt
+++ b/kotlinx-coroutines-core/jvm/test/AtomicCancellationTest.kt
@@ -9,25 +9,24 @@
import kotlin.test.*
class AtomicCancellationTest : TestBase() {
-
@Test
- fun testSendAtomicCancel() = runBlocking {
+ fun testSendCancellable() = runBlocking {
expect(1)
val channel = Channel<Int>()
val job = launch(start = CoroutineStart.UNDISPATCHED) {
expect(2)
channel.send(42) // suspends
- expect(4) // should execute despite cancellation
+ expectUnreached() // should NOT execute because of cancellation
}
expect(3)
assertEquals(42, channel.receive()) // will schedule sender for further execution
job.cancel() // cancel the job next
yield() // now yield
- finish(5)
+ finish(4)
}
@Test
- fun testSelectSendAtomicCancel() = runBlocking {
+ fun testSelectSendCancellable() = runBlocking {
expect(1)
val channel = Channel<Int>()
val job = launch(start = CoroutineStart.UNDISPATCHED) {
@@ -38,34 +37,33 @@
"OK"
}
}
- assertEquals("OK", result)
- expect(5) // should execute despite cancellation
+ expectUnreached() // should NOT execute because of cancellation
}
expect(3)
assertEquals(42, channel.receive()) // will schedule sender for further execution
job.cancel() // cancel the job next
yield() // now yield
- finish(6)
+ finish(4)
}
@Test
- fun testReceiveAtomicCancel() = runBlocking {
+ fun testReceiveCancellable() = runBlocking {
expect(1)
val channel = Channel<Int>()
val job = launch(start = CoroutineStart.UNDISPATCHED) {
expect(2)
assertEquals(42, channel.receive()) // suspends
- expect(4) // should execute despite cancellation
+ expectUnreached() // should NOT execute because of cancellation
}
expect(3)
channel.send(42) // will schedule receiver for further execution
job.cancel() // cancel the job next
yield() // now yield
- finish(5)
+ finish(4)
}
@Test
- fun testSelectReceiveAtomicCancel() = runBlocking {
+ fun testSelectReceiveCancellable() = runBlocking {
expect(1)
val channel = Channel<Int>()
val job = launch(start = CoroutineStart.UNDISPATCHED) {
@@ -77,14 +75,13 @@
"OK"
}
}
- assertEquals("OK", result)
- expect(5) // should execute despite cancellation
+ expectUnreached() // should NOT execute because of cancellation
}
expect(3)
channel.send(42) // will schedule receiver for further execution
job.cancel() // cancel the job next
yield() // now yield
- finish(6)
+ finish(4)
}
@Test
diff --git a/kotlinx-coroutines-core/jvm/test/ExecutorsTest.kt b/kotlinx-coroutines-core/jvm/test/ExecutorsTest.kt
index 033b9b7..ebf08a0 100644
--- a/kotlinx-coroutines-core/jvm/test/ExecutorsTest.kt
+++ b/kotlinx-coroutines-core/jvm/test/ExecutorsTest.kt
@@ -1,5 +1,5 @@
/*
- * Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
*/
package kotlinx.coroutines
@@ -29,6 +29,8 @@
val context = newFixedThreadPoolContext(2, "TestPool")
runBlocking(context) {
checkThreadName("TestPool")
+ delay(10)
+ checkThreadName("TestPool") // should dispatch on the right thread
}
context.close()
}
@@ -38,6 +40,8 @@
val executor = Executors.newSingleThreadExecutor { r -> Thread(r, "TestExecutor") }
runBlocking(executor.asCoroutineDispatcher()) {
checkThreadName("TestExecutor")
+ delay(10)
+ checkThreadName("TestExecutor") // should dispatch on the right thread
}
executor.shutdown()
}
diff --git a/kotlinx-coroutines-core/jvm/test/FailingCoroutinesMachineryTest.kt b/kotlinx-coroutines-core/jvm/test/FailingCoroutinesMachineryTest.kt
index 9bf8ffa..c9f722a 100644
--- a/kotlinx-coroutines-core/jvm/test/FailingCoroutinesMachineryTest.kt
+++ b/kotlinx-coroutines-core/jvm/test/FailingCoroutinesMachineryTest.kt
@@ -1,5 +1,5 @@
/*
- * Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
*/
package kotlinx.coroutines
@@ -15,8 +15,21 @@
@RunWith(Parameterized::class)
class FailingCoroutinesMachineryTest(
private val element: CoroutineContext.Element,
- private val dispatcher: CoroutineDispatcher
+ private val dispatcher: TestDispatcher
) : TestBase() {
+ class TestDispatcher(val name: String, val block: () -> CoroutineDispatcher) {
+ private var _value: CoroutineDispatcher? = null
+
+ val value: CoroutineDispatcher
+ get() = _value ?: block().also { _value = it }
+
+ override fun toString(): String = name
+
+ fun reset() {
+ runCatching { (_value as? ExecutorCoroutineDispatcher)?.close() }
+ _value = null
+ }
+ }
private var caught: Throwable? = null
private val latch = CountDownLatch(1)
@@ -75,7 +88,7 @@
@After
fun tearDown() {
- runCatching { (dispatcher as? ExecutorCoroutineDispatcher)?.close() }
+ dispatcher.reset()
if (lazyOuterDispatcher.isInitialized()) lazyOuterDispatcher.value.close()
}
@@ -84,14 +97,14 @@
@Parameterized.Parameters(name = "Element: {0}, dispatcher: {1}")
fun dispatchers(): List<Array<Any>> {
val elements = listOf<Any>(FailingRestore, FailingUpdate)
- val dispatchers = listOf<Any>(
- Dispatchers.Unconfined,
- Dispatchers.Default,
- Executors.newFixedThreadPool(1).asCoroutineDispatcher(),
- Executors.newScheduledThreadPool(1).asCoroutineDispatcher(),
- ThrowingDispatcher, ThrowingDispatcher2
+ val dispatchers = listOf<TestDispatcher>(
+ TestDispatcher("Dispatchers.Unconfined") { Dispatchers.Unconfined },
+ TestDispatcher("Dispatchers.Default") { Dispatchers.Default },
+ TestDispatcher("Executors.newFixedThreadPool(1)") { Executors.newFixedThreadPool(1).asCoroutineDispatcher() },
+ TestDispatcher("Executors.newScheduledThreadPool(1)") { Executors.newScheduledThreadPool(1).asCoroutineDispatcher() },
+ TestDispatcher("ThrowingDispatcher") { ThrowingDispatcher },
+ TestDispatcher("ThrowingDispatcher2") { ThrowingDispatcher2 }
)
-
return elements.flatMap { element ->
dispatchers.map { dispatcher ->
arrayOf(element, dispatcher)
@@ -102,13 +115,13 @@
@Test
fun testElement() = runTest {
- launch(NonCancellable + dispatcher + exceptionHandler + element) {}
+ launch(NonCancellable + dispatcher.value + exceptionHandler + element) {}
checkException()
}
@Test
fun testNestedElement() = runTest {
- launch(NonCancellable + dispatcher + exceptionHandler) {
+ launch(NonCancellable + dispatcher.value + exceptionHandler) {
launch(element) { }
}
checkException()
@@ -117,7 +130,7 @@
@Test
fun testNestedDispatcherAndElement() = runTest {
launch(lazyOuterDispatcher.value + NonCancellable + exceptionHandler) {
- launch(element + dispatcher) { }
+ launch(element + dispatcher.value) { }
}
checkException()
}
diff --git a/kotlinx-coroutines-core/jvm/test/JobStructuredJoinStressTest.kt b/kotlinx-coroutines-core/jvm/test/JobStructuredJoinStressTest.kt
index ec3635c..50d86f3 100644
--- a/kotlinx-coroutines-core/jvm/test/JobStructuredJoinStressTest.kt
+++ b/kotlinx-coroutines-core/jvm/test/JobStructuredJoinStressTest.kt
@@ -5,6 +5,7 @@
package kotlinx.coroutines
import org.junit.*
+import kotlin.coroutines.*
/**
* Test a race between job failure and join.
@@ -12,22 +13,52 @@
* See [#1123](https://github.com/Kotlin/kotlinx.coroutines/issues/1123).
*/
class JobStructuredJoinStressTest : TestBase() {
- private val nRepeats = 1_000 * stressTestMultiplier
+ private val nRepeats = 10_000 * stressTestMultiplier
@Test
- fun testStress() {
- repeat(nRepeats) {
+ fun testStressRegularJoin() {
+ stress(Job::join)
+ }
+
+ @Test
+ fun testStressSuspendCancellable() {
+ stress { job ->
+ suspendCancellableCoroutine { cont ->
+ job.invokeOnCompletion { cont.resume(Unit) }
+ }
+ }
+ }
+
+ @Test
+ fun testStressSuspendCancellableReusable() {
+ stress { job ->
+ suspendCancellableCoroutineReusable { cont ->
+ job.invokeOnCompletion { cont.resume(Unit) }
+ }
+ }
+ }
+
+ private fun stress(join: suspend (Job) -> Unit) {
+ expect(1)
+ repeat(nRepeats) { index ->
assertFailsWith<TestException> {
runBlocking {
// launch in background
val job = launch(Dispatchers.Default) {
throw TestException("OK") // crash
}
- assertFailsWith<CancellationException> {
- job.join()
+ try {
+ join(job)
+ error("Should not complete successfully")
+ } catch (e: CancellationException) {
+ // must always crash with cancellation exception
+ expect(2 + index)
+ } catch (e: Throwable) {
+ error("Unexpected exception", e)
}
}
}
}
+ finish(2 + nRepeats)
}
}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/jvm/test/RejectedExecutionTest.kt b/kotlinx-coroutines-core/jvm/test/RejectedExecutionTest.kt
new file mode 100644
index 0000000..7f6d6b6
--- /dev/null
+++ b/kotlinx-coroutines-core/jvm/test/RejectedExecutionTest.kt
@@ -0,0 +1,171 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines
+
+import kotlinx.coroutines.flow.*
+import kotlinx.coroutines.internal.*
+import kotlinx.coroutines.scheduling.*
+import org.junit.*
+import org.junit.Test
+import java.util.concurrent.*
+import kotlin.test.*
+
+class RejectedExecutionTest : TestBase() {
+ private val threadName = "RejectedExecutionTest"
+ private val executor = RejectingExecutor()
+
+ @After
+ fun tearDown() {
+ executor.shutdown()
+ executor.awaitTermination(10, TimeUnit.SECONDS)
+ }
+
+ @Test
+ fun testRejectOnLaunch() = runTest {
+ expect(1)
+ val job = launch(executor.asCoroutineDispatcher()) {
+ expectUnreached()
+ }
+ assertEquals(1, executor.submittedTasks)
+ assertTrue(job.isCancelled)
+ finish(2)
+ }
+
+ @Test
+ fun testRejectOnLaunchAtomic() = runTest {
+ expect(1)
+ val job = launch(executor.asCoroutineDispatcher(), start = CoroutineStart.ATOMIC) {
+ expect(2)
+ assertEquals(true, coroutineContext[Job]?.isCancelled)
+ assertIoThread() // was rejected on start, but start was atomic
+ }
+ assertEquals(1, executor.submittedTasks)
+ job.join()
+ finish(3)
+ }
+
+ @Test
+ fun testRejectOnWithContext() = runTest {
+ expect(1)
+ assertFailsWith<CancellationException> {
+ withContext(executor.asCoroutineDispatcher()) {
+ expectUnreached()
+ }
+ }
+ assertEquals(1, executor.submittedTasks)
+ finish(2)
+ }
+
+ @Test
+ fun testRejectOnResumeInContext() = runTest {
+ expect(1)
+ executor.acceptTasks = 1 // accept one task
+ assertFailsWith<CancellationException> {
+ withContext(executor.asCoroutineDispatcher()) {
+ expect(2)
+ assertExecutorThread()
+ try {
+ withContext(Dispatchers.Default) {
+ expect(3)
+ assertDefaultDispatcherThread()
+ // We have to wait until caller executor thread had already suspended (if not running task),
+ // so that we resume back to it a new task is posted
+ executor.awaitNotRunningTask()
+ expect(4)
+ assertDefaultDispatcherThread()
+ }
+ // cancelled on resume back
+ } finally {
+ expect(5)
+ assertIoThread()
+ }
+ expectUnreached()
+ }
+ }
+ assertEquals(2, executor.submittedTasks)
+ finish(6)
+ }
+
+ @Test
+ fun testRejectOnDelay() = runTest {
+ if (!removeFutureOnCancel(executor)) return@runTest // Skip this test on old JDKs
+ expect(1)
+ executor.acceptTasks = 1 // accept one task
+ assertFailsWith<CancellationException> {
+ withContext(executor.asCoroutineDispatcher()) {
+ expect(2)
+ assertExecutorThread()
+ try {
+ delay(10) // cancelled
+ } finally {
+ // Since it was cancelled on attempt to delay, it still stays on the same thread
+ assertExecutorThread()
+ }
+ expectUnreached()
+ }
+ }
+ assertEquals(2, executor.submittedTasks)
+ finish(3)
+ }
+
+ @Test
+ fun testRejectWithTimeout() = runTest {
+ if (!removeFutureOnCancel(executor)) return@runTest // Skip this test on old JDKs
+ expect(1)
+ executor.acceptTasks = 1 // accept one task
+ assertFailsWith<CancellationException> {
+ withContext(executor.asCoroutineDispatcher()) {
+ expect(2)
+ assertExecutorThread()
+ withTimeout(1000) {
+ expect(3) // atomic entry into the block (legacy behavior, it seem to be Ok with way)
+ assertEquals(true, coroutineContext[Job]?.isCancelled) // but the job is already cancelled
+ }
+ expectUnreached()
+ }
+ }
+ assertEquals(2, executor.submittedTasks)
+ finish(4)
+ }
+
+ private inner class RejectingExecutor : ScheduledThreadPoolExecutor(1, { r -> Thread(r, threadName) }) {
+ var acceptTasks = 0
+ var submittedTasks = 0
+ val runningTask = MutableStateFlow(false)
+
+ override fun schedule(command: Runnable, delay: Long, unit: TimeUnit): ScheduledFuture<*> {
+ submittedTasks++
+ if (submittedTasks > acceptTasks) throw RejectedExecutionException()
+ val wrapper = Runnable {
+ runningTask.value = true
+ try {
+ command.run()
+ } finally {
+ runningTask.value = false
+ }
+ }
+ return super.schedule(wrapper, delay, unit)
+ }
+
+ suspend fun awaitNotRunningTask() = runningTask.first { !it }
+ }
+
+ private fun assertExecutorThread() {
+ val thread = Thread.currentThread()
+ if (!thread.name.startsWith(threadName)) error("Not an executor thread: $thread")
+ }
+
+ private fun assertDefaultDispatcherThread() {
+ val thread = Thread.currentThread()
+ if (thread !is CoroutineScheduler.Worker) error("Not a thread from Dispatchers.Default: $thread")
+ assertEquals(CoroutineScheduler.WorkerState.CPU_ACQUIRED, thread.state)
+ }
+
+ private fun assertIoThread() {
+ val thread = Thread.currentThread()
+ if (thread !is CoroutineScheduler.Worker) error("Not a thread from Dispatchers.IO: $thread")
+ assertEquals(CoroutineScheduler.WorkerState.BLOCKING, thread.state)
+ }
+}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/jvm/test/ReusableCancellableContinuationTest.kt b/kotlinx-coroutines-core/jvm/test/ReusableCancellableContinuationTest.kt
index 892a2a6..56f1e28 100644
--- a/kotlinx-coroutines-core/jvm/test/ReusableCancellableContinuationTest.kt
+++ b/kotlinx-coroutines-core/jvm/test/ReusableCancellableContinuationTest.kt
@@ -11,15 +11,14 @@
import kotlin.test.*
class ReusableCancellableContinuationTest : TestBase() {
-
@Test
fun testReusable() = runTest {
- testContinuationsCount(10, 1, ::suspendAtomicCancellableCoroutineReusable)
+ testContinuationsCount(10, 1, ::suspendCancellableCoroutineReusable)
}
@Test
fun testRegular() = runTest {
- testContinuationsCount(10, 10, ::suspendAtomicCancellableCoroutine)
+ testContinuationsCount(10, 10, ::suspendCancellableCoroutine)
}
private suspend inline fun CoroutineScope.testContinuationsCount(
@@ -51,7 +50,7 @@
fun testCancelledOnClaimedCancel() = runTest {
expect(1)
try {
- suspendAtomicCancellableCoroutineReusable<Unit> {
+ suspendCancellableCoroutineReusable<Unit> {
it.cancel()
}
expectUnreached()
@@ -65,7 +64,7 @@
expect(1)
// Bind child at first
var continuation: Continuation<*>? = null
- suspendAtomicCancellableCoroutineReusable<Unit> {
+ suspendCancellableCoroutineReusable<Unit> {
expect(2)
continuation = it
launch { // Attach to the parent, avoid fast path
@@ -77,13 +76,16 @@
ensureActive()
// Verify child was bound
FieldWalker.assertReachableCount(1, coroutineContext[Job]) { it === continuation }
- suspendAtomicCancellableCoroutineReusable<Unit> {
- expect(5)
- coroutineContext[Job]!!.cancel()
- it.resume(Unit)
+ try {
+ suspendCancellableCoroutineReusable<Unit> {
+ expect(5)
+ coroutineContext[Job]!!.cancel()
+ it.resume(Unit) // will not dispatch, will get CancellationException
+ }
+ } catch (e: CancellationException) {
+ assertFalse(isActive)
+ finish(6)
}
- assertFalse(isActive)
- finish(6)
}
@Test
@@ -93,7 +95,7 @@
launch {
cont!!.resumeWith(Result.success(Unit))
}
- suspendAtomicCancellableCoroutineReusable<Unit> {
+ suspendCancellableCoroutineReusable<Unit> {
cont = it
}
ensureActive()
@@ -108,7 +110,7 @@
launch { // Attach to the parent, avoid fast path
cont!!.resumeWith(Result.success(Unit))
}
- suspendAtomicCancellableCoroutine<Unit> {
+ suspendCancellableCoroutine<Unit> {
cont = it
}
ensureActive()
@@ -121,7 +123,7 @@
expect(1)
var cont: Continuation<*>? = null
try {
- suspendAtomicCancellableCoroutineReusable<Unit> {
+ suspendCancellableCoroutineReusable<Unit> {
cont = it
it.cancel()
}
@@ -137,7 +139,7 @@
val currentJob = coroutineContext[Job]!!
expect(1)
// Bind child at first
- suspendAtomicCancellableCoroutineReusable<Unit> {
+ suspendCancellableCoroutineReusable<Unit> {
expect(2)
// Attach to the parent, avoid fast path
launch {
@@ -153,15 +155,23 @@
assertFalse(isActive)
// Child detached
FieldWalker.assertReachableCount(0, currentJob) { it is CancellableContinuation<*> }
- suspendAtomicCancellableCoroutineReusable<Unit> { it.resume(Unit) }
- suspendAtomicCancellableCoroutineReusable<Unit> { it.resume(Unit) }
- FieldWalker.assertReachableCount(0, currentJob) { it is CancellableContinuation<*> }
-
+ expect(5)
try {
- suspendAtomicCancellableCoroutineReusable<Unit> {}
+ // Resume is non-atomic, so it throws cancellation exception
+ suspendCancellableCoroutineReusable<Unit> {
+ expect(6) // but the code inside the block is executed
+ it.resume(Unit)
+ }
} catch (e: CancellationException) {
FieldWalker.assertReachableCount(0, currentJob) { it is CancellableContinuation<*> }
- finish(5)
+ expect(7)
+ }
+ try {
+ // No resume -- still cancellation exception
+ suspendCancellableCoroutineReusable<Unit> {}
+ } catch (e: CancellationException) {
+ FieldWalker.assertReachableCount(0, currentJob) { it is CancellableContinuation<*> }
+ finish(8)
}
}
diff --git a/kotlinx-coroutines-core/jvm/test/RunInterruptibleStressTest.kt b/kotlinx-coroutines-core/jvm/test/RunInterruptibleStressTest.kt
index 79251bb..701b958 100644
--- a/kotlinx-coroutines-core/jvm/test/RunInterruptibleStressTest.kt
+++ b/kotlinx-coroutines-core/jvm/test/RunInterruptibleStressTest.kt
@@ -9,25 +9,29 @@
import java.util.concurrent.atomic.*
import kotlin.test.*
+/**
+ * Stress test for [runInterruptible].
+ * It does not pass on JDK 1.6 on Windows: [Thread.sleep] times out without being interrupted despite the
+ * fact that thread interruption flag is set.
+ */
class RunInterruptibleStressTest : TestBase() {
-
@get:Rule
val dispatcher = ExecutorRule(4)
- private val REPEAT_TIMES = 1000 * stressTestMultiplier
+ private val repeatTimes = 1000 * stressTestMultiplier
@Test
- fun testStress() = runBlocking {
- val interruptLeak = AtomicBoolean(false)
+ fun testStress() = runTest {
val enterCount = AtomicInteger(0)
val interruptedCount = AtomicInteger(0)
- repeat(REPEAT_TIMES) {
+ repeat(repeatTimes) {
val job = launch(dispatcher) {
try {
runInterruptible {
enterCount.incrementAndGet()
try {
- Thread.sleep(Long.MAX_VALUE)
+ Thread.sleep(10_000)
+ error("Sleep was not interrupted, Thread.isInterrupted=${Thread.currentThread().isInterrupted}")
} catch (e: InterruptedException) {
interruptedCount.incrementAndGet()
throw e
@@ -36,19 +40,17 @@
} catch (e: CancellationException) {
// Expected
} finally {
- interruptLeak.set(interruptLeak.get() || Thread.currentThread().isInterrupted)
+ assertFalse(Thread.currentThread().isInterrupted, "Interrupt flag should not leak")
}
}
// Add dispatch delay
val cancelJob = launch(dispatcher) {
job.cancel()
}
-
- job.start()
joinAll(job, cancelJob)
}
-
- assertFalse(interruptLeak.get())
+ println("Entered runInterruptible ${enterCount.get()} times")
+ assertTrue(enterCount.get() > 0) // ensure timing is Ok and we don't cancel it all prematurely
assertEquals(enterCount.get(), interruptedCount.get())
}
}
diff --git a/kotlinx-coroutines-core/jvm/test/TestBase.kt b/kotlinx-coroutines-core/jvm/test/TestBase.kt
index bf462cc..17238e8 100644
--- a/kotlinx-coroutines-core/jvm/test/TestBase.kt
+++ b/kotlinx-coroutines-core/jvm/test/TestBase.kt
@@ -69,6 +69,8 @@
throw makeError(message, cause)
}
+ public fun hasError() = error.get() != null
+
private fun makeError(message: Any, cause: Throwable? = null): IllegalStateException =
IllegalStateException(message.toString(), cause).also {
setError(it)
@@ -107,7 +109,7 @@
* Asserts that this line is never executed.
*/
public actual fun expectUnreached() {
- error("Should not be reached")
+ error("Should not be reached, current action index is ${actionIndex.get()}")
}
/**
diff --git a/kotlinx-coroutines-core/jvm/test/channels/BroadcastChannelMultiReceiveStressTest.kt b/kotlinx-coroutines-core/jvm/test/channels/BroadcastChannelMultiReceiveStressTest.kt
index 54ba7b6..2e73b24 100644
--- a/kotlinx-coroutines-core/jvm/test/channels/BroadcastChannelMultiReceiveStressTest.kt
+++ b/kotlinx-coroutines-core/jvm/test/channels/BroadcastChannelMultiReceiveStressTest.kt
@@ -48,8 +48,9 @@
launch(pool + CoroutineName("Sender")) {
var i = 0L
while (isActive) {
- broadcast.send(++i)
- sentTotal.set(i) // set sentTotal only if `send` was not cancelled
+ i++
+ broadcast.send(i) // could be cancelled
+ sentTotal.set(i) // only was for it if it was not cancelled
}
}
val receivers = mutableListOf<Job>()
@@ -88,10 +89,8 @@
try {
withTimeout(5000) {
receivers.forEachIndexed { index, receiver ->
- if (lastReceived[index].get() == total)
- receiver.cancel()
- else
- receiver.join()
+ if (lastReceived[index].get() >= total) receiver.cancel()
+ receiver.join()
}
}
} catch (e: Exception) {
@@ -112,7 +111,7 @@
check(i == last + 1) { "Last was $last, got $i" }
receivedTotal.incrementAndGet()
lastReceived[receiverIndex].set(i)
- return i == stopOnReceive.get()
+ return i >= stopOnReceive.get()
}
private suspend fun doReceive(channel: ReceiveChannel<Long>, receiverIndex: Int) {
diff --git a/kotlinx-coroutines-core/jvm/test/channels/ChannelAtomicCancelStressTest.kt b/kotlinx-coroutines-core/jvm/test/channels/ChannelAtomicCancelStressTest.kt
deleted file mode 100644
index 6556888..0000000
--- a/kotlinx-coroutines-core/jvm/test/channels/ChannelAtomicCancelStressTest.kt
+++ /dev/null
@@ -1,156 +0,0 @@
-/*
- * Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
- */
-
-package kotlinx.coroutines.channels
-
-import kotlinx.coroutines.*
-import kotlinx.coroutines.selects.*
-import org.junit.After
-import org.junit.Test
-import org.junit.runner.*
-import org.junit.runners.*
-import kotlin.random.Random
-import java.util.concurrent.atomic.*
-import kotlin.test.*
-
-/**
- * Tests cancel atomicity for channel send & receive operations, including their select versions.
- */
-@RunWith(Parameterized::class)
-class ChannelAtomicCancelStressTest(private val kind: TestChannelKind) : TestBase() {
- companion object {
- @Parameterized.Parameters(name = "{0}")
- @JvmStatic
- fun params(): Collection<Array<Any>> = TestChannelKind.values().map { arrayOf<Any>(it) }
- }
-
- private val TEST_DURATION = 1000L * stressTestMultiplier
-
- private val dispatcher = newFixedThreadPoolContext(2, "ChannelAtomicCancelStressTest")
- private val scope = CoroutineScope(dispatcher)
-
- private val channel = kind.create()
- private val senderDone = Channel<Boolean>(1)
- private val receiverDone = Channel<Boolean>(1)
-
- private var lastSent = 0
- private var lastReceived = 0
-
- private var stoppedSender = 0
- private var stoppedReceiver = 0
-
- private var missedCnt = 0
- private var dupCnt = 0
-
- val failed = AtomicReference<Throwable>()
-
- lateinit var sender: Job
- lateinit var receiver: Job
-
- @After
- fun tearDown() {
- dispatcher.close()
- }
-
- fun fail(e: Throwable) = failed.compareAndSet(null, e)
-
- private inline fun cancellable(done: Channel<Boolean>, block: () -> Unit) {
- try {
- block()
- } finally {
- if (!done.offer(true))
- fail(IllegalStateException("failed to offer to done channel"))
- }
- }
-
- @Test
- fun testAtomicCancelStress() = runBlocking {
- println("--- ChannelAtomicCancelStressTest $kind")
- val deadline = System.currentTimeMillis() + TEST_DURATION
- launchSender()
- launchReceiver()
- while (System.currentTimeMillis() < deadline && failed.get() == null) {
- when (Random.nextInt(3)) {
- 0 -> { // cancel & restart sender
- stopSender()
- launchSender()
- }
- 1 -> { // cancel & restart receiver
- stopReceiver()
- launchReceiver()
- }
- 2 -> yield() // just yield (burn a little time)
- }
- }
- stopSender()
- stopReceiver()
- println(" Sent $lastSent ints to channel")
- println(" Received $lastReceived ints from channel")
- println(" Stopped sender $stoppedSender times")
- println("Stopped receiver $stoppedReceiver times")
- println(" Missed $missedCnt ints")
- println(" Duplicated $dupCnt ints")
- failed.get()?.let { throw it }
- assertEquals(0, dupCnt)
- if (!kind.isConflated) {
- assertEquals(0, missedCnt)
- assertEquals(lastSent, lastReceived)
- }
- }
-
- private fun launchSender() {
- sender = scope.launch(start = CoroutineStart.ATOMIC) {
- cancellable(senderDone) {
- var counter = 0
- while (true) {
- val trySend = lastSent + 1
- when (Random.nextInt(2)) {
- 0 -> channel.send(trySend)
- 1 -> select { channel.onSend(trySend) {} }
- else -> error("cannot happen")
- }
- lastSent = trySend // update on success
- when {
- // must artificially slow down LINKED_LIST sender to avoid overwhelming receiver and going OOM
- kind == TestChannelKind.LINKED_LIST -> while (lastSent > lastReceived + 100) yield()
- // yield periodically to check cancellation on conflated channels
- kind.isConflated -> if (counter++ % 100 == 0) yield()
- }
- }
- }
- }
- }
-
- private suspend fun stopSender() {
- stoppedSender++
- sender.cancel()
- senderDone.receive()
- }
-
- private fun launchReceiver() {
- receiver = scope.launch(start = CoroutineStart.ATOMIC) {
- cancellable(receiverDone) {
- while (true) {
- val received = when (Random.nextInt(2)) {
- 0 -> channel.receive()
- 1 -> select { channel.onReceive { it } }
- else -> error("cannot happen")
- }
- val expected = lastReceived + 1
- if (received > expected)
- missedCnt++
- if (received < expected)
- dupCnt++
- lastReceived = received
- }
- }
- }
- }
-
- private suspend fun stopReceiver() {
- stoppedReceiver++
- receiver.cancel()
- receiverDone.receive()
- }
-}
diff --git a/kotlinx-coroutines-core/jvm/test/channels/ChannelCancelUndeliveredElementStressTest.kt b/kotlinx-coroutines-core/jvm/test/channels/ChannelCancelUndeliveredElementStressTest.kt
new file mode 100644
index 0000000..76713aa
--- /dev/null
+++ b/kotlinx-coroutines-core/jvm/test/channels/ChannelCancelUndeliveredElementStressTest.kt
@@ -0,0 +1,102 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.channels
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.selects.*
+import java.util.concurrent.atomic.*
+import kotlin.random.*
+import kotlin.test.*
+
+class ChannelCancelUndeliveredElementStressTest : TestBase() {
+ private val repeatTimes = 10_000 * stressTestMultiplier
+
+ // total counters
+ private var sendCnt = 0
+ private var offerFailedCnt = 0
+ private var receivedCnt = 0
+ private var undeliveredCnt = 0
+
+ // last operation
+ private var lastReceived = 0
+ private var dSendCnt = 0
+ private var dSendExceptionCnt = 0
+ private var dOfferFailedCnt = 0
+ private var dReceivedCnt = 0
+ private val dUndeliveredCnt = AtomicInteger()
+
+ @Test
+ fun testStress() = runTest {
+ repeat(repeatTimes) {
+ val channel = Channel<Int>(1) { dUndeliveredCnt.incrementAndGet() }
+ val j1 = launch(Dispatchers.Default) {
+ sendOne(channel) // send first
+ sendOne(channel) // send second
+ }
+ val j2 = launch(Dispatchers.Default) {
+ receiveOne(channel) // receive one element from the channel
+ channel.cancel() // cancel the channel
+ }
+
+ joinAll(j1, j2)
+
+ // All elements must be either received or undelivered (IN every run)
+ if (dSendCnt - dOfferFailedCnt != dReceivedCnt + dUndeliveredCnt.get()) {
+ println(" Send: $dSendCnt")
+ println("Send Exception: $dSendExceptionCnt")
+ println(" Offer failed: $dOfferFailedCnt")
+ println(" Received: $dReceivedCnt")
+ println(" Undelivered: ${dUndeliveredCnt.get()}")
+ error("Failed")
+ }
+ offerFailedCnt += dOfferFailedCnt
+ receivedCnt += dReceivedCnt
+ undeliveredCnt += dUndeliveredCnt.get()
+ // clear for next run
+ dSendCnt = 0
+ dSendExceptionCnt = 0
+ dOfferFailedCnt = 0
+ dReceivedCnt = 0
+ dUndeliveredCnt.set(0)
+ }
+ // Stats
+ println(" Send: $sendCnt")
+ println(" Offer failed: $offerFailedCnt")
+ println(" Received: $receivedCnt")
+ println(" Undelivered: $undeliveredCnt")
+ assertEquals(sendCnt - offerFailedCnt, receivedCnt + undeliveredCnt)
+ }
+
+ private suspend fun sendOne(channel: Channel<Int>) {
+ dSendCnt++
+ val i = ++sendCnt
+ try {
+ when (Random.nextInt(2)) {
+ 0 -> channel.send(i)
+ 1 -> if (!channel.offer(i)) {
+ dOfferFailedCnt++
+ }
+ }
+ } catch(e: Throwable) {
+ assertTrue(e is CancellationException) // the only exception possible in this test
+ dSendExceptionCnt++
+ throw e
+ }
+ }
+
+ private suspend fun receiveOne(channel: Channel<Int>) {
+ val received = when (Random.nextInt(3)) {
+ 0 -> channel.receive()
+ 1 -> channel.receiveOrNull() ?: error("Cannot be closed yet")
+ 2 -> select {
+ channel.onReceive { it }
+ }
+ else -> error("Cannot happen")
+ }
+ assertTrue(received > lastReceived)
+ dReceivedCnt++
+ lastReceived = received
+ }
+}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/jvm/test/channels/ChannelSendReceiveStressTest.kt b/kotlinx-coroutines-core/jvm/test/channels/ChannelSendReceiveStressTest.kt
index 00c5a60..f414c33 100644
--- a/kotlinx-coroutines-core/jvm/test/channels/ChannelSendReceiveStressTest.kt
+++ b/kotlinx-coroutines-core/jvm/test/channels/ChannelSendReceiveStressTest.kt
@@ -35,7 +35,7 @@
private val maxBuffer = 10_000 // artificial limit for LinkedListChannel
- val channel = kind.create()
+ val channel = kind.create<Int>()
private val sendersCompleted = AtomicInteger()
private val receiversCompleted = AtomicInteger()
private val dupes = AtomicInteger()
diff --git a/kotlinx-coroutines-core/jvm/test/channels/ChannelUndeliveredElementStressTest.kt b/kotlinx-coroutines-core/jvm/test/channels/ChannelUndeliveredElementStressTest.kt
new file mode 100644
index 0000000..1188329
--- /dev/null
+++ b/kotlinx-coroutines-core/jvm/test/channels/ChannelUndeliveredElementStressTest.kt
@@ -0,0 +1,255 @@
+/*
+ * Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.channels
+
+import kotlinx.atomicfu.*
+import kotlinx.coroutines.*
+import kotlinx.coroutines.selects.*
+import org.junit.After
+import org.junit.Test
+import org.junit.runner.*
+import org.junit.runners.*
+import kotlin.random.Random
+import kotlin.test.*
+
+/**
+ * Tests resource transfer via channel send & receive operations, including their select versions,
+ * using `onUndeliveredElement` to detect lost resources and close them properly.
+ */
+@RunWith(Parameterized::class)
+class ChannelUndeliveredElementStressTest(private val kind: TestChannelKind) : TestBase() {
+ companion object {
+ @Parameterized.Parameters(name = "{0}")
+ @JvmStatic
+ fun params(): Collection<Array<Any>> =
+ TestChannelKind.values()
+ .filter { !it.viaBroadcast }
+ .map { arrayOf<Any>(it) }
+ }
+
+ private val iterationDurationMs = 100L
+ private val testIterations = 20 * stressTestMultiplier // 2 sec
+
+ private val dispatcher = newFixedThreadPoolContext(2, "ChannelAtomicCancelStressTest")
+ private val scope = CoroutineScope(dispatcher)
+
+ private val channel = kind.create<Data> { it.failedToDeliver() }
+ private val senderDone = Channel<Boolean>(1)
+ private val receiverDone = Channel<Boolean>(1)
+
+ @Volatile
+ private var lastReceived = -1L
+
+ private var stoppedSender = 0L
+ private var stoppedReceiver = 0L
+
+ private var sentCnt = 0L // total number of send attempts
+ private var receivedCnt = 0L // actually received successfully
+ private var dupCnt = 0L // duplicates (should never happen)
+ private val failedToDeliverCnt = atomic(0L) // out of sent
+
+ private val modulo = 1 shl 25
+ private val mask = (modulo - 1).toLong()
+ private val sentStatus = ItemStatus() // 1 - send norm, 2 - send select, +2 - did not throw exception
+ private val receivedStatus = ItemStatus() // 1-6 received
+ private val failedStatus = ItemStatus() // 1 - failed
+
+ lateinit var sender: Job
+ lateinit var receiver: Job
+
+ @After
+ fun tearDown() {
+ dispatcher.close()
+ }
+
+ private inline fun cancellable(done: Channel<Boolean>, block: () -> Unit) {
+ try {
+ block()
+ } finally {
+ if (!done.offer(true))
+ error(IllegalStateException("failed to offer to done channel"))
+ }
+ }
+
+ @Test
+ fun testAtomicCancelStress() = runBlocking {
+ println("=== ChannelAtomicCancelStressTest $kind")
+ var nextIterationTime = System.currentTimeMillis() + iterationDurationMs
+ var iteration = 0
+ launchSender()
+ launchReceiver()
+ while (!hasError()) {
+ if (System.currentTimeMillis() >= nextIterationTime) {
+ nextIterationTime += iterationDurationMs
+ iteration++
+ verify(iteration)
+ if (iteration % 10 == 0) printProgressSummary(iteration)
+ if (iteration >= testIterations) break
+ launchSender()
+ launchReceiver()
+ }
+ when (Random.nextInt(3)) {
+ 0 -> { // cancel & restart sender
+ stopSender()
+ launchSender()
+ }
+ 1 -> { // cancel & restart receiver
+ stopReceiver()
+ launchReceiver()
+ }
+ 2 -> yield() // just yield (burn a little time)
+ }
+ }
+ }
+
+ private suspend fun verify(iteration: Int) {
+ stopSender()
+ drainReceiver()
+ stopReceiver()
+ try {
+ assertEquals(0, dupCnt)
+ assertEquals(sentCnt - failedToDeliverCnt.value, receivedCnt)
+ } catch (e: Throwable) {
+ printProgressSummary(iteration)
+ printErrorDetails()
+ throw e
+ }
+ sentStatus.clear()
+ receivedStatus.clear()
+ failedStatus.clear()
+ }
+
+ private fun printProgressSummary(iteration: Int) {
+ println("--- ChannelAtomicCancelStressTest $kind -- $iteration of $testIterations")
+ println(" Sent $sentCnt times to channel")
+ println(" Received $receivedCnt times from channel")
+ println(" Failed to deliver ${failedToDeliverCnt.value} times")
+ println(" Stopped sender $stoppedSender times")
+ println(" Stopped receiver $stoppedReceiver times")
+ println(" Duplicated $dupCnt deliveries")
+ }
+
+ private fun printErrorDetails() {
+ val min = minOf(sentStatus.min, receivedStatus.min, failedStatus.min)
+ val max = maxOf(sentStatus.max, receivedStatus.max, failedStatus.max)
+ for (x in min..max) {
+ val sentCnt = if (sentStatus[x] != 0) 1 else 0
+ val receivedCnt = if (receivedStatus[x] != 0) 1 else 0
+ val failedToDeliverCnt = failedStatus[x]
+ if (sentCnt - failedToDeliverCnt != receivedCnt) {
+ println("!!! Error for value $x: " +
+ "sentStatus=${sentStatus[x]}, " +
+ "receivedStatus=${receivedStatus[x]}, " +
+ "failedStatus=${failedStatus[x]}"
+ )
+ }
+ }
+ }
+
+
+ private fun launchSender() {
+ sender = scope.launch(start = CoroutineStart.ATOMIC) {
+ cancellable(senderDone) {
+ var counter = 0
+ while (true) {
+ val trySendData = Data(sentCnt++)
+ val sendMode = Random.nextInt(2) + 1
+ sentStatus[trySendData.x] = sendMode
+ when (sendMode) {
+ 1 -> channel.send(trySendData)
+ 2 -> select<Unit> { channel.onSend(trySendData) {} }
+ else -> error("cannot happen")
+ }
+ sentStatus[trySendData.x] = sendMode + 2
+ when {
+ // must artificially slow down LINKED_LIST sender to avoid overwhelming receiver and going OOM
+ kind == TestChannelKind.LINKED_LIST -> while (sentCnt > lastReceived + 100) yield()
+ // yield periodically to check cancellation on conflated channels
+ kind.isConflated -> if (counter++ % 100 == 0) yield()
+ }
+ }
+ }
+ }
+ }
+
+ private suspend fun stopSender() {
+ stoppedSender++
+ sender.cancel()
+ senderDone.receive()
+ }
+
+ private fun launchReceiver() {
+ receiver = scope.launch(start = CoroutineStart.ATOMIC) {
+ cancellable(receiverDone) {
+ while (true) {
+ val receiveMode = Random.nextInt(6) + 1
+ val receivedData = when (receiveMode) {
+ 1 -> channel.receive()
+ 2 -> select { channel.onReceive { it } }
+ 3 -> channel.receiveOrNull() ?: error("Should not be closed")
+ 4 -> select { channel.onReceiveOrNull { it ?: error("Should not be closed") } }
+ 5 -> channel.receiveOrClosed().value
+ 6 -> {
+ val iterator = channel.iterator()
+ check(iterator.hasNext()) { "Should not be closed" }
+ iterator.next()
+ }
+ else -> error("cannot happen")
+ }
+ receivedCnt++
+ val received = receivedData.x
+ if (received <= lastReceived)
+ dupCnt++
+ lastReceived = received
+ receivedStatus[received] = receiveMode
+ }
+ }
+ }
+ }
+
+ private suspend fun drainReceiver() {
+ while (!channel.isEmpty) yield() // burn time until receiver gets it all
+ }
+
+ private suspend fun stopReceiver() {
+ stoppedReceiver++
+ receiver.cancel()
+ receiverDone.receive()
+ }
+
+ private inner class Data(val x: Long) {
+ private val failedToDeliver = atomic(false)
+
+ fun failedToDeliver() {
+ check(failedToDeliver.compareAndSet(false, true)) { "onUndeliveredElement notified twice" }
+ failedToDeliverCnt.incrementAndGet()
+ failedStatus[x] = 1
+ }
+ }
+
+ inner class ItemStatus {
+ private val a = ByteArray(modulo)
+ private val _min = atomic(Long.MAX_VALUE)
+ private val _max = atomic(-1L)
+
+ val min: Long get() = _min.value
+ val max: Long get() = _max.value
+
+ operator fun set(x: Long, value: Int) {
+ a[(x and mask).toInt()] = value.toByte()
+ _min.update { y -> minOf(x, y) }
+ _max.update { y -> maxOf(x, y) }
+ }
+
+ operator fun get(x: Long): Int = a[(x and mask).toInt()].toInt()
+
+ fun clear() {
+ if (_max.value < 0) return
+ for (x in _min.value.._max.value) a[(x and mask).toInt()] = 0
+ _min.value = Long.MAX_VALUE
+ _max.value = -1L
+ }
+ }
+}
diff --git a/kotlinx-coroutines-core/jvm/test/channels/ChannelsConsumeTest.kt b/kotlinx-coroutines-core/jvm/test/channels/ChannelsConsumeTest.kt
deleted file mode 100644
index cb19b36..0000000
--- a/kotlinx-coroutines-core/jvm/test/channels/ChannelsConsumeTest.kt
+++ /dev/null
@@ -1,908 +0,0 @@
-/*
- * Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
- */
-
-@file:Suppress("DEPRECATION")
-
-package kotlinx.coroutines.channels
-
-import kotlinx.coroutines.*
-import kotlin.coroutines.*
-import kotlin.test.*
-
-/**
- * Tests that various operators on channels properly consume (close) their source channels.
- */
-class ChannelsConsumeTest : TestBase() {
- private val sourceList = (1..10).toList()
-
- // test source with numbers 1..10
- private fun CoroutineScope.testSource() = produce(NonCancellable) {
- for (i in sourceList) {
- send(i)
- }
- }
-
- @Test
- fun testConsume() {
- checkTerminal {
- consume {
- assertEquals(1, receive())
- }
- }
- }
-
- @Test
- fun testConsumeEach() {
- checkTerminal {
- var sum = 0
- consumeEach { sum += it }
- assertEquals(55, sum)
- }
- }
-
- @Test
- fun testConsumeEachIndexed() {
- checkTerminal {
- var sum = 0
- consumeEachIndexed { (index, i) -> sum += index * i }
- assertEquals(330, sum)
- }
- }
-
- @Test
- fun testElementAt() {
- checkTerminal {
- assertEquals(2, elementAt(1))
- }
- checkTerminal(expected = { it is IndexOutOfBoundsException }) {
- elementAt(10)
- }
- }
-
- @Test
- fun testElementAtOrElse() {
- checkTerminal {
- assertEquals(3, elementAtOrElse(2) { error("Cannot happen") })
- }
- checkTerminal {
- assertEquals(-23, elementAtOrElse(10) { -23 })
- }
- }
-
- @Test
- fun testElementOrNull() {
- checkTerminal {
- assertEquals(4, elementAtOrNull(3))
- }
- checkTerminal {
- assertNull(elementAtOrNull(10))
- }
- }
-
- @Test
- fun testFind() {
- checkTerminal {
- assertEquals(3, find { it % 3 == 0 })
- }
- }
-
- @Test
- fun testFindLast() {
- checkTerminal {
- assertEquals(9, findLast { it % 3 == 0 })
- }
- }
-
- @Test
- fun testFirst() {
- checkTerminal {
- assertEquals(1, first())
- }
- }
-
- @Test
- fun testFirstPredicate() {
- checkTerminal {
- assertEquals(3, first { it % 3 == 0 })
- }
- checkTerminal(expected = { it is NoSuchElementException }) {
- first { it > 10 }
- }
- }
-
- @Test
- fun testFirstOrNull() {
- checkTerminal {
- assertEquals(1, firstOrNull())
- }
- }
-
- @Test
- fun testFirstOrNullPredicate() {
- checkTerminal {
- assertEquals(3, firstOrNull { it % 3 == 0 })
- }
- checkTerminal {
- assertNull(firstOrNull { it > 10 })
- }
- }
-
- @Test
- fun testIndexOf() {
- checkTerminal {
- assertEquals(2, indexOf(3))
- }
- checkTerminal {
- assertEquals(-1, indexOf(11))
- }
- }
-
- @Test
- fun testIndexOfFirst() {
- checkTerminal {
- assertEquals(2, indexOfFirst { it % 3 == 0 })
- }
- checkTerminal {
- assertEquals(-1, indexOfFirst { it > 10 })
- }
- }
-
- @Test
- fun testIndexOfLast() {
- checkTerminal {
- assertEquals(8, indexOfLast { it % 3 == 0 })
- }
- checkTerminal {
- assertEquals(-1, indexOfLast { it > 10 })
- }
- }
-
- @Test
- fun testLast() {
- checkTerminal {
- assertEquals(10, last())
- }
- }
-
- @Test
- fun testLastPredicate() {
- checkTerminal {
- assertEquals(9, last { it % 3 == 0 })
- }
- checkTerminal(expected = { it is NoSuchElementException }) {
- last { it > 10 }
- }
- }
-
- @Test
- fun testLastIndexOf() {
- checkTerminal {
- assertEquals(8, lastIndexOf(9))
- }
- }
-
- @Test
- fun testLastOrNull() {
- checkTerminal {
- assertEquals(10, lastOrNull())
- }
- }
-
- @Test
- fun testLastOrNullPredicate() {
- checkTerminal {
- assertEquals(9, lastOrNull { it % 3 == 0 })
- }
- checkTerminal {
- assertNull(lastOrNull { it > 10 })
- }
- }
-
- @Test
- fun testSingle() {
- checkTerminal(expected = { it is IllegalArgumentException }) {
- single()
- }
- }
-
- @Test
- fun testSinglePredicate() {
- checkTerminal {
- assertEquals(7, single { it % 7 == 0 })
- }
- checkTerminal(expected = { it is IllegalArgumentException }) {
- single { it % 3 == 0 }
- }
- checkTerminal(expected = { it is NoSuchElementException }) {
- single { it > 10 }
- }
- }
-
- @Test
- fun testSingleOrNull() {
- checkTerminal {
- assertNull(singleOrNull())
- }
- }
-
- @Test
- fun testSingleOrNullPredicate() {
- checkTerminal {
- assertEquals(7, singleOrNull { it % 7 == 0 })
- }
- checkTerminal {
- assertNull(singleOrNull { it % 3 == 0 })
- }
- checkTerminal {
- assertNull(singleOrNull { it > 10 })
- }
- }
-
- @Test
- fun testDrop() {
- checkTransform(sourceList.drop(3)) {
- drop(3)
- }
- }
-
- @Test
- fun testDropWhile() {
- checkTransform(sourceList.dropWhile { it < 4}) {
- dropWhile { it < 4 }
- }
- }
-
- @Test
- fun testFilter() {
- checkTransform(sourceList.filter { it % 2 == 0 }) {
- filter { it % 2 == 0 }
- }
- }
-
- @Test
- fun testFilterIndexed() {
- checkTransform(sourceList.filterIndexed { index, _ -> index % 2 == 0 }) {
- filterIndexed { index, _ -> index % 2 == 0 }
- }
- }
-
- @Test
- fun testFilterIndexedToCollection() {
- checkTerminal {
- val list = mutableListOf<Int>()
- filterIndexedTo(list) { index, _ -> index % 2 == 0 }
- assertEquals(listOf(1, 3, 5, 7, 9), list)
- }
- }
-
- @Test
- fun testFilterIndexedToChannel() {
- checkTerminal {
- val channel = Channel<Int>()
- val result = GlobalScope.async { channel.toList() }
- filterIndexedTo(channel) { index, _ -> index % 2 == 0 }
- channel.close()
- assertEquals(listOf(1, 3, 5, 7, 9), result.await())
- }
- }
-
- @Test
- fun testFilterNot() {
- checkTransform(sourceList.filterNot { it % 2 == 0 }) {
- filterNot { it % 2 == 0 }
- }
- }
-
- @Test
- fun testFilterNotNullToCollection() {
- checkTerminal {
- val list = mutableListOf<Int>()
- filterNotNullTo(list)
- assertEquals((1..10).toList(), list)
- }
- }
-
- @Test
- fun testFilterNotNullToChannel() {
- checkTerminal {
- val channel = Channel<Int>()
- val result = GlobalScope.async { channel.toList() }
- filterNotNullTo(channel)
- channel.close()
- assertEquals((1..10).toList(), result.await())
- }
- }
-
- @Test
- fun testFilterNotToCollection() {
- checkTerminal {
- val list = mutableListOf<Int>()
- filterNotTo(list) { it % 2 == 0 }
- assertEquals(listOf(1, 3, 5, 7, 9), list)
- }
- }
-
- @Test
- fun testFilterNotToChannel() {
- checkTerminal {
- val channel = Channel<Int>()
- val result = GlobalScope.async { channel.toList() }
- filterNotTo(channel) { it % 2 == 0 }
- channel.close()
- assertEquals(listOf(1, 3, 5, 7, 9), result.await())
- }
- }
-
- @Test
- fun testFilterToCollection() {
- checkTerminal {
- val list = mutableListOf<Int>()
- filterTo(list) { it % 2 == 0 }
- assertEquals(listOf(2, 4, 6, 8, 10), list)
- }
- }
-
- @Test
- fun testFilterToChannel() {
- checkTerminal {
- val channel = Channel<Int>()
- val result = GlobalScope.async { channel.toList() }
- filterTo(channel) { it % 2 == 0 }
- channel.close()
- assertEquals(listOf(2, 4, 6, 8, 10), result.await())
- }
- }
-
- @Test
- fun testTake() {
- checkTransform(sourceList.take(3)) {
- take(3)
- }
- }
-
- @Test
- fun testTakeWhile() {
- checkTransform(sourceList.takeWhile { it < 4 }) {
- takeWhile { it < 4 }
- }
- }
-
- @Test
- fun testAssociate() {
- checkTerminal {
- assertEquals(sourceList.associate { it to it.toString() }, associate { it to it.toString() })
- }
- }
-
- @Test
- fun testAssociateBy() {
- checkTerminal {
- assertEquals(sourceList.associateBy { it.toString() }, associateBy { it.toString() })
- }
- }
-
- @Test
- fun testAssociateByTwo() {
- checkTerminal {
- assertEquals(sourceList.associateBy({ it.toString() }, { it + 1}), associateBy({ it.toString() }, { it + 1}))
- }
- }
-
- @Test
- fun testAssociateByToMap() {
- checkTerminal {
- val map = mutableMapOf<String, Int>()
- associateByTo(map) { it.toString() }
- assertEquals(sourceList.associateBy { it.toString() }, map)
- }
- }
-
- @Test
- fun testAssociateByTwoToMap() {
- checkTerminal {
- val map = mutableMapOf<String, Int>()
- associateByTo(map, { it.toString() }, { it + 1})
- assertEquals(sourceList.associateBy({ it.toString() }, { it + 1}), map)
- }
- }
-
- @Test
- fun testAssociateToMap() {
- checkTerminal {
- val map = mutableMapOf<Int, String>()
- associateTo(map) { it to it.toString() }
- assertEquals(sourceList.associate { it to it.toString() }, map)
- }
- }
-
- @Test
- fun testToChannel() {
- checkTerminal {
- val channel = Channel<Int>()
- val result = GlobalScope.async { channel.toList() }
- toChannel(channel)
- channel.close()
- assertEquals(sourceList, result.await())
- }
- }
-
- @Test
- fun testToCollection() {
- checkTerminal {
- val list = mutableListOf<Int>()
- toCollection(list)
- assertEquals(sourceList, list)
- }
- }
-
- @Test
- fun testToList() {
- checkTerminal {
- val list = toList()
- assertEquals(sourceList, list)
- }
- }
-
- @Test
- fun testToMap() {
- checkTerminal {
- val map = map { it to it.toString() }.toMap()
- assertEquals(sourceList.map { it to it.toString() }.toMap(), map)
- }
- }
-
- @Test
- fun testToMapWithMap() {
- checkTerminal {
- val map = mutableMapOf<Int, String>()
- map { it to it.toString() }.toMap(map)
- assertEquals(sourceList.map { it to it.toString() }.toMap(), map)
- }
- }
-
- @Test
- fun testToMutableList() {
- checkTerminal {
- val list = toMutableList()
- assertEquals(sourceList, list)
- }
- }
-
- @Test
- fun testToSet() {
- checkTerminal {
- val set = toSet()
- assertEquals(sourceList.toSet(), set)
- }
- }
-
- @Test
- fun testFlatMap() {
- checkTransform(sourceList.flatMap { listOf("A$it", "B$it") }) {
- flatMap {
- GlobalScope.produce(coroutineContext) {
- send("A$it")
- send("B$it")
- }
- }
- }
- }
-
- @Test
- fun testGroupBy() {
- checkTerminal {
- val map = groupBy { it % 2 }
- assertEquals(sourceList.groupBy { it % 2 }, map)
- }
- }
-
- @Test
- fun testGroupByTwo() {
- checkTerminal {
- val map = groupBy({ it % 2 }, { it.toString() })
- assertEquals(sourceList.groupBy({ it % 2 }, { it.toString() }), map)
- }
- }
-
- @Test
- fun testGroupByTo() {
- checkTerminal {
- val map = mutableMapOf<Int, MutableList<Int>>()
- groupByTo(map) { it % 2 }
- assertEquals(sourceList.groupBy { it % 2 }, map)
- }
- }
-
- @Test
- fun testGroupByToTwo() {
- checkTerminal {
- val map = mutableMapOf<Int, MutableList<String>>()
- groupByTo(map, { it % 2 }, { it.toString() })
- assertEquals(sourceList.groupBy({ it % 2 }, { it.toString() }), map)
- }
- }
-
- @Test
- fun testMap() {
- checkTransform(sourceList.map { it.toString() }) {
- map { it.toString() }
- }
- }
-
- @Test
- fun testMapIndexed() {
- checkTransform(sourceList.mapIndexed { index, v -> "$index$v" }) {
- mapIndexed { index, v -> "$index$v" }
- }
- }
-
- @Test
- fun testMapIndexedNotNull() {
- checkTransform(sourceList.mapIndexedNotNull { index, v -> "$index$v".takeIf { v % 2 == 0 } }) {
- mapIndexedNotNull { index, v -> "$index$v".takeIf { v % 2 == 0 } }
- }
- }
-
- @Test
- fun testMapIndexedNotNullToCollection() {
- checkTerminal {
- val list = mutableListOf<String>()
- mapIndexedNotNullTo(list) { index, v -> "$index$v".takeIf { v % 2 == 0 } }
- assertEquals(sourceList.mapIndexedNotNull { index, v -> "$index$v".takeIf { v % 2 == 0 } }, list)
- }
- }
-
- @Test
- fun testMapIndexedNotNullToChannel() {
- checkTerminal {
- val channel = Channel<String>()
- val result = GlobalScope.async { channel.toList() }
- mapIndexedNotNullTo(channel) { index, v -> "$index$v".takeIf { v % 2 == 0 } }
- channel.close()
- assertEquals(sourceList.mapIndexedNotNull { index, v -> "$index$v".takeIf { v % 2 == 0 } }, result.await())
- }
- }
-
- @Test
- fun testMapIndexedToCollection() {
- checkTerminal {
- val list = mutableListOf<String>()
- mapIndexedTo(list) { index, v -> "$index$v" }
- assertEquals(sourceList.mapIndexed { index, v -> "$index$v" }, list)
- }
- }
-
- @Test
- fun testMapIndexedToChannel() {
- checkTerminal {
- val channel = Channel<String>()
- val result = GlobalScope.async { channel.toList() }
- mapIndexedTo(channel) { index, v -> "$index$v" }
- channel.close()
- assertEquals(sourceList.mapIndexed { index, v -> "$index$v" }, result.await())
- }
- }
-
- @Test
- fun testMapNotNull() {
- checkTransform(sourceList.mapNotNull { (it + 3).takeIf { it % 2 == 0 } }) {
- mapNotNull { (it + 3).takeIf { it % 2 == 0 } }
- }
- }
-
- @Test
- fun testMapNotNullToCollection() {
- checkTerminal {
- val list = mutableListOf<Int>()
- mapNotNullTo(list) { (it + 3).takeIf { it % 2 == 0 } }
- assertEquals(sourceList.mapNotNull { (it + 3).takeIf { it % 2 == 0 } }, list)
- }
- }
-
- @Test
- fun testMapNotNullToChannel() {
- checkTerminal {
- val channel = Channel<Int>()
- val result = GlobalScope.async { channel.toList() }
- mapNotNullTo(channel) { (it + 3).takeIf { it % 2 == 0 } }
- channel.close()
- assertEquals(sourceList.mapNotNull { (it + 3).takeIf { it % 2 == 0 } }, result.await())
- }
- }
-
- @Test
- fun testMapToCollection() {
- checkTerminal {
- val list = mutableListOf<Int>()
- mapTo(list) { it + 3 }
- assertEquals(sourceList.map { it + 3 }, list)
- }
- }
-
- @Test
- fun testMapToChannel() {
- checkTerminal {
- val channel = Channel<Int>()
- val result = GlobalScope.async { channel.toList() }
- mapTo(channel) { it + 3 }
- channel.close()
- assertEquals(sourceList.map { it + 3 }, result.await())
- }
- }
-
- @Test
- fun testWithIndex() {
- checkTransform(sourceList.asSequence().withIndex().toList()) {
- withIndex()
- }
- }
-
- @Test
- fun testDistinctBy() {
- checkTransform(sourceList.distinctBy { it / 2 }) {
- distinctBy { it / 2 }
- }
- }
-
- @Test
- fun testToMutableSet() {
- checkTerminal {
- val set = toMutableSet()
- assertEquals(sourceList.toSet(), set)
- }
- }
-
- @Test
- fun testAll() {
- checkTerminal {
- val all = all { it < 11 }
- assertEquals(sourceList.all { it < 11 }, all)
- }
- }
-
- @Test
- fun testAny() {
- checkTerminal {
- val any = any()
- assertEquals(sourceList.any(), any)
- }
- }
-
- @Test
- fun testAnyPredicate() {
- checkTerminal {
- val any = any { it % 3 == 0 }
- assertEquals(sourceList.any { it % 3 == 0 }, any)
- }
- }
-
- @Test
- fun testCount() {
- checkTerminal {
- val c = count()
- assertEquals(sourceList.count(), c)
- }
- }
-
- @Test
- fun testCountPredicate() {
- checkTerminal {
- val c = count { it % 3 == 0 }
- assertEquals(sourceList.count { it % 3 == 0 }, c)
- }
- }
-
- @Test
- fun testFold() {
- checkTerminal {
- val c = fold(1) { a, b -> a + b }
- assertEquals(sourceList.fold(1) { a, b -> a + b }, c)
- }
- }
-
- @Test
- fun testFoldIndexed() {
- checkTerminal {
- val c = foldIndexed(1) { i, a, b -> i * a + b }
- assertEquals(sourceList.foldIndexed(1) { i, a, b -> i * a + b }, c)
- }
- }
-
- @Test
- fun testMaxBy() {
- checkTerminal {
- val c = maxBy { it % 3 }
- assertEquals(sourceList.maxBy { it % 3 }, c)
- }
- }
-
- @Test
- fun testMaxWith() {
- checkTerminal {
- val c = maxWith(compareBy { it % 3 })
- assertEquals(sourceList.maxWith(compareBy { it % 3 }), c)
- }
- }
-
- @Test
- fun testMinBy() {
- checkTerminal {
- val c = maxBy { it % 3 }
- assertEquals(sourceList.maxBy { it % 3 }, c)
- }
- }
-
- @Test
- fun testMinWith() {
- checkTerminal {
- val c = maxWith(compareBy { it % 3 })
- assertEquals(sourceList.maxWith(compareBy { it % 3 }), c)
- }
- }
-
- @Test
- fun testNone() {
- checkTerminal {
- val none = none()
- assertEquals(sourceList.none(), none)
- }
- }
-
- @Test
- fun testNonePredicate() {
- checkTerminal {
- val none = none { it > 10 }
- assertEquals(sourceList.none { it > 10 }, none)
- }
- }
-
- @Test
- fun testReduce() {
- checkTerminal {
- val c = reduce { a, b -> a + b }
- assertEquals(sourceList.reduce { a, b -> a + b }, c)
- }
- }
-
- @Test
- fun testReduceIndexed() {
- checkTerminal {
- val c = reduceIndexed { i, a, b -> i * a + b }
- assertEquals(sourceList.reduceIndexed { i, a, b -> i * a + b }, c)
- }
- }
-
- @Test
- fun testSubBy() {
- checkTerminal {
- val c = sumBy { it }
- assertEquals(sourceList.sumBy { it }, c)
- }
- }
-
- @Test
- fun testSubByDouble() {
- checkTerminal {
- val c = sumByDouble { it.toDouble() }
- assertEquals(sourceList.sumByDouble { it.toDouble() }, c)
- }
- }
-
- @Test
- fun testPartition() {
- checkTerminal {
- val pair = partition { it % 2 == 0 }
- assertEquals(sourceList.partition { it % 2 == 0 }, pair)
- }
- }
-
- @Test
- fun testZip() {
- val expect = sourceList.zip(sourceList) { a, b -> a + 2 * b }
- checkTransform(expect) {
- with(CoroutineScope(coroutineContext)) {
- zip(testSource()) { a, b -> a + 2*b }
- }
- }
- checkTransform(expect) {
- with(CoroutineScope(coroutineContext)) {
- testSource().zip(this@checkTransform) { a, b -> a + 2*b }
- }
- }
- }
-
- // ------------------
-
- private fun checkTerminal(
- expected: ((Throwable?) -> Unit)? = null,
- terminal: suspend ReceiveChannel<Int>.() -> Unit
- ) {
- checkTerminalCompletion(expected, terminal)
- checkTerminalCancellation(expected, terminal)
- }
-
- private fun checkTerminalCompletion(
- expected: ((Throwable?) -> Unit)? = null,
- terminal: suspend ReceiveChannel<Int>.() -> Unit
- ) {
- val src = runBlocking {
- val src = testSource()
- try {
- // terminal operation
- terminal(src)
- // source must be cancelled at the end of terminal op
- if (expected != null) error("Exception was expected")
- } catch (e: Throwable) {
- if (expected == null) throw e
- expected(e)
- }
- src
- }
- assertTrue(src.isClosedForReceive, "Source must be closed")
- }
-
- private fun checkTerminalCancellation(
- expected: ((Throwable?) -> Unit)? = null,
- terminal: suspend ReceiveChannel<Int>.() -> Unit
- ) {
- val src = runBlocking {
- val src = testSource()
- // terminal operation in a separate async context started until the first suspension
- val d = async(NonCancellable, start = CoroutineStart.UNDISPATCHED) {
- terminal(src)
- }
- // then cancel it
- d.cancel()
- // and try to get it's result
- try {
- d.await()
- } catch (e: CancellationException) {
- // ok -- was cancelled
- } catch (e: Throwable) {
- // if threw a different exception -- must be an expected one
- if (expected == null) throw e
- expected(e)
- }
- src
- }
- // source must be cancelled at the end of terminal op even if it was cancelled while in process
- assertTrue(src.isClosedForReceive, "Source must be closed")
- }
-
- private fun <R> checkTransform(
- expect: List<R>,
- transform: suspend ReceiveChannel<Int>.() -> ReceiveChannel<R>
- ) {
- // check for varying number of received elements from the channel
- for (nReceive in 0..expect.size) {
- checkTransform(nReceive, expect, transform)
- }
- }
-
- private fun <R> checkTransform(
- nReceive: Int,
- expect: List<R>,
- transform: suspend ReceiveChannel<Int>.() -> ReceiveChannel<R>
- ) {
- val src = runBlocking {
- val src = testSource()
- // transform
- val res = transform(src)
- // receive nReceive elements from the result
- repeat(nReceive) { i ->
- assertEquals(expect[i], res.receive())
- }
- if (nReceive < expect.size) {
- // then cancel
- res.cancel()
- } else {
- // then check that result is closed
- assertNull(res.receiveOrNull(), "Result has unexpected values")
- }
- src
- }
- // source must be cancelled when runBlocking processes all the scheduled stuff
- assertTrue(src.isClosedForReceive, "Source must be closed")
- }
-}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/jvm/test/channels/ChannelsJvmTest.kt b/kotlinx-coroutines-core/jvm/test/channels/ChannelsJvmTest.kt
index 7613f04..da20f0c 100644
--- a/kotlinx-coroutines-core/jvm/test/channels/ChannelsJvmTest.kt
+++ b/kotlinx-coroutines-core/jvm/test/channels/ChannelsJvmTest.kt
@@ -14,7 +14,9 @@
fun testBlocking() {
val ch = Channel<Int>()
val sum = GlobalScope.async {
- ch.sumBy { it }
+ var sum = 0
+ ch.consumeEach { sum += it }
+ sum
}
repeat(10) {
ch.sendBlocking(it)
diff --git a/kotlinx-coroutines-core/jvm/test/channels/InvokeOnCloseStressTest.kt b/kotlinx-coroutines-core/jvm/test/channels/InvokeOnCloseStressTest.kt
index 864a0b4..888522c 100644
--- a/kotlinx-coroutines-core/jvm/test/channels/InvokeOnCloseStressTest.kt
+++ b/kotlinx-coroutines-core/jvm/test/channels/InvokeOnCloseStressTest.kt
@@ -39,7 +39,7 @@
private suspend fun runStressTest(kind: TestChannelKind) {
repeat(iterations) {
val counter = AtomicInteger(0)
- val channel = kind.create()
+ val channel = kind.create<Int>()
val latch = CountDownLatch(1)
val j1 = async {
diff --git a/kotlinx-coroutines-core/jvm/test/channels/SimpleSendReceiveJvmTest.kt b/kotlinx-coroutines-core/jvm/test/channels/SimpleSendReceiveJvmTest.kt
index 07c431b..eeddfb5 100644
--- a/kotlinx-coroutines-core/jvm/test/channels/SimpleSendReceiveJvmTest.kt
+++ b/kotlinx-coroutines-core/jvm/test/channels/SimpleSendReceiveJvmTest.kt
@@ -28,7 +28,7 @@
}
}
- val channel = kind.create()
+ val channel = kind.create<Int>()
@Test
fun testSimpleSendReceive() = runBlocking {
diff --git a/kotlinx-coroutines-core/jvm/test/examples/example-delay-01.kt b/kotlinx-coroutines-core/jvm/test/examples/example-delay-01.kt
new file mode 100644
index 0000000..d2a5d53
--- /dev/null
+++ b/kotlinx-coroutines-core/jvm/test/examples/example-delay-01.kt
@@ -0,0 +1,24 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+// This file was automatically generated from Delay.kt by Knit tool. Do not edit.
+package kotlinx.coroutines.examples.exampleDelay01
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+
+fun main() = runBlocking {
+
+flow {
+ emit(1)
+ delay(90)
+ emit(2)
+ delay(90)
+ emit(3)
+ delay(1010)
+ emit(4)
+ delay(1010)
+ emit(5)
+}.debounce(1000)
+.toList().joinToString().let { println(it) } }
diff --git a/kotlinx-coroutines-core/jvm/test/examples/example-delay-02.kt b/kotlinx-coroutines-core/jvm/test/examples/example-delay-02.kt
new file mode 100644
index 0000000..f74422e
--- /dev/null
+++ b/kotlinx-coroutines-core/jvm/test/examples/example-delay-02.kt
@@ -0,0 +1,30 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+// This file was automatically generated from Delay.kt by Knit tool. Do not edit.
+package kotlinx.coroutines.examples.exampleDelay02
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+
+fun main() = runBlocking {
+
+flow {
+ emit(1)
+ delay(90)
+ emit(2)
+ delay(90)
+ emit(3)
+ delay(1010)
+ emit(4)
+ delay(1010)
+ emit(5)
+}.debounce {
+ if (it == 1) {
+ 0L
+ } else {
+ 1000L
+ }
+}
+.toList().joinToString().let { println(it) } }
diff --git a/kotlinx-coroutines-core/jvm/test/examples/example-delay-03.kt b/kotlinx-coroutines-core/jvm/test/examples/example-delay-03.kt
new file mode 100644
index 0000000..edaea74
--- /dev/null
+++ b/kotlinx-coroutines-core/jvm/test/examples/example-delay-03.kt
@@ -0,0 +1,19 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+// This file was automatically generated from Delay.kt by Knit tool. Do not edit.
+package kotlinx.coroutines.examples.exampleDelay03
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+
+fun main() = runBlocking {
+
+flow {
+ repeat(10) {
+ emit(it)
+ delay(110)
+ }
+}.sample(200)
+.toList().joinToString().let { println(it) } }
diff --git a/kotlinx-coroutines-core/jvm/test/examples/example-delay-duration-01.kt b/kotlinx-coroutines-core/jvm/test/examples/example-delay-duration-01.kt
new file mode 100644
index 0000000..a19e6cb
--- /dev/null
+++ b/kotlinx-coroutines-core/jvm/test/examples/example-delay-duration-01.kt
@@ -0,0 +1,26 @@
+@file:OptIn(ExperimentalTime::class)
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+// This file was automatically generated from Delay.kt by Knit tool. Do not edit.
+package kotlinx.coroutines.examples.exampleDelayDuration01
+
+import kotlin.time.*
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+
+fun main() = runBlocking {
+
+flow {
+ emit(1)
+ delay(90.milliseconds)
+ emit(2)
+ delay(90.milliseconds)
+ emit(3)
+ delay(1010.milliseconds)
+ emit(4)
+ delay(1010.milliseconds)
+ emit(5)
+}.debounce(1000.milliseconds)
+.toList().joinToString().let { println(it) } }
diff --git a/kotlinx-coroutines-core/jvm/test/examples/example-delay-duration-02.kt b/kotlinx-coroutines-core/jvm/test/examples/example-delay-duration-02.kt
new file mode 100644
index 0000000..10ba88a
--- /dev/null
+++ b/kotlinx-coroutines-core/jvm/test/examples/example-delay-duration-02.kt
@@ -0,0 +1,32 @@
+@file:OptIn(ExperimentalTime::class)
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+// This file was automatically generated from Delay.kt by Knit tool. Do not edit.
+package kotlinx.coroutines.examples.exampleDelayDuration02
+
+import kotlin.time.*
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+
+fun main() = runBlocking {
+
+flow {
+ emit(1)
+ delay(90.milliseconds)
+ emit(2)
+ delay(90.milliseconds)
+ emit(3)
+ delay(1010.milliseconds)
+ emit(4)
+ delay(1010.milliseconds)
+ emit(5)
+}.debounce {
+ if (it == 1) {
+ 0.milliseconds
+ } else {
+ 1000.milliseconds
+ }
+}
+.toList().joinToString().let { println(it) } }
diff --git a/kotlinx-coroutines-core/jvm/test/examples/example-delay-duration-03.kt b/kotlinx-coroutines-core/jvm/test/examples/example-delay-duration-03.kt
new file mode 100644
index 0000000..5fa980a
--- /dev/null
+++ b/kotlinx-coroutines-core/jvm/test/examples/example-delay-duration-03.kt
@@ -0,0 +1,21 @@
+@file:OptIn(ExperimentalTime::class)
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+// This file was automatically generated from Delay.kt by Knit tool. Do not edit.
+package kotlinx.coroutines.examples.exampleDelayDuration03
+
+import kotlin.time.*
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+
+fun main() = runBlocking {
+
+flow {
+ repeat(10) {
+ emit(it)
+ delay(110.milliseconds)
+ }
+}.sample(200.milliseconds)
+.toList().joinToString().let { println(it) } }
diff --git a/kotlinx-coroutines-core/jvm/test/examples/test/FlowDelayTest.kt b/kotlinx-coroutines-core/jvm/test/examples/test/FlowDelayTest.kt
new file mode 100644
index 0000000..99e72eb
--- /dev/null
+++ b/kotlinx-coroutines-core/jvm/test/examples/test/FlowDelayTest.kt
@@ -0,0 +1,53 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+// This file was automatically generated from Delay.kt by Knit tool. Do not edit.
+package kotlinx.coroutines.examples.test
+
+import kotlinx.coroutines.knit.*
+import org.junit.Test
+
+class FlowDelayTest {
+ @Test
+ fun testExampleDelay01() {
+ test("ExampleDelay01") { kotlinx.coroutines.examples.exampleDelay01.main() }.verifyLines(
+ "3, 4, 5"
+ )
+ }
+
+ @Test
+ fun testExampleDelay02() {
+ test("ExampleDelay02") { kotlinx.coroutines.examples.exampleDelay02.main() }.verifyLines(
+ "1, 3, 4, 5"
+ )
+ }
+
+ @Test
+ fun testExampleDelayDuration01() {
+ test("ExampleDelayDuration01") { kotlinx.coroutines.examples.exampleDelayDuration01.main() }.verifyLines(
+ "3, 4, 5"
+ )
+ }
+
+ @Test
+ fun testExampleDelayDuration02() {
+ test("ExampleDelayDuration02") { kotlinx.coroutines.examples.exampleDelayDuration02.main() }.verifyLines(
+ "1, 3, 4, 5"
+ )
+ }
+
+ @Test
+ fun testExampleDelay03() {
+ test("ExampleDelay03") { kotlinx.coroutines.examples.exampleDelay03.main() }.verifyLines(
+ "1, 3, 5, 7, 9"
+ )
+ }
+
+ @Test
+ fun testExampleDelayDuration03() {
+ test("ExampleDelayDuration03") { kotlinx.coroutines.examples.exampleDelayDuration03.main() }.verifyLines(
+ "1, 3, 5, 7, 9"
+ )
+ }
+}
diff --git a/kotlinx-coroutines-core/jvm/test/flow/OnCompletionInterceptedReleaseTest.kt b/kotlinx-coroutines-core/jvm/test/flow/OnCompletionInterceptedReleaseTest.kt
new file mode 100644
index 0000000..a6268b5
--- /dev/null
+++ b/kotlinx-coroutines-core/jvm/test/flow/OnCompletionInterceptedReleaseTest.kt
@@ -0,0 +1,45 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.flow
+
+import kotlinx.coroutines.*
+import org.junit.Test
+import kotlin.coroutines.*
+import kotlin.test.*
+
+class OnCompletionInterceptedReleaseTest : TestBase() {
+ @Test
+ fun testLeak() = runTest {
+ expect(1)
+ var cont: Continuation<Unit>? = null
+ val interceptor = CountingInterceptor()
+ val job = launch(interceptor, start = CoroutineStart.UNDISPATCHED) {
+ emptyFlow<Int>()
+ .onCompletion { emit(1) }
+ .collect { value ->
+ expect(2)
+ assertEquals(1, value)
+ suspendCoroutine { cont = it }
+ }
+ }
+ cont!!.resume(Unit)
+ assertTrue(job.isCompleted)
+ assertEquals(interceptor.intercepted, interceptor.released)
+ finish(3)
+ }
+
+ class CountingInterceptor : AbstractCoroutineContextElement(ContinuationInterceptor), ContinuationInterceptor {
+ var intercepted = 0
+ var released = 0
+ override fun <T> interceptContinuation(continuation: Continuation<T>): Continuation<T> {
+ intercepted++
+ return Continuation(continuation.context) { continuation.resumeWith(it) }
+ }
+
+ override fun releaseInterceptedContinuation(continuation: Continuation<*>) {
+ released++
+ }
+ }
+}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/jvm/test/flow/SharedFlowStressTest.kt b/kotlinx-coroutines-core/jvm/test/flow/SharedFlowStressTest.kt
new file mode 100644
index 0000000..349b7c8
--- /dev/null
+++ b/kotlinx-coroutines-core/jvm/test/flow/SharedFlowStressTest.kt
@@ -0,0 +1,87 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.flow
+
+import kotlinx.atomicfu.*
+import kotlinx.coroutines.*
+import org.junit.*
+import org.junit.Test
+import kotlin.collections.ArrayList
+import kotlin.test.*
+import kotlin.time.*
+
+@ExperimentalTime
+class SharedFlowStressTest : TestBase() {
+ private val nProducers = 5
+ private val nConsumers = 3
+ private val nSeconds = 3 * stressTestMultiplier
+
+ private lateinit var sf: MutableSharedFlow<Long>
+ private lateinit var view: SharedFlow<Long>
+
+ @get:Rule
+ val producerDispatcher = ExecutorRule(nProducers)
+ @get:Rule
+ val consumerDispatcher = ExecutorRule(nConsumers)
+
+ private val totalProduced = atomic(0L)
+ private val totalConsumed = atomic(0L)
+
+ @Test
+ fun testStressReplay1() =
+ testStress(1, 0)
+
+ @Test
+ fun testStressReplay1ExtraBuffer1() =
+ testStress(1, 1)
+
+ @Test
+ fun testStressReplay2ExtraBuffer1() =
+ testStress(2, 1)
+
+ private fun testStress(replay: Int, extraBufferCapacity: Int) = runTest {
+ sf = MutableSharedFlow(replay, extraBufferCapacity)
+ view = sf.asSharedFlow()
+ val jobs = ArrayList<Job>()
+ jobs += List(nProducers) { producerIndex ->
+ launch(producerDispatcher) {
+ var cur = producerIndex.toLong()
+ while (isActive) {
+ sf.emit(cur)
+ totalProduced.incrementAndGet()
+ cur += nProducers
+ }
+ }
+ }
+ jobs += List(nConsumers) { consumerIndex ->
+ launch(consumerDispatcher) {
+ while (isActive) {
+ view
+ .dropWhile { it % nConsumers != consumerIndex.toLong() }
+ .take(1)
+ .collect {
+ check(it % nConsumers == consumerIndex.toLong())
+ totalConsumed.incrementAndGet()
+ }
+ }
+ }
+ }
+ var lastProduced = 0L
+ var lastConsumed = 0L
+ for (sec in 1..nSeconds) {
+ delay(1.seconds)
+ val produced = totalProduced.value
+ val consumed = totalConsumed.value
+ println("$sec sec: produced = $produced; consumed = $consumed")
+ assertNotEquals(lastProduced, produced)
+ assertNotEquals(lastConsumed, consumed)
+ lastProduced = produced
+ lastConsumed = consumed
+ }
+ jobs.forEach { it.cancel() }
+ jobs.forEach { it.join() }
+ println("total: produced = ${totalProduced.value}; consumed = ${totalConsumed.value}")
+ }
+}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/jvm/test/flow/SharingStressTest.kt b/kotlinx-coroutines-core/jvm/test/flow/SharingStressTest.kt
new file mode 100644
index 0000000..7d346bd
--- /dev/null
+++ b/kotlinx-coroutines-core/jvm/test/flow/SharingStressTest.kt
@@ -0,0 +1,193 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.flow
+
+import kotlinx.coroutines.*
+import org.junit.*
+import org.junit.Test
+import java.util.*
+import java.util.concurrent.atomic.*
+import kotlin.random.*
+import kotlin.test.*
+import kotlin.time.*
+import kotlin.time.TimeSource
+
+@OptIn(ExperimentalTime::class)
+class SharingStressTest : TestBase() {
+ private val testDuration = 1000L * stressTestMultiplier
+ private val nSubscribers = 5
+ private val testStarted = TimeSource.Monotonic.markNow()
+
+ @get:Rule
+ val emitterDispatcher = ExecutorRule(1)
+
+ @get:Rule
+ val subscriberDispatcher = ExecutorRule(nSubscribers)
+
+ @Test
+ public fun testNoReplayLazy() =
+ testStress(0, started = SharingStarted.Lazily)
+
+ @Test
+ public fun testNoReplayWhileSubscribed() =
+ testStress(0, started = SharingStarted.WhileSubscribed())
+
+ @Test
+ public fun testNoReplayWhileSubscribedTimeout() =
+ testStress(0, started = SharingStarted.WhileSubscribed(stopTimeoutMillis = 50L))
+
+ @Test
+ public fun testReplay100WhileSubscribed() =
+ testStress(100, started = SharingStarted.WhileSubscribed())
+
+ @Test
+ public fun testReplay100WhileSubscribedReset() =
+ testStress(100, started = SharingStarted.WhileSubscribed(replayExpirationMillis = 0L))
+
+ @Test
+ public fun testReplay100WhileSubscribedTimeout() =
+ testStress(100, started = SharingStarted.WhileSubscribed(stopTimeoutMillis = 50L))
+
+ @Test
+ public fun testStateLazy() =
+ testStress(1, started = SharingStarted.Lazily)
+
+ @Test
+ public fun testStateWhileSubscribed() =
+ testStress(1, started = SharingStarted.WhileSubscribed())
+
+ @Test
+ public fun testStateWhileSubscribedReset() =
+ testStress(1, started = SharingStarted.WhileSubscribed(replayExpirationMillis = 0L))
+
+ private fun testStress(replay: Int, started: SharingStarted) = runTest {
+ log("-- Stress with replay=$replay, started=$started")
+ val random = Random(1)
+ val emitIndex = AtomicLong()
+ val cancelledEmits = HashSet<Long>()
+ val missingCollects = Collections.synchronizedSet(LinkedHashSet<Long>())
+ // at most one copy of upstream can be running at any time
+ val isRunning = AtomicInteger(0)
+ val upstream = flow {
+ assertEquals(0, isRunning.getAndIncrement())
+ try {
+ while (true) {
+ val value = emitIndex.getAndIncrement()
+ try {
+ emit(value)
+ } catch (e: CancellationException) {
+ // emission was cancelled -> could be missing
+ cancelledEmits.add(value)
+ throw e
+ }
+ }
+ } finally {
+ assertEquals(1, isRunning.getAndDecrement())
+ }
+ }
+ val subCount = MutableStateFlow(0)
+ val sharingJob = Job()
+ val sharingScope = this + emitterDispatcher + sharingJob
+ val usingStateFlow = replay == 1
+ val sharedFlow = if (usingStateFlow)
+ upstream.stateIn(sharingScope, started, 0L)
+ else
+ upstream.shareIn(sharingScope, started, replay)
+ try {
+ val subscribers = ArrayList<SubJob>()
+ withTimeoutOrNull(testDuration) {
+ // start and stop subscribers
+ while (true) {
+ log("Staring $nSubscribers subscribers")
+ repeat(nSubscribers) {
+ subscribers += launchSubscriber(sharedFlow, usingStateFlow, subCount, missingCollects)
+ }
+ // wait until they all subscribed
+ subCount.first { it == nSubscribers }
+ // let them work a bit more & make sure emitter did not hang
+ val fromEmitIndex = emitIndex.get()
+ val waitEmitIndex = fromEmitIndex + 100 // wait until 100 emitted
+ withTimeout(10000) { // wait for at most 10s for something to be emitted
+ do {
+ delay(random.nextLong(50L..100L))
+ } while (emitIndex.get() < waitEmitIndex) // Ok, enough was emitted, wait more if not
+ }
+ // Stop all subscribers and ensure they collected something
+ log("Stopping subscribers (emitted = ${emitIndex.get() - fromEmitIndex})")
+ subscribers.forEach {
+ it.job.cancelAndJoin()
+ assertTrue { it.count > 0 } // something must be collected too
+ }
+ subscribers.clear()
+ log("Intermission")
+ delay(random.nextLong(10L..100L)) // wait a bit before starting them again
+ }
+ }
+ if (!subscribers.isEmpty()) {
+ log("Stopping subscribers")
+ subscribers.forEach { it.job.cancelAndJoin() }
+ }
+ } finally {
+ log("--- Finally: Cancelling sharing job")
+ sharingJob.cancel()
+ }
+ sharingJob.join() // make sure sharing job did not hang
+ log("Emitter was cancelled ${cancelledEmits.size} times")
+ log("Collectors missed ${missingCollects.size} values")
+ for (value in missingCollects) {
+ assertTrue(value in cancelledEmits, "Value $value is missing for no apparent reason")
+ }
+ }
+
+ private fun CoroutineScope.launchSubscriber(
+ sharedFlow: SharedFlow<Long>,
+ usingStateFlow: Boolean,
+ subCount: MutableStateFlow<Int>,
+ missingCollects: MutableSet<Long>
+ ): SubJob {
+ val subJob = SubJob()
+ subJob.job = launch(subscriberDispatcher) {
+ var last = -1L
+ sharedFlow
+ .onSubscription {
+ subCount.increment(1)
+ }
+ .onCompletion {
+ subCount.increment(-1)
+ }
+ .collect { j ->
+ subJob.count++
+ // last must grow sequentially, no jumping or losses
+ if (last == -1L) {
+ last = j
+ } else {
+ val expected = last + 1
+ if (usingStateFlow)
+ assertTrue(expected <= j)
+ else {
+ if (expected != j) {
+ if (j == expected + 1) {
+ // if missing just one -- could be race with cancelled emit
+ missingCollects.add(expected)
+ } else {
+ // broken otherwise
+ assertEquals(expected, j)
+ }
+ }
+ }
+ last = j
+ }
+ }
+ }
+ return subJob
+ }
+
+ private class SubJob {
+ lateinit var job: Job
+ var count = 0L
+ }
+
+ private fun log(msg: String) = println("${testStarted.elapsedNow().toLongMilliseconds()} ms: $msg")
+}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/jvm/test/flow/StateFlowCancellabilityTest.kt b/kotlinx-coroutines-core/jvm/test/flow/StateFlowCancellabilityTest.kt
new file mode 100644
index 0000000..fc4996c
--- /dev/null
+++ b/kotlinx-coroutines-core/jvm/test/flow/StateFlowCancellabilityTest.kt
@@ -0,0 +1,56 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.flow
+
+import kotlinx.coroutines.*
+import java.util.concurrent.*
+import kotlin.test.*
+
+@Suppress("BlockingMethodInNonBlockingContext")
+class StateFlowCancellabilityTest : TestBase() {
+ @Test
+ fun testCancellabilityNoConflation() = runTest {
+ expect(1)
+ val state = MutableStateFlow(0)
+ var subscribed = true
+ var lastReceived = -1
+ val barrier = CyclicBarrier(2)
+ val job = state
+ .onSubscription {
+ subscribed = true
+ barrier.await()
+ }
+ .onEach { i ->
+ when (i) {
+ 0 -> expect(2) // initial value
+ 1 -> expect(3)
+ 2 -> {
+ expect(4)
+ currentCoroutineContext().cancel()
+ }
+ else -> expectUnreached() // shall check for cancellation
+ }
+ lastReceived = i
+ barrier.await()
+ barrier.await()
+ }
+ .launchIn(this + Dispatchers.Default)
+ barrier.await()
+ assertTrue(subscribed) // should have subscribed in the first barrier
+ barrier.await()
+ assertEquals(0, lastReceived) // should get initial value, too
+ for (i in 1..3) { // emit after subscription
+ state.value = i
+ barrier.await() // let it go
+ if (i < 3) {
+ barrier.await() // wait for receive
+ assertEquals(i, lastReceived) // shall receive it
+ }
+ }
+ job.join()
+ finish(5)
+ }
+}
+
diff --git a/kotlinx-coroutines-core/jvm/test/guide/example-cancel-08.kt b/kotlinx-coroutines-core/jvm/test/guide/example-cancel-08.kt
new file mode 100644
index 0000000..e7def13
--- /dev/null
+++ b/kotlinx-coroutines-core/jvm/test/guide/example-cancel-08.kt
@@ -0,0 +1,31 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+// This file was automatically generated from cancellation-and-timeouts.md by Knit tool. Do not edit.
+package kotlinx.coroutines.guide.exampleCancel08
+
+import kotlinx.coroutines.*
+
+var acquired = 0
+
+class Resource {
+ init { acquired++ } // Acquire the resource
+ fun close() { acquired-- } // Release the resource
+}
+
+fun main() {
+ runBlocking {
+ repeat(100_000) { // Launch 100K coroutines
+ launch {
+ val resource = withTimeout(60) { // Timeout of 60 ms
+ delay(50) // Delay for 50 ms
+ Resource() // Acquire a resource and return it from withTimeout block
+ }
+ resource.close() // Release the resource
+ }
+ }
+ }
+ // Outside of runBlocking all coroutines have completed
+ println(acquired) // Print the number of resources still acquired
+}
diff --git a/kotlinx-coroutines-core/jvm/test/guide/example-cancel-09.kt b/kotlinx-coroutines-core/jvm/test/guide/example-cancel-09.kt
new file mode 100644
index 0000000..95424f5
--- /dev/null
+++ b/kotlinx-coroutines-core/jvm/test/guide/example-cancel-09.kt
@@ -0,0 +1,36 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+// This file was automatically generated from cancellation-and-timeouts.md by Knit tool. Do not edit.
+package kotlinx.coroutines.guide.exampleCancel09
+
+import kotlinx.coroutines.*
+
+var acquired = 0
+
+class Resource {
+ init { acquired++ } // Acquire the resource
+ fun close() { acquired-- } // Release the resource
+}
+
+fun main() {
+ runBlocking {
+ repeat(100_000) { // Launch 100K coroutines
+ launch {
+ var resource: Resource? = null // Not acquired yet
+ try {
+ withTimeout(60) { // Timeout of 60 ms
+ delay(50) // Delay for 50 ms
+ resource = Resource() // Store a resource to the variable if acquired
+ }
+ // We can do something else with the resource here
+ } finally {
+ resource?.close() // Release the resource if it was acquired
+ }
+ }
+ }
+ }
+ // Outside of runBlocking all coroutines have completed
+ println(acquired) // Print the number of resources still acquired
+}
diff --git a/kotlinx-coroutines-core/jvm/test/guide/test/BasicsGuideTest.kt b/kotlinx-coroutines-core/jvm/test/guide/test/BasicsGuideTest.kt
index 7fc57c2..ea5003b 100644
--- a/kotlinx-coroutines-core/jvm/test/guide/test/BasicsGuideTest.kt
+++ b/kotlinx-coroutines-core/jvm/test/guide/test/BasicsGuideTest.kt
@@ -5,6 +5,7 @@
// This file was automatically generated from basics.md by Knit tool. Do not edit.
package kotlinx.coroutines.guide.test
+import kotlinx.coroutines.knit.*
import org.junit.Test
class BasicsGuideTest {
diff --git a/kotlinx-coroutines-core/jvm/test/guide/test/CancellationGuideTest.kt b/kotlinx-coroutines-core/jvm/test/guide/test/CancellationGuideTest.kt
index a2e91de..0cff63a 100644
--- a/kotlinx-coroutines-core/jvm/test/guide/test/CancellationGuideTest.kt
+++ b/kotlinx-coroutines-core/jvm/test/guide/test/CancellationGuideTest.kt
@@ -5,6 +5,7 @@
// This file was automatically generated from cancellation-and-timeouts.md by Knit tool. Do not edit.
package kotlinx.coroutines.guide.test
+import kotlinx.coroutines.knit.*
import org.junit.Test
class CancellationGuideTest {
@@ -87,4 +88,11 @@
"Result is null"
)
}
+
+ @Test
+ fun testExampleCancel09() {
+ test("ExampleCancel09") { kotlinx.coroutines.guide.exampleCancel09.main() }.verifyLines(
+ "0"
+ )
+ }
}
diff --git a/kotlinx-coroutines-core/jvm/test/guide/test/ChannelsGuideTest.kt b/kotlinx-coroutines-core/jvm/test/guide/test/ChannelsGuideTest.kt
index 209d439..d15a550 100644
--- a/kotlinx-coroutines-core/jvm/test/guide/test/ChannelsGuideTest.kt
+++ b/kotlinx-coroutines-core/jvm/test/guide/test/ChannelsGuideTest.kt
@@ -5,6 +5,7 @@
// This file was automatically generated from channels.md by Knit tool. Do not edit.
package kotlinx.coroutines.guide.test
+import kotlinx.coroutines.knit.*
import org.junit.Test
class ChannelsGuideTest {
diff --git a/kotlinx-coroutines-core/jvm/test/guide/test/ComposingGuideTest.kt b/kotlinx-coroutines-core/jvm/test/guide/test/ComposingGuideTest.kt
index 50c3fd7..1f9692d 100644
--- a/kotlinx-coroutines-core/jvm/test/guide/test/ComposingGuideTest.kt
+++ b/kotlinx-coroutines-core/jvm/test/guide/test/ComposingGuideTest.kt
@@ -5,6 +5,7 @@
// This file was automatically generated from composing-suspending-functions.md by Knit tool. Do not edit.
package kotlinx.coroutines.guide.test
+import kotlinx.coroutines.knit.*
import org.junit.Test
class ComposingGuideTest {
diff --git a/kotlinx-coroutines-core/jvm/test/guide/test/DispatcherGuideTest.kt b/kotlinx-coroutines-core/jvm/test/guide/test/DispatcherGuideTest.kt
index c0c3241..d6f1c21 100644
--- a/kotlinx-coroutines-core/jvm/test/guide/test/DispatcherGuideTest.kt
+++ b/kotlinx-coroutines-core/jvm/test/guide/test/DispatcherGuideTest.kt
@@ -5,6 +5,7 @@
// This file was automatically generated from coroutine-context-and-dispatchers.md by Knit tool. Do not edit.
package kotlinx.coroutines.guide.test
+import kotlinx.coroutines.knit.*
import org.junit.Test
class DispatcherGuideTest {
diff --git a/kotlinx-coroutines-core/jvm/test/guide/test/ExceptionsGuideTest.kt b/kotlinx-coroutines-core/jvm/test/guide/test/ExceptionsGuideTest.kt
index c42ba31..f34fd3f 100644
--- a/kotlinx-coroutines-core/jvm/test/guide/test/ExceptionsGuideTest.kt
+++ b/kotlinx-coroutines-core/jvm/test/guide/test/ExceptionsGuideTest.kt
@@ -5,6 +5,7 @@
// This file was automatically generated from exception-handling.md by Knit tool. Do not edit.
package kotlinx.coroutines.guide.test
+import kotlinx.coroutines.knit.*
import org.junit.Test
class ExceptionsGuideTest {
diff --git a/kotlinx-coroutines-core/jvm/test/guide/test/FlowGuideTest.kt b/kotlinx-coroutines-core/jvm/test/guide/test/FlowGuideTest.kt
index 7fa9cc8..c7d4a72 100644
--- a/kotlinx-coroutines-core/jvm/test/guide/test/FlowGuideTest.kt
+++ b/kotlinx-coroutines-core/jvm/test/guide/test/FlowGuideTest.kt
@@ -5,6 +5,7 @@
// This file was automatically generated from flow.md by Knit tool. Do not edit.
package kotlinx.coroutines.guide.test
+import kotlinx.coroutines.knit.*
import org.junit.Test
class FlowGuideTest {
diff --git a/kotlinx-coroutines-core/jvm/test/guide/test/SelectGuideTest.kt b/kotlinx-coroutines-core/jvm/test/guide/test/SelectGuideTest.kt
index e3f47b9..55650d4 100644
--- a/kotlinx-coroutines-core/jvm/test/guide/test/SelectGuideTest.kt
+++ b/kotlinx-coroutines-core/jvm/test/guide/test/SelectGuideTest.kt
@@ -5,6 +5,7 @@
// This file was automatically generated from select-expression.md by Knit tool. Do not edit.
package kotlinx.coroutines.guide.test
+import kotlinx.coroutines.knit.*
import org.junit.Test
class SelectGuideTest {
diff --git a/kotlinx-coroutines-core/jvm/test/guide/test/SharedStateGuideTest.kt b/kotlinx-coroutines-core/jvm/test/guide/test/SharedStateGuideTest.kt
index 8d534a0..3162b24 100644
--- a/kotlinx-coroutines-core/jvm/test/guide/test/SharedStateGuideTest.kt
+++ b/kotlinx-coroutines-core/jvm/test/guide/test/SharedStateGuideTest.kt
@@ -5,6 +5,7 @@
// This file was automatically generated from shared-mutable-state-and-concurrency.md by Knit tool. Do not edit.
package kotlinx.coroutines.guide.test
+import kotlinx.coroutines.knit.*
import org.junit.Test
class SharedStateGuideTest {
diff --git a/kotlinx-coroutines-core/jvm/test/internal/ConcurrentWeakMapTest.kt b/kotlinx-coroutines-core/jvm/test/internal/ConcurrentWeakMapTest.kt
index ae4b5fc..e4fa5e9 100644
--- a/kotlinx-coroutines-core/jvm/test/internal/ConcurrentWeakMapTest.kt
+++ b/kotlinx-coroutines-core/jvm/test/internal/ConcurrentWeakMapTest.kt
@@ -12,8 +12,8 @@
class ConcurrentWeakMapTest : TestBase() {
@Test
fun testSimple() {
- val expect = (1..1000).associateWith { it.toString() }
- val m = ConcurrentWeakMap<Int, String>()
+ val expect = (1..1000).associate { it.toString().let { it to it } }
+ val m = ConcurrentWeakMap<String, String>()
// repeat adding/removing a few times
repeat(5) {
assertEquals(0, m.size)
@@ -27,7 +27,7 @@
assertEquals(expect.keys, m.keys)
assertEquals(expect.entries, m.entries)
for ((k, v) in expect) {
- assertEquals(v, m.get(k))
+ assertEquals(v, m[k])
}
assertEquals(expect.size, m.size)
if (it % 2 == 0) {
@@ -38,9 +38,9 @@
m.clear()
}
assertEquals(0, m.size)
- for ((k, v) in expect) {
- assertNull(m.get(k))
+ for ((k, _) in expect) {
+ assertNull(m[k])
}
}
}
-}
\ No newline at end of file
+}
diff --git a/kotlinx-coroutines-core/jvm/test/guide/test/TestUtil.kt b/kotlinx-coroutines-core/jvm/test/knit/TestUtil.kt
similarity index 98%
rename from kotlinx-coroutines-core/jvm/test/guide/test/TestUtil.kt
rename to kotlinx-coroutines-core/jvm/test/knit/TestUtil.kt
index fb1c85b..7eda904 100644
--- a/kotlinx-coroutines-core/jvm/test/guide/test/TestUtil.kt
+++ b/kotlinx-coroutines-core/jvm/test/knit/TestUtil.kt
@@ -1,8 +1,8 @@
/*
- * Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
*/
-package kotlinx.coroutines.guide.test
+package kotlinx.coroutines.knit
import kotlinx.coroutines.*
import kotlinx.coroutines.internal.*
diff --git a/kotlinx-coroutines-core/jvm/test/sync/MutexStressTest.kt b/kotlinx-coroutines-core/jvm/test/sync/MutexStressTest.kt
index 8ecb8fd..bb713b2 100644
--- a/kotlinx-coroutines-core/jvm/test/sync/MutexStressTest.kt
+++ b/kotlinx-coroutines-core/jvm/test/sync/MutexStressTest.kt
@@ -5,6 +5,7 @@
package kotlinx.coroutines.sync
import kotlinx.coroutines.*
+import kotlinx.coroutines.selects.*
import kotlin.test.*
class MutexStressTest : TestBase() {
@@ -26,4 +27,67 @@
jobs.forEach { it.join() }
assertEquals(n * k, shared)
}
+
+ @Test
+ fun stressUnlockCancelRace() = runTest {
+ val n = 10_000 * stressTestMultiplier
+ val mutex = Mutex(true) // create a locked mutex
+ newSingleThreadContext("SemaphoreStressTest").use { pool ->
+ repeat (n) {
+ // Initially, we hold the lock and no one else can `lock`,
+ // otherwise it's a bug.
+ assertTrue(mutex.isLocked)
+ var job1EnteredCriticalSection = false
+ val job1 = launch(start = CoroutineStart.UNDISPATCHED) {
+ mutex.lock()
+ job1EnteredCriticalSection = true
+ mutex.unlock()
+ }
+ // check that `job1` didn't finish the call to `acquire()`
+ assertEquals(false, job1EnteredCriticalSection)
+ val job2 = launch(pool) {
+ mutex.unlock()
+ }
+ // Because `job2` executes in a separate thread, this
+ // cancellation races with the call to `unlock()`.
+ job1.cancelAndJoin()
+ job2.join()
+ assertFalse(mutex.isLocked)
+ mutex.lock()
+ }
+ }
+ }
+
+ @Test
+ fun stressUnlockCancelRaceWithSelect() = runTest {
+ val n = 10_000 * stressTestMultiplier
+ val mutex = Mutex(true) // create a locked mutex
+ newSingleThreadContext("SemaphoreStressTest").use { pool ->
+ repeat (n) {
+ // Initially, we hold the lock and no one else can `lock`,
+ // otherwise it's a bug.
+ assertTrue(mutex.isLocked)
+ var job1EnteredCriticalSection = false
+ val job1 = launch(start = CoroutineStart.UNDISPATCHED) {
+ select<Unit> {
+ mutex.onLock {
+ job1EnteredCriticalSection = true
+ mutex.unlock()
+ }
+ }
+ }
+ // check that `job1` didn't finish the call to `acquire()`
+ assertEquals(false, job1EnteredCriticalSection)
+ val job2 = launch(pool) {
+ mutex.unlock()
+ }
+ // Because `job2` executes in a separate thread, this
+ // cancellation races with the call to `unlock()`.
+ job1.cancelAndJoin()
+ job2.join()
+ assertFalse(mutex.isLocked)
+ mutex.lock()
+ }
+ }
+ }
}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/jvm/test/sync/SemaphoreStressTest.kt b/kotlinx-coroutines-core/jvm/test/sync/SemaphoreStressTest.kt
index 9c77990..374a1e3 100644
--- a/kotlinx-coroutines-core/jvm/test/sync/SemaphoreStressTest.kt
+++ b/kotlinx-coroutines-core/jvm/test/sync/SemaphoreStressTest.kt
@@ -5,7 +5,6 @@
import kotlin.test.assertEquals
class SemaphoreStressTest : TestBase() {
-
@Test
fun stressTestAsMutex() = runBlocking(Dispatchers.Default) {
val n = 10_000 * stressTestMultiplier
@@ -71,14 +70,14 @@
// Initially, we hold the permit and no one else can `acquire`,
// otherwise it's a bug.
assertEquals(0, semaphore.availablePermits)
- var job1_entered_critical_section = false
+ var job1EnteredCriticalSection = false
val job1 = launch(start = CoroutineStart.UNDISPATCHED) {
semaphore.acquire()
- job1_entered_critical_section = true
+ job1EnteredCriticalSection = true
semaphore.release()
}
// check that `job1` didn't finish the call to `acquire()`
- assertEquals(false, job1_entered_critical_section)
+ assertEquals(false, job1EnteredCriticalSection)
val job2 = launch(pool) {
semaphore.release()
}
@@ -91,5 +90,4 @@
}
}
}
-
}
diff --git a/kotlinx-coroutines-core/knit.properties b/kotlinx-coroutines-core/knit.properties
new file mode 100644
index 0000000..93ce87d
--- /dev/null
+++ b/kotlinx-coroutines-core/knit.properties
@@ -0,0 +1,10 @@
+#
+# Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+#
+
+knit.package=kotlinx.coroutines.examples
+knit.dir=jvm/test/examples/
+
+test.package=kotlinx.coroutines.examples.test
+test.dir=jvm/test/examples/test/
+
diff --git a/kotlinx-coroutines-core/native/src/CoroutineContext.kt b/kotlinx-coroutines-core/native/src/CoroutineContext.kt
index bcc7f48..4ec1289 100644
--- a/kotlinx-coroutines-core/native/src/CoroutineContext.kt
+++ b/kotlinx-coroutines-core/native/src/CoroutineContext.kt
@@ -16,8 +16,8 @@
takeEventLoop().dispatch(context, block)
override fun scheduleResumeAfterDelay(timeMillis: Long, continuation: CancellableContinuation<Unit>) =
takeEventLoop().scheduleResumeAfterDelay(timeMillis, continuation)
- override fun invokeOnTimeout(timeMillis: Long, block: Runnable): DisposableHandle =
- takeEventLoop().invokeOnTimeout(timeMillis, block)
+ override fun invokeOnTimeout(timeMillis: Long, block: Runnable, context: CoroutineContext): DisposableHandle =
+ takeEventLoop().invokeOnTimeout(timeMillis, block, context)
actual fun enqueue(task: Runnable): Unit = loopWasShutDown()
}
diff --git a/kotlinx-coroutines-core/native/src/Dispatchers.kt b/kotlinx-coroutines-core/native/src/Dispatchers.kt
index aca1cc0..c06b7c2 100644
--- a/kotlinx-coroutines-core/native/src/Dispatchers.kt
+++ b/kotlinx-coroutines-core/native/src/Dispatchers.kt
@@ -7,24 +7,16 @@
import kotlin.coroutines.*
public actual object Dispatchers {
-
public actual val Default: CoroutineDispatcher = createDefaultDispatcher()
-
public actual val Main: MainCoroutineDispatcher = NativeMainDispatcher(Default)
-
public actual val Unconfined: CoroutineDispatcher get() = kotlinx.coroutines.Unconfined // Avoid freezing
}
private class NativeMainDispatcher(val delegate: CoroutineDispatcher) : MainCoroutineDispatcher() {
-
override val immediate: MainCoroutineDispatcher
get() = throw UnsupportedOperationException("Immediate dispatching is not supported on Native")
-
override fun dispatch(context: CoroutineContext, block: Runnable) = delegate.dispatch(context, block)
-
override fun isDispatchNeeded(context: CoroutineContext): Boolean = delegate.isDispatchNeeded(context)
-
override fun dispatchYield(context: CoroutineContext, block: Runnable) = delegate.dispatchYield(context, block)
-
override fun toString(): String = toStringInternalImpl() ?: delegate.toString()
}
diff --git a/kotlinx-coroutines-core/native/src/EventLoop.kt b/kotlinx-coroutines-core/native/src/EventLoop.kt
index d6c6525..b397d6f 100644
--- a/kotlinx-coroutines-core/native/src/EventLoop.kt
+++ b/kotlinx-coroutines-core/native/src/EventLoop.kt
@@ -4,6 +4,7 @@
package kotlinx.coroutines
+import kotlin.coroutines.*
import kotlin.system.*
internal actual abstract class EventLoopImplPlatform: EventLoop() {
@@ -13,7 +14,7 @@
}
internal class EventLoopImpl: EventLoopImplBase() {
- override fun invokeOnTimeout(timeMillis: Long, block: Runnable): DisposableHandle =
+ override fun invokeOnTimeout(timeMillis: Long, block: Runnable, context: CoroutineContext): DisposableHandle =
scheduleInvokeOnTimeout(timeMillis, block)
}
diff --git a/kotlinx-coroutines-core/native/src/WorkerMain.native.kt b/kotlinx-coroutines-core/native/src/WorkerMain.native.kt
new file mode 100644
index 0000000..84cc9f4
--- /dev/null
+++ b/kotlinx-coroutines-core/native/src/WorkerMain.native.kt
@@ -0,0 +1,8 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines
+
+// It is used in the main sources of native-mt branch
+internal expect inline fun workerMain(block: () -> Unit)
diff --git a/kotlinx-coroutines-core/native/src/internal/LinkedList.kt b/kotlinx-coroutines-core/native/src/internal/LinkedList.kt
index 9657830..99ab042 100644
--- a/kotlinx-coroutines-core/native/src/internal/LinkedList.kt
+++ b/kotlinx-coroutines-core/native/src/internal/LinkedList.kt
@@ -124,6 +124,8 @@
return null
}
+ actual open fun onRemoved(affected: Node) {}
+
actual final override fun prepare(op: AtomicOp<*>): Any? {
val affected = affectedNode
val failure = failure(affected)
diff --git a/kotlinx-coroutines-core/native/src/internal/LocalAtomics.kt b/kotlinx-coroutines-core/native/src/internal/LocalAtomics.kt
new file mode 100644
index 0000000..398cb63
--- /dev/null
+++ b/kotlinx-coroutines-core/native/src/internal/LocalAtomics.kt
@@ -0,0 +1,20 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.internal
+
+import kotlinx.atomicfu.*
+
+internal actual class LocalAtomicInt actual constructor(value: Int) {
+
+ private val iRef = atomic(value)
+
+ actual fun set(value: Int) {
+ iRef.value = value
+ }
+
+ actual fun get(): Int = iRef.value
+
+ actual fun decrementAndGet(): Int = iRef.decrementAndGet()
+}
diff --git a/kotlinx-coroutines-core/native/test/WorkerTest.kt b/kotlinx-coroutines-core/native/test/WorkerTest.kt
index 84aceda..d6b5fad 100644
--- a/kotlinx-coroutines-core/native/test/WorkerTest.kt
+++ b/kotlinx-coroutines-core/native/test/WorkerTest.kt
@@ -1,5 +1,5 @@
/*
- * Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
*/
package kotlinx.coroutines
@@ -19,6 +19,7 @@
delay(1)
}
}.result
+ worker.requestTermination()
}
@Test
@@ -31,5 +32,6 @@
}.join()
}
}.result
+ worker.requestTermination()
}
}
diff --git a/kotlinx-coroutines-core/nativeDarwin/src/WorkerMain.kt b/kotlinx-coroutines-core/nativeDarwin/src/WorkerMain.kt
new file mode 100644
index 0000000..3445cb9
--- /dev/null
+++ b/kotlinx-coroutines-core/nativeDarwin/src/WorkerMain.kt
@@ -0,0 +1,13 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines
+
+import kotlinx.cinterop.*
+
+internal actual inline fun workerMain(block: () -> Unit) {
+ autoreleasepool {
+ block()
+ }
+}
diff --git a/kotlinx-coroutines-core/nativeDarwin/test/Launcher.kt b/kotlinx-coroutines-core/nativeDarwin/test/Launcher.kt
new file mode 100644
index 0000000..78ed765
--- /dev/null
+++ b/kotlinx-coroutines-core/nativeDarwin/test/Launcher.kt
@@ -0,0 +1,28 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines
+
+import platform.CoreFoundation.*
+import kotlin.native.concurrent.*
+import kotlin.native.internal.test.*
+import kotlin.system.*
+
+// This is a separate entry point for tests in background
+fun mainBackground(args: Array<String>) {
+ val worker = Worker.start(name = "main-background")
+ worker.execute(TransferMode.SAFE, { args.freeze() }) {
+ val result = testLauncherEntryPoint(it)
+ exitProcess(result)
+ }
+ CFRunLoopRun()
+ error("CFRunLoopRun should never return")
+}
+
+// This is a separate entry point for tests with leak checker
+fun mainNoExit(args: Array<String>) {
+ workerMain { // autoreleasepool to make sure interop objects are properly freed
+ testLauncherEntryPoint(args)
+ }
+}
\ No newline at end of file
diff --git a/kotlinx-coroutines-core/nativeOther/src/WorkerMain.kt b/kotlinx-coroutines-core/nativeOther/src/WorkerMain.kt
new file mode 100644
index 0000000..cac0530
--- /dev/null
+++ b/kotlinx-coroutines-core/nativeOther/src/WorkerMain.kt
@@ -0,0 +1,7 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines
+
+internal actual inline fun workerMain(block: () -> Unit) = block()
diff --git a/kotlinx-coroutines-core/nativeOther/test/Launcher.kt b/kotlinx-coroutines-core/nativeOther/test/Launcher.kt
new file mode 100644
index 0000000..feddd4c
--- /dev/null
+++ b/kotlinx-coroutines-core/nativeOther/test/Launcher.kt
@@ -0,0 +1,23 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines
+
+import kotlin.native.concurrent.*
+import kotlin.native.internal.test.*
+import kotlin.system.*
+
+// This is a separate entry point for tests in background
+fun mainBackground(args: Array<String>) {
+ val worker = Worker.start(name = "main-background")
+ worker.execute(TransferMode.SAFE, { args.freeze() }) {
+ val result = testLauncherEntryPoint(it)
+ exitProcess(result)
+ }.result // block main thread
+}
+
+// This is a separate entry point for tests with leak checker
+fun mainNoExit(args: Array<String>) {
+ testLauncherEntryPoint(args)
+}
\ No newline at end of file
diff --git a/kotlinx-coroutines-debug/README.md b/kotlinx-coroutines-debug/README.md
index 81e62e7..5525f91 100644
--- a/kotlinx-coroutines-debug/README.md
+++ b/kotlinx-coroutines-debug/README.md
@@ -23,7 +23,7 @@
Add `kotlinx-coroutines-debug` to your project test dependencies:
```
dependencies {
- testImplementation 'org.jetbrains.kotlinx:kotlinx-coroutines-debug:1.3.8'
+ testImplementation 'org.jetbrains.kotlinx:kotlinx-coroutines-debug:1.4.0'
}
```
@@ -61,7 +61,7 @@
### Using as JVM agent
Debug module can also be used as a standalone JVM agent to enable debug probes on the application startup.
-You can run your application with an additional argument: `-javaagent:kotlinx-coroutines-debug-1.3.8.jar`.
+You can run your application with an additional argument: `-javaagent:kotlinx-coroutines-debug-1.4.1.jar`.
Additionally, on Linux and Mac OS X you can use `kill -5 $pid` command in order to force your application to print all alive coroutines.
When used as Java agent, `"kotlinx.coroutines.debug.enable.creation.stack.trace"` system property can be used to control
[DebugProbes.enableCreationStackTraces] along with agent startup.
@@ -170,6 +170,98 @@
at kotlinx.coroutines.debug.DebugProbes.install(DebugProbes.kt:49)
-->
+#### Build failures due to duplicate resource files
+
+Building an Android project that depends on `kotlinx-coroutines-debug` (usually introduced by being a transitive
+dependency of `kotlinx-coroutines-test`) may fail with `DuplicateRelativeFileException` for `META-INF/AL2.0`,
+`META-INF/LGPL2.1`, or `win32-x86/attach_hotspot_windows.dll` when trying to merge the Android resource.
+
+The problem is that Android merges the resources of all its dependencies into a single directory and complains about
+conflicts, but:
+* `kotlinx-coroutines-debug` transitively depends on JNA and JNA-platform, both of which include license files in their
+ META-INF directories. Trying to merge these files leads to conflicts, which means that any Android project that
+ depends on JNA and JNA-platform will experience build failures.
+* Additionally, `kotlinx-coroutines-debug` embeds `byte-buddy-agent` and `byte-buddy`, along with their resource files.
+ Then, if the project separately depends on `byte-buddy`, merging the resources of `kotlinx-coroutines-debug` with ones
+ from `byte-buddy` and `byte-buddy-agent` will lead to conflicts as the resource files are duplicated.
+
+One possible workaround for these issues is to add the following to the `android` block in your gradle file for the
+application subproject:
+```groovy
+ packagingOptions {
+ // for JNA and JNA-platform
+ exclude "META-INF/AL2.0"
+ exclude "META-INF/LGPL2.1"
+ // for byte-buddy
+ exclude "META-INF/licenses/ASM"
+ pickFirst "win32-x86-64/attach_hotspot_windows.dll"
+ pickFirst "win32-x86/attach_hotspot_windows.dll"
+ }
+```
+This will cause the resource merge algorithm to exclude the problematic license files altogether and only leave a single
+copy of the files needed for `byte-buddy-agent` to work.
+
+Alternatively, avoid depending on `kotlinx-coroutines-debug`. In particular, if the only reason why this library a
+dependency of your project is that `kotlinx-coroutines-test` in turn depends on it, you may change your dependency on
+`kotlinx.coroutines.test` to exclude `kotlinx-coroutines-debug`. For example, you could replace
+```kotlin
+androidTestImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:$coroutines_version")
+```
+with
+```groovy
+androidTestImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:$coroutines_version") {
+ exclude group: "org.jetbrains.kotlinx", module: "kotlinx-coroutines-debug"
+}
+```
+<!---
+Snippets of stacktraces for googling:
+
+org.gradle.api.tasks.TaskExecutionException: Execution failed for task ':app:mergeDebugAndroidTestJavaResource'.
+ ...
+Caused by: org.gradle.workers.intelrnal.DefaultWorkerExecutor$WorkExecutionException: A failure occurred while executing com.android.build.gradle.internal.tasks.Workers$ActionFacade
+ ...
+Caused by: com.android.builder.merge.DuplicateRelativeFileException: More than one file was found with OS independent path 'META-INF/AL2.0'.
+ at com.android.builder.merge.StreamMergeAlgorithms.lambda$acceptOnlyOne$2(StreamMergeAlgorithms.java:85)
+ at com.android.builder.merge.StreamMergeAlgorithms.lambda$select$3(StreamMergeAlgorithms.java:106)
+ at com.android.builder.merge.IncrementalFileMergerOutputs$1.create(IncrementalFileMergerOutputs.java:88)
+ at com.android.builder.merge.DelegateIncrementalFileMergerOutput.create(DelegateIncrementalFileMergerOutput.java:64)
+ at com.android.build.gradle.internal.tasks.MergeJavaResourcesDelegate$run$output$1.create(MergeJavaResourcesDelegate.kt:230)
+ at com.android.builder.merge.IncrementalFileMerger.updateChangedFile(IncrementalFileMerger.java:242)
+ at com.android.builder.merge.IncrementalFileMerger.mergeChangedInputs(IncrementalFileMerger.java:203)
+ at com.android.builder.merge.IncrementalFileMerger.merge(IncrementalFileMerger.java:80)
+ at com.android.build.gradle.internal.tasks.MergeJavaResourcesDelegate.run(MergeJavaResourcesDelegate.kt:276)
+ at com.android.build.gradle.internal.tasks.MergeJavaResRunnable.run(MergeJavaResRunnable.kt:81)
+ at com.android.build.gradle.internal.tasks.Workers$ActionFacade.run(Workers.kt:242)
+ at org.gradle.workers.internal.AdapterWorkAction.execute(AdapterWorkAction.java:50)
+ at org.gradle.workers.internal.DefaultWorkerServer.execute(DefaultWorkerServer.java:50)
+ at org.gradle.workers.internal.NoIsolationWorkerFactory$1$1.create(NoIsolationWorkerFactory.java:63)
+ at org.gradle.workers.internal.NoIsolationWorkerFactory$1$1.create(NoIsolationWorkerFactory.java:59)
+ at org.gradle.internal.classloader.ClassLoaderUtils.executeInClassloader(ClassLoaderUtils.java:98)
+ at org.gradle.workers.internal.NoIsolationWorkerFactory$1.lambda$execute$0(NoIsolationWorkerFactory.java:59)
+ at org.gradle.workers.internal.AbstractWorker$1.call(AbstractWorker.java:44)
+ at org.gradle.workers.internal.AbstractWorker$1.call(AbstractWorker.java:41)
+ at org.gradle.internal.operations.DefaultBuildOperationExecutor$CallableBuildOperationWorker.execute(DefaultBuildOperationExecutor.java:416)
+ at org.gradle.internal.operations.DefaultBuildOperationExecutor$CallableBuildOperationWorker.execute(DefaultBuildOperationExecutor.java:406)
+ at org.gradle.internal.operations.DefaultBuildOperationExecutor$1.execute(DefaultBuildOperationExecutor.java:165)
+ at org.gradle.internal.operations.DefaultBuildOperationExecutor.execute(DefaultBuildOperationExecutor.java:250)
+ at org.gradle.internal.operations.DefaultBuildOperationExecutor.execute(DefaultBuildOperationExecutor.java:158)
+ at org.gradle.internal.operations.DefaultBuildOperationExecutor.call(DefaultBuildOperationExecutor.java:102)
+ at org.gradle.internal.operations.DelegatingBuildOperationExecutor.call(DelegatingBuildOperationExecutor.java:36)
+ at org.gradle.workers.internal.AbstractWorker.executeWrappedInBuildOperation(AbstractWorker.java:41)
+ at org.gradle.workers.internal.NoIsolationWorkerFactory$1.execute(NoIsolationWorkerFactory.java:53)
+ at org.gradle.workers.internal.DefaultWorkerExecutor.lambda$submitWork$2(DefaultWorkerExecutor.java:200)
+ at org.gradle.internal.work.DefaultConditionalExecutionQueue$ExecutionRunner.runExecution(DefaultConditionalExecutionQueue.java:215)
+ at org.gradle.internal.work.DefaultConditionalExecutionQueue$ExecutionRunner.runBatch(DefaultConditionalExecutionQueue.java:164)
+ at org.gradle.internal.work.DefaultConditionalExecutionQueue$ExecutionRunner.run(DefaultConditionalExecutionQueue.java:131)
+
+Execution failed for task ':app:mergeStagingDebugAndroidTestJavaResource'.
+Execution failed for task ':app:mergeDebugAndroidTestJavaResource'.
+Execution failed for task ':app:mergeDebugTestJavaResource'
+
+More than one file was found with OS independent path 'META-INF/LGPL2.1'
+More than one file was found with OS independent path 'win32-x86/attach_hotspot_windows.dll'
+More than one file was found with OS independent path 'win32-x86-64/attach_hotspot_windows.dll'
+-->
<!--- MODULE kotlinx-coroutines-core -->
<!--- INDEX kotlinx.coroutines -->
[Job]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/index.html
diff --git a/kotlinx-coroutines-debug/src/CoroutinesBlockHoundIntegration.kt b/kotlinx-coroutines-debug/src/CoroutinesBlockHoundIntegration.kt
index f89d2be..091e8eb 100644
--- a/kotlinx-coroutines-debug/src/CoroutinesBlockHoundIntegration.kt
+++ b/kotlinx-coroutines-debug/src/CoroutinesBlockHoundIntegration.kt
@@ -1,16 +1,168 @@
@file:Suppress("INVISIBLE_REFERENCE", "INVISIBLE_MEMBER")
+
package kotlinx.coroutines.debug
-import reactor.blockhound.BlockHound
import kotlinx.coroutines.scheduling.*
+import reactor.blockhound.*
import reactor.blockhound.integration.*
@Suppress("UNUSED")
-public class CoroutinesBlockHoundIntegration: BlockHoundIntegration {
+public class CoroutinesBlockHoundIntegration : BlockHoundIntegration {
- override fun applyTo(builder: BlockHound.Builder) {
- builder.addDynamicThreadPredicate { isSchedulerWorker(it) }
- builder.nonBlockingThreadPredicate { p -> p.or { mayNotBlock(it) } }
+ override fun applyTo(builder: BlockHound.Builder): Unit = with(builder) {
+ allowBlockingCallsInPrimitiveImplementations()
+ allowBlockingWhenEnqueuingTasks()
+ allowServiceLoaderInvocationsOnInit()
+ allowBlockingCallsInReflectionImpl()
+ /* The predicates that define that BlockHound should only report blocking calls from threads that are part of
+ the coroutine thread pool and currently execute a CPU-bound coroutine computation. */
+ addDynamicThreadPredicate { isSchedulerWorker(it) }
+ nonBlockingThreadPredicate { p -> p.or { mayNotBlock(it) } }
+ }
+
+ /**
+ * Allows blocking calls in various coroutine structures, such as flows and channels.
+ *
+ * They use locks in implementations, though only for protecting short pieces of fast and well-understood code, so
+ * locking in such places doesn't affect the program liveness.
+ */
+ private fun BlockHound.Builder.allowBlockingCallsInPrimitiveImplementations() {
+ allowBlockingCallsInJobSupport()
+ allowBlockingCallsInThreadSafeHeap()
+ allowBlockingCallsInFlow()
+ allowBlockingCallsInChannels()
+ }
+
+ /**
+ * Allows blocking inside [kotlinx.coroutines.JobSupport].
+ */
+ private fun BlockHound.Builder.allowBlockingCallsInJobSupport() {
+ for (method in listOf("finalizeFinishingState", "invokeOnCompletion", "makeCancelling",
+ "tryMakeCompleting"))
+ {
+ allowBlockingCallsInside("kotlinx.coroutines.JobSupport", method)
+ }
+ }
+
+ /**
+ * Allows blocking inside [kotlinx.coroutines.internal.ThreadSafeHeap].
+ */
+ private fun BlockHound.Builder.allowBlockingCallsInThreadSafeHeap() {
+ for (method in listOf("clear", "peek", "removeFirstOrNull", "addLast")) {
+ allowBlockingCallsInside("kotlinx.coroutines.internal.ThreadSafeHeap", method)
+ }
+ // [addLastIf] is only used in [EventLoop.common]. Users of [removeFirstIf]:
+ allowBlockingCallsInside("kotlinx.coroutines.test.TestCoroutineDispatcher", "doActionsUntil")
+ allowBlockingCallsInside("kotlinx.coroutines.test.TestCoroutineContext", "triggerActions")
+ }
+
+ private fun BlockHound.Builder.allowBlockingCallsInFlow() {
+ allowBlockingCallsInsideStateFlow()
+ allowBlockingCallsInsideSharedFlow()
+ }
+
+ /**
+ * Allows blocking inside the implementation of [kotlinx.coroutines.flow.StateFlow].
+ */
+ private fun BlockHound.Builder.allowBlockingCallsInsideStateFlow() {
+ allowBlockingCallsInside("kotlinx.coroutines.flow.StateFlowImpl", "updateState")
+ }
+
+ /**
+ * Allows blocking inside the implementation of [kotlinx.coroutines.flow.SharedFlow].
+ */
+ private fun BlockHound.Builder.allowBlockingCallsInsideSharedFlow() {
+ for (method in listOf("emitSuspend", "awaitValue", "getReplayCache", "tryEmit", "cancelEmitter",
+ "tryTakeValue", "resetReplayCache"))
+ {
+ allowBlockingCallsInside("kotlinx.coroutines.flow.SharedFlowImpl", method)
+ }
+ for (method in listOf("getSubscriptionCount", "allocateSlot", "freeSlot")) {
+ allowBlockingCallsInside("kotlinx.coroutines.flow.internal.AbstractSharedFlow", method)
+ }
+ }
+
+ private fun BlockHound.Builder.allowBlockingCallsInChannels() {
+ allowBlockingCallsInArrayChannel()
+ allowBlockingCallsInBroadcastChannel()
+ allowBlockingCallsInConflatedChannel()
+ }
+
+ /**
+ * Allows blocking inside [kotlinx.coroutines.channels.ArrayChannel].
+ */
+ private fun BlockHound.Builder.allowBlockingCallsInArrayChannel() {
+ for (method in listOf(
+ "pollInternal", "isEmpty", "isFull", "isClosedForReceive", "offerInternal", "offerSelectInternal",
+ "enqueueSend", "pollInternal", "pollSelectInternal", "enqueueReceiveInternal", "onCancelIdempotent"))
+ {
+ allowBlockingCallsInside("kotlinx.coroutines.channels.ArrayChannel", method)
+ }
+ }
+
+ /**
+ * Allows blocking inside [kotlinx.coroutines.channels.ArrayBroadcastChannel].
+ */
+ private fun BlockHound.Builder.allowBlockingCallsInBroadcastChannel() {
+ for (method in listOf("offerInternal", "offerSelectInternal", "updateHead")) {
+ allowBlockingCallsInside("kotlinx.coroutines.channels.ArrayBroadcastChannel", method)
+ }
+ for (method in listOf("checkOffer", "pollInternal", "pollSelectInternal")) {
+ allowBlockingCallsInside("kotlinx.coroutines.channels.ArrayBroadcastChannel\$Subscriber", method)
+ }
+ }
+
+ /**
+ * Allows blocking inside [kotlinx.coroutines.channels.ConflatedChannel].
+ */
+ private fun BlockHound.Builder.allowBlockingCallsInConflatedChannel() {
+ for (method in listOf("offerInternal", "offerSelectInternal", "pollInternal", "pollSelectInternal",
+ "onCancelIdempotent"))
+ {
+ allowBlockingCallsInside("kotlinx.coroutines.channels.ConflatedChannel", method)
+ }
+ }
+
+ /**
+ * Allows blocking when enqueuing tasks into a thread pool.
+ *
+ * Without this, the following code breaks:
+ * ```
+ * withContext(Dispatchers.Default) {
+ * withContext(newSingleThreadContext("singleThreadedContext")) {
+ * }
+ * }
+ * ```
+ */
+ private fun BlockHound.Builder.allowBlockingWhenEnqueuingTasks() {
+ /* This method may block as part of its implementation, but is probably safe. */
+ allowBlockingCallsInside("java.util.concurrent.ScheduledThreadPoolExecutor", "execute")
+ }
+
+ /**
+ * Allows instances of [java.util.ServiceLoader] being called.
+ *
+ * Each instance is listed separately; another approach could be to generally allow the operations performed by
+ * service loaders, as they can generally be considered safe. This was not done here because ServiceLoader has a
+ * large API surface, with some methods being hidden as implementation details (in particular, the implementation of
+ * its iterator is completely opaque). Relying on particular names being used in ServiceLoader's implementation
+ * would be brittle, so here we only provide clearance rules for some specific instances.
+ */
+ private fun BlockHound.Builder.allowServiceLoaderInvocationsOnInit() {
+ allowBlockingCallsInside("kotlinx.coroutines.reactive.ReactiveFlowKt", "<clinit>")
+ allowBlockingCallsInside("kotlinx.coroutines.CoroutineExceptionHandlerImplKt", "<clinit>")
+ // not part of the coroutines library, but it would be nice if reflection also wasn't considered blocking
+ allowBlockingCallsInside("kotlin.reflect.jvm.internal.impl.resolve.OverridingUtil", "<clinit>")
+ }
+
+ /**
+ * Allows some blocking calls from the reflection API.
+ *
+ * The API is big, so surely some other blocking calls will show up, but with these rules in place, at least some
+ * simple examples work without problems.
+ */
+ private fun BlockHound.Builder.allowBlockingCallsInReflectionImpl() {
+ allowBlockingCallsInside("kotlin.reflect.jvm.internal.impl.builtins.jvm.JvmBuiltInsPackageFragmentProvider", "findPackage")
}
}
diff --git a/kotlinx-coroutines-debug/test/BlockHoundTest.kt b/kotlinx-coroutines-debug/test/BlockHoundTest.kt
index ff5c95c..571daca 100644
--- a/kotlinx-coroutines-debug/test/BlockHoundTest.kt
+++ b/kotlinx-coroutines-debug/test/BlockHoundTest.kt
@@ -1,5 +1,6 @@
package kotlinx.coroutines.debug
import kotlinx.coroutines.*
+import kotlinx.coroutines.channels.*
import org.junit.*
import reactor.blockhound.*
@@ -52,6 +53,27 @@
}
}
+ @Test
+ fun testChannelsNotBeingConsideredBlocking() = runTest {
+ withContext(Dispatchers.Default) {
+ // Copy of kotlinx.coroutines.channels.ArrayChannelTest.testSimple
+ val q = Channel<Int>(1)
+ check(q.isEmpty)
+ check(!q.isClosedForReceive)
+ check(!q.isClosedForSend)
+ val sender = launch {
+ q.send(1)
+ q.send(2)
+ }
+ val receiver = launch {
+ q.receive() == 1
+ q.receive() == 2
+ }
+ sender.join()
+ receiver.join()
+ }
+ }
+
@Test(expected = BlockingOperationError::class)
fun testReusingThreadsFailure() = runTest {
val n = 100
diff --git a/kotlinx-coroutines-debug/test/CoroutinesDumpTest.kt b/kotlinx-coroutines-debug/test/CoroutinesDumpTest.kt
index 8507721..fd02791 100644
--- a/kotlinx-coroutines-debug/test/CoroutinesDumpTest.kt
+++ b/kotlinx-coroutines-debug/test/CoroutinesDumpTest.kt
@@ -115,16 +115,22 @@
coroutineThread!!.interrupt()
val expected =
- ("kotlin.coroutines.intrinsics.IntrinsicsKt__IntrinsicsJvmKt.createCoroutineUnintercepted(IntrinsicsJvm.kt:116)\n" +
- "kotlinx.coroutines.intrinsics.CancellableKt.startCoroutineCancellable(Cancellable.kt:23)\n" +
- "kotlinx.coroutines.CoroutineStart.invoke(CoroutineStart.kt:109)\n" +
- "kotlinx.coroutines.AbstractCoroutine.start(AbstractCoroutine.kt:160)\n" +
- "kotlinx.coroutines.BuildersKt__Builders_commonKt.async(Builders.common.kt:88)\n" +
- "kotlinx.coroutines.BuildersKt.async(Unknown Source)\n" +
- "kotlinx.coroutines.BuildersKt__Builders_commonKt.async\$default(Builders.common.kt:81)\n" +
- "kotlinx.coroutines.BuildersKt.async\$default(Unknown Source)\n" +
- "kotlinx.coroutines.debug.CoroutinesDumpTest\$testCreationStackTrace\$1.invokeSuspend(CoroutinesDumpTest.kt)").trimStackTrace()
- assertTrue(result.startsWith(expected))
+ "kotlin.coroutines.intrinsics.IntrinsicsKt__IntrinsicsJvmKt.createCoroutineUnintercepted(IntrinsicsJvm.kt)\n" +
+ "kotlinx.coroutines.intrinsics.CancellableKt.startCoroutineCancellable(Cancellable.kt)\n" +
+ "kotlinx.coroutines.intrinsics.CancellableKt.startCoroutineCancellable\$default(Cancellable.kt)\n" +
+ "kotlinx.coroutines.CoroutineStart.invoke(CoroutineStart.kt)\n" +
+ "kotlinx.coroutines.AbstractCoroutine.start(AbstractCoroutine.kt)\n" +
+ "kotlinx.coroutines.BuildersKt__Builders_commonKt.async(Builders.common.kt)\n" +
+ "kotlinx.coroutines.BuildersKt.async(Unknown Source)\n" +
+ "kotlinx.coroutines.BuildersKt__Builders_commonKt.async\$default(Builders.common.kt)\n" +
+ "kotlinx.coroutines.BuildersKt.async\$default(Unknown Source)\n" +
+ "kotlinx.coroutines.debug.CoroutinesDumpTest\$testCreationStackTrace\$1.invokeSuspend(CoroutinesDumpTest.kt)"
+ if (!result.startsWith(expected)) {
+ println("=== Actual result")
+ println(result)
+ error("Does not start with expected lines")
+ }
+
}
@Test
diff --git a/kotlinx-coroutines-debug/test/DebugLeaksStressTest.kt b/kotlinx-coroutines-debug/test/DebugLeaksStressTest.kt
deleted file mode 100644
index bf34917..0000000
--- a/kotlinx-coroutines-debug/test/DebugLeaksStressTest.kt
+++ /dev/null
@@ -1,56 +0,0 @@
-/*
- * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
- */
-
-import kotlinx.coroutines.*
-import kotlinx.coroutines.debug.*
-import org.junit.*
-
-/**
- * This stress tests ensure that no actual [OutOfMemoryError] occurs when lots of coroutines are created and
- * leaked in various ways under debugger. A faster but more fragile version of this test is in [DebugLeaksTest].
- */
-class DebugLeaksStressTest : DebugTestBase() {
- private val nRepeat = 100_000 * stressTestMultiplier
- private val nBytes = 100_000
-
- @Test
- fun testIteratorLeak() {
- repeat(nRepeat) {
- val bytes = ByteArray(nBytes)
- iterator { yield(bytes) }
- }
- }
-
- @Test
- fun testLazyGlobalCoroutineLeak() {
- repeat(nRepeat) {
- val bytes = ByteArray(nBytes)
- GlobalScope.launch(start = CoroutineStart.LAZY) { println(bytes) }
- }
- }
-
- @Test
- fun testLazyCancelledChildCoroutineLeak() = runTest {
- coroutineScope {
- repeat(nRepeat) {
- val bytes = ByteArray(nBytes)
- val child = launch(start = CoroutineStart.LAZY) { println(bytes) }
- child.cancel()
- }
- }
- }
-
- @Test
- fun testAbandonedGlobalCoroutineLeak() {
- repeat(nRepeat) {
- val bytes = ByteArray(nBytes)
- GlobalScope.launch {
- suspendForever()
- println(bytes)
- }
- }
- }
-
- private suspend fun suspendForever() = suspendCancellableCoroutine<Unit> { }
-}
diff --git a/kotlinx-coroutines-debug/test/DebugProbesTest.kt b/kotlinx-coroutines-debug/test/DebugProbesTest.kt
index 24050e5..3b32db3 100644
--- a/kotlinx-coroutines-debug/test/DebugProbesTest.kt
+++ b/kotlinx-coroutines-debug/test/DebugProbesTest.kt
@@ -40,24 +40,25 @@
val deferred = createDeferred()
val traces = listOf(
"java.util.concurrent.ExecutionException\n" +
- "\tat kotlinx.coroutines.debug.DebugProbesTest\$createDeferred\$1.invokeSuspend(DebugProbesTest.kt:16)\n" +
+ "\tat kotlinx.coroutines.debug.DebugProbesTest\$createDeferred\$1.invokeSuspend(DebugProbesTest.kt)\n" +
"\t(Coroutine boundary)\n" +
"\tat kotlinx.coroutines.DeferredCoroutine.await\$suspendImpl(Builders.common.kt)\n" +
- "\tat kotlinx.coroutines.debug.DebugProbesTest.oneMoreNestedMethod(DebugProbesTest.kt:71)\n" +
- "\tat kotlinx.coroutines.debug.DebugProbesTest.nestedMethod(DebugProbesTest.kt:66)\n" +
+ "\tat kotlinx.coroutines.debug.DebugProbesTest.oneMoreNestedMethod(DebugProbesTest.kt)\n" +
+ "\tat kotlinx.coroutines.debug.DebugProbesTest.nestedMethod(DebugProbesTest.kt)\n" +
"\t(Coroutine creation stacktrace)\n" +
- "\tat kotlin.coroutines.intrinsics.IntrinsicsKt__IntrinsicsJvmKt.createCoroutineUnintercepted(IntrinsicsJvm.kt:116)\n" +
- "\tat kotlinx.coroutines.intrinsics.CancellableKt.startCoroutineCancellable(Cancellable.kt:23)\n" +
- "\tat kotlinx.coroutines.CoroutineStart.invoke(CoroutineStart.kt:99)\n" +
- "\tat kotlinx.coroutines.AbstractCoroutine.start(AbstractCoroutine.kt:148)\n" +
- "\tat kotlinx.coroutines.BuildersKt__BuildersKt.runBlocking(Builders.kt:45)\n" +
+ "\tat kotlin.coroutines.intrinsics.IntrinsicsKt__IntrinsicsJvmKt.createCoroutineUnintercepted(IntrinsicsJvm.kt)\n" +
+ "\tat kotlinx.coroutines.intrinsics.CancellableKt.startCoroutineCancellable(Cancellable.kt)\n" +
+ "\tat kotlinx.coroutines.intrinsics.CancellableKt.startCoroutineCancellable\$default(Cancellable.kt)\n" +
+ "\tat kotlinx.coroutines.CoroutineStart.invoke(CoroutineStart.kt)\n" +
+ "\tat kotlinx.coroutines.AbstractCoroutine.start(AbstractCoroutine.kt)\n" +
+ "\tat kotlinx.coroutines.BuildersKt__BuildersKt.runBlocking(Builders.kt)\n" +
"\tat kotlinx.coroutines.BuildersKt.runBlocking(Unknown Source)\n" +
- "\tat kotlinx.coroutines.TestBase.runTest(TestBase.kt:138)\n" +
- "\tat kotlinx.coroutines.TestBase.runTest\$default(TestBase.kt:19)\n" +
- "\tat kotlinx.coroutines.debug.DebugProbesTest.testAsyncWithProbes(DebugProbesTest.kt:38)",
+ "\tat kotlinx.coroutines.TestBase.runTest(TestBase.kt)\n" +
+ "\tat kotlinx.coroutines.TestBase.runTest\$default(TestBase.kt)\n" +
+ "\tat kotlinx.coroutines.debug.DebugProbesTest.testAsyncWithProbes(DebugProbesTest.kt)",
"Caused by: java.util.concurrent.ExecutionException\n" +
- "\tat kotlinx.coroutines.debug.DebugProbesTest\$createDeferred\$1.invokeSuspend(DebugProbesTest.kt:16)\n" +
- "\tat kotlin.coroutines.jvm.internal.BaseContinuationImpl.resumeWith(ContinuationImpl.kt:32)\n")
+ "\tat kotlinx.coroutines.debug.DebugProbesTest\$createDeferred\$1.invokeSuspend(DebugProbesTest.kt)\n" +
+ "\tat kotlin.coroutines.jvm.internal.BaseContinuationImpl.resumeWith(ContinuationImpl.kt)\n")
nestedMethod(deferred, traces)
deferred.join()
}
diff --git a/kotlinx-coroutines-debug/test/LazyCoroutineTest.kt b/kotlinx-coroutines-debug/test/LazyCoroutineTest.kt
new file mode 100644
index 0000000..c872b6a
--- /dev/null
+++ b/kotlinx-coroutines-debug/test/LazyCoroutineTest.kt
@@ -0,0 +1,23 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+package kotlinx.coroutines.debug
+
+import kotlinx.coroutines.*
+import org.junit.Test
+import kotlin.test.*
+
+class LazyCoroutineTest : DebugTestBase() {
+
+ @Test
+ fun testLazyCompletedCoroutine() = runTest {
+ val job = launch(start = CoroutineStart.LAZY) {}
+ job.invokeOnCompletion { expect(2) }
+ expect(1)
+ job.cancelAndJoin()
+ expect(3)
+ assertEquals(1, DebugProbes.dumpCoroutinesInfo().size) // Outer runBlocking
+ verifyPartialDump(1, "BlockingCoroutine{Active}")
+ finish(4)
+ }
+}
diff --git a/kotlinx-coroutines-debug/test/WithContextUndispatchedTest.kt b/kotlinx-coroutines-debug/test/WithContextUndispatchedTest.kt
new file mode 100644
index 0000000..e803c98
--- /dev/null
+++ b/kotlinx-coroutines-debug/test/WithContextUndispatchedTest.kt
@@ -0,0 +1,67 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+package kotlinx.coroutines.debug
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+import org.junit.*
+
+// Test four our internal optimization "withContextUndispatched"
+class WithContextUndispatchedTest : DebugTestBase() {
+
+ @Test
+ fun testZip() = runTest {
+ val f1 = flowOf("a")
+ val f2 = flow {
+ nestedEmit()
+ yield()
+ }
+ f1.zip(f2) { i, j -> i + j }.collect {
+ bar(false)
+ }
+ }
+
+ private suspend fun FlowCollector<Int>.nestedEmit() {
+ emit(1)
+ emit(2)
+ }
+
+ @Test
+ fun testUndispatchedFlowOn() = runTest {
+ val flow = flowOf(1, 2, 3).flowOn(CoroutineName("..."))
+ flow.collect {
+ bar(true)
+ }
+ }
+
+ @Test
+ fun testUndispatchedFlowOnWithNestedCaller() = runTest {
+ val flow = flow {
+ nestedEmit()
+ }.flowOn(CoroutineName("..."))
+ flow.collect {
+ bar(true)
+ }
+ }
+
+ private suspend fun bar(forFlowOn: Boolean) {
+ yield()
+ if (forFlowOn) {
+ verifyFlowOn()
+ } else {
+ verifyZip()
+ }
+ yield()
+ }
+
+ private suspend fun verifyFlowOn() {
+ yield() // suspend
+ verifyPartialDump(1, "verifyFlowOn", "bar")
+ }
+
+ private suspend fun verifyZip() {
+ yield() // suspend
+ verifyPartialDump(2, "verifyZip", "bar", "nestedEmit")
+ }
+}
diff --git a/kotlinx-coroutines-test/README.md b/kotlinx-coroutines-test/README.md
index 97a1178..afcd4a3 100644
--- a/kotlinx-coroutines-test/README.md
+++ b/kotlinx-coroutines-test/README.md
@@ -9,7 +9,7 @@
Add `kotlinx-coroutines-test` to your project test dependencies:
```
dependencies {
- testImplementation 'org.jetbrains.kotlinx:kotlinx-coroutines-test:1.3.8'
+ testImplementation 'org.jetbrains.kotlinx:kotlinx-coroutines-test:1.4.1'
}
```
diff --git a/kotlinx-coroutines-test/api/kotlinx-coroutines-test.api b/kotlinx-coroutines-test/api/kotlinx-coroutines-test.api
index e3b1f73..c99ec5c 100644
--- a/kotlinx-coroutines-test/api/kotlinx-coroutines-test.api
+++ b/kotlinx-coroutines-test/api/kotlinx-coroutines-test.api
@@ -25,7 +25,7 @@
public fun dispatch (Lkotlin/coroutines/CoroutineContext;Ljava/lang/Runnable;)V
public fun dispatchYield (Lkotlin/coroutines/CoroutineContext;Ljava/lang/Runnable;)V
public fun getCurrentTime ()J
- public fun invokeOnTimeout (JLjava/lang/Runnable;)Lkotlinx/coroutines/DisposableHandle;
+ public fun invokeOnTimeout (JLjava/lang/Runnable;Lkotlin/coroutines/CoroutineContext;)Lkotlinx/coroutines/DisposableHandle;
public fun pauseDispatcher ()V
public fun pauseDispatcher (Lkotlin/jvm/functions/Function1;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public fun resumeDispatcher ()V
diff --git a/kotlinx-coroutines-test/src/TestCoroutineDispatcher.kt b/kotlinx-coroutines-test/src/TestCoroutineDispatcher.kt
index 4706d62..cad2636 100644
--- a/kotlinx-coroutines-test/src/TestCoroutineDispatcher.kt
+++ b/kotlinx-coroutines-test/src/TestCoroutineDispatcher.kt
@@ -65,7 +65,7 @@
}
/** @suppress */
- override fun invokeOnTimeout(timeMillis: Long, block: Runnable): DisposableHandle {
+ override fun invokeOnTimeout(timeMillis: Long, block: Runnable, context: CoroutineContext): DisposableHandle {
val node = postDelayed(block, timeMillis)
return object : DisposableHandle {
override fun dispose() {
diff --git a/kotlinx-coroutines-test/src/internal/MainTestDispatcher.kt b/kotlinx-coroutines-test/src/internal/MainTestDispatcher.kt
index c18e410..baa1aa5 100644
--- a/kotlinx-coroutines-test/src/internal/MainTestDispatcher.kt
+++ b/kotlinx-coroutines-test/src/internal/MainTestDispatcher.kt
@@ -46,8 +46,8 @@
delay.delay(time)
}
- override fun invokeOnTimeout(timeMillis: Long, block: Runnable): DisposableHandle {
- return delay.invokeOnTimeout(timeMillis, block)
+ override fun invokeOnTimeout(timeMillis: Long, block: Runnable, context: CoroutineContext): DisposableHandle {
+ return delay.invokeOnTimeout(timeMillis, block, context)
}
public fun setDispatcher(dispatcher: CoroutineDispatcher) {
diff --git a/kotlinx-coroutines-test/test/TestRunBlockingOrderTest.kt b/kotlinx-coroutines-test/test/TestRunBlockingOrderTest.kt
index 0013a65..e21c82b 100644
--- a/kotlinx-coroutines-test/test/TestRunBlockingOrderTest.kt
+++ b/kotlinx-coroutines-test/test/TestRunBlockingOrderTest.kt
@@ -54,11 +54,11 @@
}
@Test
- fun testInfiniteDelay() = runBlockingTest {
+ fun testVeryLongDelay() = runBlockingTest {
expect(1)
delay(100) // move time forward a bit some that naive time + delay gives an overflow
launch {
- delay(Long.MAX_VALUE) // infinite delay
+ delay(Long.MAX_VALUE / 2) // very long delay
finish(4)
}
launch {
diff --git a/reactive/kotlinx-coroutines-jdk9/api/kotlinx-coroutines-jdk9.api b/reactive/kotlinx-coroutines-jdk9/api/kotlinx-coroutines-jdk9.api
index d4bc169..1f5bdec 100644
--- a/reactive/kotlinx-coroutines-jdk9/api/kotlinx-coroutines-jdk9.api
+++ b/reactive/kotlinx-coroutines-jdk9/api/kotlinx-coroutines-jdk9.api
@@ -15,6 +15,8 @@
public final class kotlinx/coroutines/jdk9/ReactiveFlowKt {
public static final fun asFlow (Ljava/util/concurrent/Flow$Publisher;)Lkotlinx/coroutines/flow/Flow;
public static final fun asPublisher (Lkotlinx/coroutines/flow/Flow;)Ljava/util/concurrent/Flow$Publisher;
+ public static final fun asPublisher (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/CoroutineContext;)Ljava/util/concurrent/Flow$Publisher;
+ public static synthetic fun asPublisher$default (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/CoroutineContext;ILjava/lang/Object;)Ljava/util/concurrent/Flow$Publisher;
public static final fun collect (Ljava/util/concurrent/Flow$Publisher;Lkotlin/jvm/functions/Function1;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
}
diff --git a/reactive/kotlinx-coroutines-jdk9/build.gradle b/reactive/kotlinx-coroutines-jdk9/build.gradle
deleted file mode 100644
index 8737e8e..0000000
--- a/reactive/kotlinx-coroutines-jdk9/build.gradle
+++ /dev/null
@@ -1,24 +0,0 @@
-/*
- * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
- */
-targetCompatibility = 9
-
-dependencies {
- compile project(":kotlinx-coroutines-reactive")
- compile "org.reactivestreams:reactive-streams-flow-adapters:$reactive_streams_version"
-}
-
-compileTestKotlin {
- kotlinOptions.jvmTarget = "9"
-}
-
-compileKotlin {
- kotlinOptions.jvmTarget = "9"
-}
-
-tasks.withType(dokka.getClass()) {
- externalDocumentationLink {
- url = new URL("https://docs.oracle.com/javase/9/docs/api/java/util/concurrent/Flow.html")
- packageListUrl = projectDir.toPath().resolve("package.list").toUri().toURL()
- }
-}
diff --git a/reactive/kotlinx-coroutines-jdk9/build.gradle.kts b/reactive/kotlinx-coroutines-jdk9/build.gradle.kts
new file mode 100644
index 0000000..c721746
--- /dev/null
+++ b/reactive/kotlinx-coroutines-jdk9/build.gradle.kts
@@ -0,0 +1,22 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+dependencies {
+ compile(project(":kotlinx-coroutines-reactive"))
+ compile("org.reactivestreams:reactive-streams-flow-adapters:${version("reactive_streams")}")
+}
+
+tasks {
+ compileKotlin {
+ kotlinOptions.jvmTarget = "9"
+ }
+
+ compileTestKotlin {
+ kotlinOptions.jvmTarget = "9"
+ }
+}
+
+externalDocumentationLink(
+ url = "https://docs.oracle.com/javase/9/docs/api/java/util/concurrent/Flow.html"
+)
diff --git a/reactive/kotlinx-coroutines-jdk9/src/Publish.kt b/reactive/kotlinx-coroutines-jdk9/src/Publish.kt
index d274083..6fd9a5e 100644
--- a/reactive/kotlinx-coroutines-jdk9/src/Publish.kt
+++ b/reactive/kotlinx-coroutines-jdk9/src/Publish.kt
@@ -28,7 +28,7 @@
* **Note: This is an experimental api.** Behaviour of publishers that work as children in a parent scope with respect
* to cancellation and error handling may change in the future.
*/
-@ExperimentalCoroutinesApi
+@ExperimentalCoroutinesApi // Since 1.3.x
public fun <T> flowPublish(
context: CoroutineContext = EmptyCoroutineContext,
@BuilderInference block: suspend ProducerScope<T>.() -> Unit
diff --git a/reactive/kotlinx-coroutines-jdk9/src/ReactiveFlow.kt b/reactive/kotlinx-coroutines-jdk9/src/ReactiveFlow.kt
index 89caf82..5d546df 100644
--- a/reactive/kotlinx-coroutines-jdk9/src/ReactiveFlow.kt
+++ b/reactive/kotlinx-coroutines-jdk9/src/ReactiveFlow.kt
@@ -4,12 +4,14 @@
package kotlinx.coroutines.jdk9
+import kotlinx.coroutines.*
import kotlinx.coroutines.flow.*
import kotlinx.coroutines.reactive.asFlow
import kotlinx.coroutines.reactive.asPublisher
import kotlinx.coroutines.reactive.collect
+import org.reactivestreams.*
+import kotlin.coroutines.*
import java.util.concurrent.Flow as JFlow
-import org.reactivestreams.FlowAdapters
/**
* Transforms the given reactive [Publisher] into [Flow].
@@ -25,9 +27,15 @@
/**
* Transforms the given flow to a reactive specification compliant [Publisher].
+ *
+ * An optional [context] can be specified to control the execution context of calls to [Subscriber] methods.
+ * You can set a [CoroutineDispatcher] to confine them to a specific thread and/or various [ThreadContextElement] to
+ * inject additional context into the caller thread. By default, the [Unconfined][Dispatchers.Unconfined] dispatcher
+ * is used, so calls are performed from an arbitrary thread.
*/
-public fun <T : Any> Flow<T>.asPublisher(): JFlow.Publisher<T> {
- val reactivePublisher : org.reactivestreams.Publisher<T> = this.asPublisher<T>()
+@JvmOverloads // binary compatibility
+public fun <T : Any> Flow<T>.asPublisher(context: CoroutineContext = EmptyCoroutineContext): JFlow.Publisher<T> {
+ val reactivePublisher : org.reactivestreams.Publisher<T> = this.asPublisher<T>(context)
return FlowAdapters.toFlowPublisher(reactivePublisher)
}
diff --git a/reactive/kotlinx-coroutines-reactive/README.md b/reactive/kotlinx-coroutines-reactive/README.md
index 0a59b2c..aed2622 100644
--- a/reactive/kotlinx-coroutines-reactive/README.md
+++ b/reactive/kotlinx-coroutines-reactive/README.md
@@ -6,7 +6,7 @@
| **Name** | **Result** | **Scope** | **Description**
| --------------- | ----------------------------- | ---------------- | ---------------
-| [publish] | `Publisher` | [ProducerScope] | Cold reactive publisher that starts the coroutine on subscribe
+| [kotlinx.coroutines.reactive.publish] | `Publisher` | [ProducerScope] | Cold reactive publisher that starts the coroutine on subscribe
Integration with [Flow]:
@@ -37,7 +37,7 @@
[ProducerScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-producer-scope/index.html
<!--- MODULE kotlinx-coroutines-reactive -->
<!--- INDEX kotlinx.coroutines.reactive -->
-[publish]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive/kotlinx.coroutines.reactive/publish.html
+[kotlinx.coroutines.reactive.publish]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive/kotlinx.coroutines.reactive/publish.html
[Publisher.asFlow]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive/kotlinx.coroutines.reactive/org.reactivestreams.-publisher/as-flow.html
[Flow.asPublisher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive/kotlinx.coroutines.reactive/kotlinx.coroutines.flow.-flow/as-publisher.html
[org.reactivestreams.Publisher.awaitFirst]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive/kotlinx.coroutines.reactive/org.reactivestreams.-publisher/await-first.html
diff --git a/reactive/kotlinx-coroutines-reactive/api/kotlinx-coroutines-reactive.api b/reactive/kotlinx-coroutines-reactive/api/kotlinx-coroutines-reactive.api
index bed065d..961fdbe 100644
--- a/reactive/kotlinx-coroutines-reactive/api/kotlinx-coroutines-reactive.api
+++ b/reactive/kotlinx-coroutines-reactive/api/kotlinx-coroutines-reactive.api
@@ -5,6 +5,9 @@
public static final fun awaitFirstOrNull (Lorg/reactivestreams/Publisher;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public static final fun awaitLast (Lorg/reactivestreams/Publisher;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public static final fun awaitSingle (Lorg/reactivestreams/Publisher;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+ public static final fun awaitSingleOrDefault (Lorg/reactivestreams/Publisher;Ljava/lang/Object;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+ public static final fun awaitSingleOrElse (Lorg/reactivestreams/Publisher;Lkotlin/jvm/functions/Function0;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+ public static final fun awaitSingleOrNull (Lorg/reactivestreams/Publisher;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
}
public final class kotlinx/coroutines/reactive/ChannelKt {
@@ -32,7 +35,7 @@
public final class kotlinx/coroutines/reactive/FlowSubscription : kotlinx/coroutines/AbstractCoroutine, org/reactivestreams/Subscription {
public final field flow Lkotlinx/coroutines/flow/Flow;
public final field subscriber Lorg/reactivestreams/Subscriber;
- public fun <init> (Lkotlinx/coroutines/flow/Flow;Lorg/reactivestreams/Subscriber;)V
+ public fun <init> (Lkotlinx/coroutines/flow/Flow;Lorg/reactivestreams/Subscriber;Lkotlin/coroutines/CoroutineContext;)V
public fun cancel ()V
public fun request (J)V
}
@@ -65,5 +68,7 @@
public final class kotlinx/coroutines/reactive/ReactiveFlowKt {
public static final fun asFlow (Lorg/reactivestreams/Publisher;)Lkotlinx/coroutines/flow/Flow;
public static final fun asPublisher (Lkotlinx/coroutines/flow/Flow;)Lorg/reactivestreams/Publisher;
+ public static final fun asPublisher (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/CoroutineContext;)Lorg/reactivestreams/Publisher;
+ public static synthetic fun asPublisher$default (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/CoroutineContext;ILjava/lang/Object;)Lorg/reactivestreams/Publisher;
}
diff --git a/reactive/kotlinx-coroutines-reactive/build.gradle.kts b/reactive/kotlinx-coroutines-reactive/build.gradle.kts
index c69148f..2ace4f9 100644
--- a/reactive/kotlinx-coroutines-reactive/build.gradle.kts
+++ b/reactive/kotlinx-coroutines-reactive/build.gradle.kts
@@ -2,10 +2,6 @@
* Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
*/
-import org.jetbrains.dokka.DokkaConfiguration.ExternalDocumentationLink
-import org.jetbrains.dokka.gradle.DokkaTask
-import java.net.URL
-
val reactiveStreamsVersion = property("reactive_streams_version")
dependencies {
@@ -13,31 +9,28 @@
testCompile("org.reactivestreams:reactive-streams-tck:$reactiveStreamsVersion")
}
-tasks {
- val testNG = register<Test>("testNG") {
- useTestNG()
- reports.html.destination = file("$buildDir/reports/testng")
- include("**/*ReactiveStreamTckTest.*")
- // Skip testNG when tests are filtered with --tests, otherwise it simply fails
- onlyIf {
- filter.includePatterns.isEmpty()
- }
- doFirst {
- // Classic gradle, nothing works without doFirst
- println("TestNG tests: ($includes)")
- }
+val testNG by tasks.registering(Test::class) {
+ useTestNG()
+ reports.html.destination = file("$buildDir/reports/testng")
+ include("**/*ReactiveStreamTckTest.*")
+ // Skip testNG when tests are filtered with --tests, otherwise it simply fails
+ onlyIf {
+ filter.includePatterns.isEmpty()
}
-
- named<Test>("test") {
- reports.html.destination = file("$buildDir/reports/junit")
-
- dependsOn(testNG)
- }
-
- withType<DokkaTask>().configureEach {
- externalDocumentationLink(delegateClosureOf<ExternalDocumentationLink.Builder> {
- url = URL("https://www.reactive-streams.org/reactive-streams-$reactiveStreamsVersion-javadoc/")
- packageListUrl = projectDir.toPath().resolve("package.list").toUri().toURL()
- })
+ doFirst {
+ // Classic gradle, nothing works without doFirst
+ println("TestNG tests: ($includes)")
}
}
+
+tasks.test {
+ reports.html.destination = file("$buildDir/reports/junit")
+}
+
+tasks.check {
+ dependsOn(testNG)
+}
+
+externalDocumentationLink(
+ url = "https://www.reactive-streams.org/reactive-streams-$reactiveStreamsVersion-javadoc/"
+)
diff --git a/reactive/kotlinx-coroutines-reactive/src/Await.kt b/reactive/kotlinx-coroutines-reactive/src/Await.kt
index 9ea2e3c..7956c26 100644
--- a/reactive/kotlinx-coroutines-reactive/src/Await.kt
+++ b/reactive/kotlinx-coroutines-reactive/src/Await.kt
@@ -80,13 +80,53 @@
*/
public suspend fun <T> Publisher<T>.awaitSingle(): T = awaitOne(Mode.SINGLE)
+/**
+ * Awaits for the single value from the given publisher or the [default] value if none is emitted without blocking a thread and
+ * returns the resulting value or throws the corresponding exception if this publisher had produced error.
+ *
+ * This suspending function is cancellable.
+ * If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function
+ * immediately resumes with [CancellationException].
+ *
+ * @throws NoSuchElementException if publisher does not emit any value
+ * @throws IllegalArgumentException if publisher emits more than one value
+ */
+public suspend fun <T> Publisher<T>.awaitSingleOrDefault(default: T): T = awaitOne(Mode.SINGLE_OR_DEFAULT, default)
+
+/**
+ * Awaits for the single value from the given publisher or `null` value if none is emitted without blocking a thread and
+ * returns the resulting value or throws the corresponding exception if this publisher had produced error.
+ *
+ * This suspending function is cancellable.
+ * If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function
+ * immediately resumes with [CancellationException].
+ *
+ * @throws NoSuchElementException if publisher does not emit any value
+ * @throws IllegalArgumentException if publisher emits more than one value
+ */
+public suspend fun <T> Publisher<T>.awaitSingleOrNull(): T = awaitOne(Mode.SINGLE_OR_DEFAULT)
+
+/**
+ * Awaits for the single value from the given publisher or call [defaultValue] to get a value if none is emitted without blocking a thread and
+ * returns the resulting value or throws the corresponding exception if this publisher had produced error.
+ *
+ * This suspending function is cancellable.
+ * If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function
+ * immediately resumes with [CancellationException].
+ *
+ * @throws NoSuchElementException if publisher does not emit any value
+ * @throws IllegalArgumentException if publisher emits more than one value
+ */
+public suspend fun <T> Publisher<T>.awaitSingleOrElse(defaultValue: () -> T): T = awaitOne(Mode.SINGLE_OR_DEFAULT) ?: defaultValue()
+
// ------------------------ private ------------------------
private enum class Mode(val s: String) {
FIRST("awaitFirst"),
FIRST_OR_DEFAULT("awaitFirstOrDefault"),
LAST("awaitLast"),
- SINGLE("awaitSingle");
+ SINGLE("awaitSingle"),
+ SINGLE_OR_DEFAULT("awaitSingleOrDefault");
override fun toString(): String = s
}
@@ -114,8 +154,8 @@
cont.resume(t)
}
}
- Mode.LAST, Mode.SINGLE -> {
- if (mode == Mode.SINGLE && seenValue) {
+ Mode.LAST, Mode.SINGLE, Mode.SINGLE_OR_DEFAULT -> {
+ if ((mode == Mode.SINGLE || mode == Mode.SINGLE_OR_DEFAULT) && seenValue) {
subscription.cancel()
if (cont.isActive)
cont.resumeWithException(IllegalArgumentException("More than one onNext value for $mode"))
@@ -134,7 +174,7 @@
return
}
when {
- mode == Mode.FIRST_OR_DEFAULT -> {
+ (mode == Mode.FIRST_OR_DEFAULT || mode == Mode.SINGLE_OR_DEFAULT) -> {
cont.resume(default as T)
}
cont.isActive -> {
diff --git a/reactive/kotlinx-coroutines-reactive/src/Channel.kt b/reactive/kotlinx-coroutines-reactive/src/Channel.kt
index 379fc4e..26f14ec 100644
--- a/reactive/kotlinx-coroutines-reactive/src/Channel.kt
+++ b/reactive/kotlinx-coroutines-reactive/src/Channel.kt
@@ -48,7 +48,7 @@
@Suppress("INVISIBLE_REFERENCE", "INVISIBLE_MEMBER", "SubscriberImplementation")
private class SubscriptionChannel<T>(
private val request: Int
-) : LinkedListChannel<T>(), Subscriber<T> {
+) : LinkedListChannel<T>(null), Subscriber<T> {
init {
require(request >= 0) { "Invalid request size: $request" }
}
diff --git a/reactive/kotlinx-coroutines-reactive/src/ReactiveFlow.kt b/reactive/kotlinx-coroutines-reactive/src/ReactiveFlow.kt
index efa9c9c..5834220 100644
--- a/reactive/kotlinx-coroutines-reactive/src/ReactiveFlow.kt
+++ b/reactive/kotlinx-coroutines-reactive/src/ReactiveFlow.kt
@@ -34,16 +34,24 @@
*
* This function is integrated with `ReactorContext` from `kotlinx-coroutines-reactor` module,
* see its documentation for additional details.
+ *
+ * An optional [context] can be specified to control the execution context of calls to [Subscriber] methods.
+ * You can set a [CoroutineDispatcher] to confine them to a specific thread and/or various [ThreadContextElement] to
+ * inject additional context into the caller thread. By default, the [Unconfined][Dispatchers.Unconfined] dispatcher
+ * is used, so calls are performed from an arbitrary thread.
*/
-public fun <T : Any> Flow<T>.asPublisher(): Publisher<T> = FlowAsPublisher(this)
+@JvmOverloads // binary compatibility
+public fun <T : Any> Flow<T>.asPublisher(context: CoroutineContext = EmptyCoroutineContext): Publisher<T> =
+ FlowAsPublisher(this, Dispatchers.Unconfined + context)
private class PublisherAsFlow<T : Any>(
private val publisher: Publisher<T>,
context: CoroutineContext = EmptyCoroutineContext,
- capacity: Int = Channel.BUFFERED
-) : ChannelFlow<T>(context, capacity) {
- override fun create(context: CoroutineContext, capacity: Int): ChannelFlow<T> =
- PublisherAsFlow(publisher, context, capacity)
+ capacity: Int = Channel.BUFFERED,
+ onBufferOverflow: BufferOverflow = BufferOverflow.SUSPEND
+) : ChannelFlow<T>(context, capacity, onBufferOverflow) {
+ override fun create(context: CoroutineContext, capacity: Int, onBufferOverflow: BufferOverflow): ChannelFlow<T> =
+ PublisherAsFlow(publisher, context, capacity, onBufferOverflow)
/*
* Suppress for Channel.CHANNEL_DEFAULT_CAPACITY.
@@ -52,13 +60,15 @@
*/
@Suppress("INVISIBLE_MEMBER", "INVISIBLE_REFERENCE")
private val requestSize: Long
- get() = when (capacity) {
- Channel.CONFLATED -> Long.MAX_VALUE // request all and conflate incoming
- Channel.RENDEZVOUS -> 1L // need to request at least one anyway
- Channel.UNLIMITED -> Long.MAX_VALUE // reactive streams way to say "give all" must be Long.MAX_VALUE
- Channel.BUFFERED -> Channel.CHANNEL_DEFAULT_CAPACITY.toLong()
- else -> capacity.toLong().also { check(it >= 1) }
- }
+ get() =
+ if (onBufferOverflow != BufferOverflow.SUSPEND) {
+ Long.MAX_VALUE // request all, since buffering strategy is to never suspend
+ } else when (capacity) {
+ Channel.RENDEZVOUS -> 1L // need to request at least one anyway
+ Channel.UNLIMITED -> Long.MAX_VALUE // reactive streams way to say "give all", must be Long.MAX_VALUE
+ Channel.BUFFERED -> Channel.CHANNEL_DEFAULT_CAPACITY.toLong()
+ else -> capacity.toLong().also { check(it >= 1) }
+ }
override suspend fun collect(collector: FlowCollector<T>) {
val collectContext = coroutineContext
@@ -78,7 +88,7 @@
}
private suspend fun collectImpl(injectContext: CoroutineContext, collector: FlowCollector<T>) {
- val subscriber = ReactiveSubscriber<T>(capacity, requestSize)
+ val subscriber = ReactiveSubscriber<T>(capacity, onBufferOverflow, requestSize)
// inject subscribe context into publisher
publisher.injectCoroutineContext(injectContext).subscribe(subscriber)
try {
@@ -105,10 +115,14 @@
@Suppress("SubscriberImplementation")
private class ReactiveSubscriber<T : Any>(
capacity: Int,
+ onBufferOverflow: BufferOverflow,
private val requestSize: Long
) : Subscriber<T> {
private lateinit var subscription: Subscription
- private val channel = Channel<T>(capacity)
+
+ // This implementation of ReactiveSubscriber always uses "offer" in its onNext implementation and it cannot
+ // be reliable with rendezvous channel, so a rendezvous channel is replaced with buffer=1 channel
+ private val channel = Channel<T>(if (capacity == Channel.RENDEZVOUS) 1 else capacity, onBufferOverflow)
suspend fun takeNextOrNull(): T? = channel.receiveOrNull()
@@ -153,11 +167,14 @@
* Adapter that transforms [Flow] into TCK-complaint [Publisher].
* [cancel] invocation cancels the original flow.
*/
-@Suppress("PublisherImplementation")
-private class FlowAsPublisher<T : Any>(private val flow: Flow<T>) : Publisher<T> {
+@Suppress("ReactiveStreamsPublisherImplementation")
+private class FlowAsPublisher<T : Any>(
+ private val flow: Flow<T>,
+ private val context: CoroutineContext
+) : Publisher<T> {
override fun subscribe(subscriber: Subscriber<in T>?) {
if (subscriber == null) throw NullPointerException()
- subscriber.onSubscribe(FlowSubscription(flow, subscriber))
+ subscriber.onSubscribe(FlowSubscription(flow, subscriber, context))
}
}
@@ -165,8 +182,9 @@
@InternalCoroutinesApi
public class FlowSubscription<T>(
@JvmField public val flow: Flow<T>,
- @JvmField public val subscriber: Subscriber<in T>
-) : Subscription, AbstractCoroutine<Unit>(Dispatchers.Unconfined, true) {
+ @JvmField public val subscriber: Subscriber<in T>,
+ context: CoroutineContext
+) : Subscription, AbstractCoroutine<Unit>(context, true) {
private val requested = atomic(0L)
private val producer = atomic<Continuation<Unit>?>(createInitialContinuation())
diff --git a/reactive/kotlinx-coroutines-reactive/test/FlowAsPublisherTest.kt b/reactive/kotlinx-coroutines-reactive/test/FlowAsPublisherTest.kt
index c044d92..e7b8cb1 100644
--- a/reactive/kotlinx-coroutines-reactive/test/FlowAsPublisherTest.kt
+++ b/reactive/kotlinx-coroutines-reactive/test/FlowAsPublisherTest.kt
@@ -8,10 +8,10 @@
import kotlinx.coroutines.flow.*
import org.junit.Test
import org.reactivestreams.*
+import java.util.concurrent.*
import kotlin.test.*
class FlowAsPublisherTest : TestBase() {
-
@Test
fun testErrorOnCancellationIsReported() {
expect(1)
@@ -75,4 +75,78 @@
})
finish(4)
}
+
+ @Test
+ fun testUnconfinedDefaultContext() {
+ expect(1)
+ val thread = Thread.currentThread()
+ fun checkThread() {
+ assertSame(thread, Thread.currentThread())
+ }
+ flowOf(42).asPublisher().subscribe(object : Subscriber<Int> {
+ private lateinit var subscription: Subscription
+
+ override fun onSubscribe(s: Subscription) {
+ expect(2)
+ subscription = s
+ subscription.request(2)
+ }
+
+ override fun onNext(t: Int) {
+ checkThread()
+ expect(3)
+ assertEquals(42, t)
+ }
+
+ override fun onComplete() {
+ checkThread()
+ expect(4)
+ }
+
+ override fun onError(t: Throwable?) {
+ expectUnreached()
+ }
+ })
+ finish(5)
+ }
+
+ @Test
+ fun testConfinedContext() {
+ expect(1)
+ val threadName = "FlowAsPublisherTest.testConfinedContext"
+ fun checkThread() {
+ val currentThread = Thread.currentThread()
+ assertTrue(currentThread.name.startsWith(threadName), "Unexpected thread $currentThread")
+ }
+ val completed = CountDownLatch(1)
+ newSingleThreadContext(threadName).use { dispatcher ->
+ flowOf(42).asPublisher(dispatcher).subscribe(object : Subscriber<Int> {
+ private lateinit var subscription: Subscription
+
+ override fun onSubscribe(s: Subscription) {
+ expect(2)
+ subscription = s
+ subscription.request(2)
+ }
+
+ override fun onNext(t: Int) {
+ checkThread()
+ expect(3)
+ assertEquals(42, t)
+ }
+
+ override fun onComplete() {
+ checkThread()
+ expect(4)
+ completed.countDown()
+ }
+
+ override fun onError(t: Throwable?) {
+ expectUnreached()
+ }
+ })
+ completed.await()
+ }
+ finish(5)
+ }
}
diff --git a/reactive/kotlinx-coroutines-reactive/test/IntegrationTest.kt b/reactive/kotlinx-coroutines-reactive/test/IntegrationTest.kt
index 6f7d984..18cd012 100644
--- a/reactive/kotlinx-coroutines-reactive/test/IntegrationTest.kt
+++ b/reactive/kotlinx-coroutines-reactive/test/IntegrationTest.kt
@@ -48,6 +48,9 @@
assertEquals("ELSE", pub.awaitFirstOrElse { "ELSE" })
assertFailsWith<NoSuchElementException> { pub.awaitLast() }
assertFailsWith<NoSuchElementException> { pub.awaitSingle() }
+ assertEquals("OK", pub.awaitSingleOrDefault("OK"))
+ assertNull(pub.awaitSingleOrNull())
+ assertEquals("ELSE", pub.awaitSingleOrElse { "ELSE" })
var cnt = 0
pub.collect { cnt++ }
assertEquals(0, cnt)
@@ -65,6 +68,9 @@
assertEquals("OK", pub.awaitFirstOrElse { "ELSE" })
assertEquals("OK", pub.awaitLast())
assertEquals("OK", pub.awaitSingle())
+ assertEquals("OK", pub.awaitSingleOrDefault("!"))
+ assertEquals("OK", pub.awaitSingleOrNull())
+ assertEquals("OK", pub.awaitSingleOrElse { "ELSE" })
var cnt = 0
pub.collect {
assertEquals("OK", it)
@@ -84,10 +90,13 @@
}
assertEquals(1, pub.awaitFirst())
assertEquals(1, pub.awaitFirstOrDefault(0))
- assertEquals(n, pub.awaitLast())
assertEquals(1, pub.awaitFirstOrNull())
assertEquals(1, pub.awaitFirstOrElse { 0 })
+ assertEquals(n, pub.awaitLast())
assertFailsWith<IllegalArgumentException> { pub.awaitSingle() }
+ assertFailsWith<IllegalArgumentException> { pub.awaitSingleOrDefault(0) }
+ assertFailsWith<IllegalArgumentException> { pub.awaitSingleOrNull() }
+ assertFailsWith<IllegalArgumentException> { pub.awaitSingleOrElse { 0 } }
checkNumbers(n, pub)
val channel = pub.openSubscription()
checkNumbers(n, channel.asPublisher(ctx(coroutineContext)))
diff --git a/reactive/kotlinx-coroutines-reactive/test/PublisherAsFlowTest.kt b/reactive/kotlinx-coroutines-reactive/test/PublisherAsFlowTest.kt
index 61f88f6..04833e9 100644
--- a/reactive/kotlinx-coroutines-reactive/test/PublisherAsFlowTest.kt
+++ b/reactive/kotlinx-coroutines-reactive/test/PublisherAsFlowTest.kt
@@ -7,6 +7,7 @@
import kotlinx.coroutines.*
import kotlinx.coroutines.channels.*
import kotlinx.coroutines.flow.*
+import org.reactivestreams.*
import kotlin.test.*
class PublisherAsFlowTest : TestBase() {
@@ -181,4 +182,85 @@
}
finish(6)
}
+
+ @Test
+ fun testRequestRendezvous() =
+ testRequestSizeWithBuffer(Channel.RENDEZVOUS, BufferOverflow.SUSPEND, 1)
+
+ @Test
+ fun testRequestBuffer1() =
+ testRequestSizeWithBuffer(1, BufferOverflow.SUSPEND, 1)
+
+ @Test
+ fun testRequestBuffer10() =
+ testRequestSizeWithBuffer(10, BufferOverflow.SUSPEND, 10)
+
+ @Test
+ fun testRequestBufferUnlimited() =
+ testRequestSizeWithBuffer(Channel.UNLIMITED, BufferOverflow.SUSPEND, Long.MAX_VALUE)
+
+ @Test
+ fun testRequestBufferOverflowSuspend() =
+ testRequestSizeWithBuffer(Channel.BUFFERED, BufferOverflow.SUSPEND, 64)
+
+ @Test
+ fun testRequestBufferOverflowDropOldest() =
+ testRequestSizeWithBuffer(Channel.BUFFERED, BufferOverflow.DROP_OLDEST, Long.MAX_VALUE)
+
+ @Test
+ fun testRequestBufferOverflowDropLatest() =
+ testRequestSizeWithBuffer(Channel.BUFFERED, BufferOverflow.DROP_LATEST, Long.MAX_VALUE)
+
+ @Test
+ fun testRequestBuffer10OverflowDropOldest() =
+ testRequestSizeWithBuffer(10, BufferOverflow.DROP_OLDEST, Long.MAX_VALUE)
+
+ @Test
+ fun testRequestBuffer10OverflowDropLatest() =
+ testRequestSizeWithBuffer(10, BufferOverflow.DROP_LATEST, Long.MAX_VALUE)
+
+ /**
+ * Tests `publisher.asFlow.buffer(...)` chain, verifying expected requests size and that only expected
+ * values are delivered.
+ */
+ private fun testRequestSizeWithBuffer(
+ capacity: Int,
+ onBufferOverflow: BufferOverflow,
+ expectedRequestSize: Long
+ ) = runTest {
+ val m = 50
+ // publishers numbers from 1 to m
+ val publisher = Publisher<Int> { s ->
+ s.onSubscribe(object : Subscription {
+ var lastSent = 0
+ var remaining = 0L
+ override fun request(n: Long) {
+ assertEquals(expectedRequestSize, n)
+ remaining += n
+ check(remaining >= 0)
+ while (lastSent < m && remaining > 0) {
+ s.onNext(++lastSent)
+ remaining--
+ }
+ if (lastSent == m) s.onComplete()
+ }
+
+ override fun cancel() {}
+ })
+ }
+ val flow = publisher
+ .asFlow()
+ .buffer(capacity, onBufferOverflow)
+ val list = flow.toList()
+ val runSize = if (capacity == Channel.BUFFERED) 1 else capacity
+ val expected = when (onBufferOverflow) {
+ // Everything is expected to be delivered
+ BufferOverflow.SUSPEND -> (1..m).toList()
+ // Only the last one (by default) or the last "capacity" items delivered
+ BufferOverflow.DROP_OLDEST -> (m - runSize + 1..m).toList()
+ // Only the first one (by default) or the first "capacity" items delivered
+ BufferOverflow.DROP_LATEST -> (1..runSize).toList()
+ }
+ assertEquals(expected, list)
+ }
}
diff --git a/reactive/kotlinx-coroutines-reactor/api/kotlinx-coroutines-reactor.api b/reactive/kotlinx-coroutines-reactor/api/kotlinx-coroutines-reactor.api
index 422f36b..b46fe33 100644
--- a/reactive/kotlinx-coroutines-reactor/api/kotlinx-coroutines-reactor.api
+++ b/reactive/kotlinx-coroutines-reactor/api/kotlinx-coroutines-reactor.api
@@ -38,6 +38,8 @@
public final class kotlinx/coroutines/reactor/ReactorFlowKt {
public static final fun asFlux (Lkotlinx/coroutines/flow/Flow;)Lreactor/core/publisher/Flux;
+ public static final fun asFlux (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/CoroutineContext;)Lreactor/core/publisher/Flux;
+ public static synthetic fun asFlux$default (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/CoroutineContext;ILjava/lang/Object;)Lreactor/core/publisher/Flux;
}
public final class kotlinx/coroutines/reactor/SchedulerCoroutineDispatcher : kotlinx/coroutines/CoroutineDispatcher, kotlinx/coroutines/Delay {
@@ -47,7 +49,7 @@
public fun equals (Ljava/lang/Object;)Z
public final fun getScheduler ()Lreactor/core/scheduler/Scheduler;
public fun hashCode ()I
- public fun invokeOnTimeout (JLjava/lang/Runnable;)Lkotlinx/coroutines/DisposableHandle;
+ public fun invokeOnTimeout (JLjava/lang/Runnable;Lkotlin/coroutines/CoroutineContext;)Lkotlinx/coroutines/DisposableHandle;
public fun scheduleResumeAfterDelay (JLkotlinx/coroutines/CancellableContinuation;)V
public fun toString ()Ljava/lang/String;
}
diff --git a/reactive/kotlinx-coroutines-reactor/build.gradle b/reactive/kotlinx-coroutines-reactor/build.gradle
deleted file mode 100644
index 3b640bd..0000000
--- a/reactive/kotlinx-coroutines-reactor/build.gradle
+++ /dev/null
@@ -1,23 +0,0 @@
-/*
- * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
- */
-
-dependencies {
- compile "io.projectreactor:reactor-core:$reactor_version"
- compile project(':kotlinx-coroutines-reactive')
-}
-
-tasks.withType(dokka.getClass()) {
- externalDocumentationLink {
- url = new URL("https://projectreactor.io/docs/core/$reactor_version/api/")
- packageListUrl = projectDir.toPath().resolve("package.list").toUri().toURL()
- }
-}
-
-compileTestKotlin {
- kotlinOptions.jvmTarget = "1.8"
-}
-
-compileKotlin {
- kotlinOptions.jvmTarget = "1.8"
-}
diff --git a/reactive/kotlinx-coroutines-reactor/build.gradle.kts b/reactive/kotlinx-coroutines-reactor/build.gradle.kts
new file mode 100644
index 0000000..d5fd208
--- /dev/null
+++ b/reactive/kotlinx-coroutines-reactor/build.gradle.kts
@@ -0,0 +1,25 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+val reactorVersion = version("reactor")
+
+dependencies {
+ compile("io.projectreactor:reactor-core:$reactorVersion")
+ compile(project(":kotlinx-coroutines-reactive"))
+}
+
+
+tasks {
+ compileKotlin {
+ kotlinOptions.jvmTarget = "1.8"
+ }
+
+ compileTestKotlin {
+ kotlinOptions.jvmTarget = "1.8"
+ }
+}
+
+externalDocumentationLink(
+ url = "https://projectreactor.io/docs/core/$reactorVersion/api/"
+)
diff --git a/reactive/kotlinx-coroutines-reactor/src/ReactorFlow.kt b/reactive/kotlinx-coroutines-reactor/src/ReactorFlow.kt
index d665c88..a478ab1 100644
--- a/reactive/kotlinx-coroutines-reactor/src/ReactorFlow.kt
+++ b/reactive/kotlinx-coroutines-reactor/src/ReactorFlow.kt
@@ -4,25 +4,38 @@
package kotlinx.coroutines.reactor
+import kotlinx.coroutines.*
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.flowOn
import kotlinx.coroutines.reactive.FlowSubscription
+import org.reactivestreams.*
import reactor.core.CoreSubscriber
import reactor.core.publisher.Flux
+import kotlin.coroutines.*
/**
* Converts the given flow to a cold flux.
* The original flow is cancelled when the flux subscriber is disposed.
*
* This function is integrated with [ReactorContext], see its documentation for additional details.
+ *
+ * An optional [context] can be specified to control the execution context of calls to [Subscriber] methods.
+ * You can set a [CoroutineDispatcher] to confine them to a specific thread and/or various [ThreadContextElement] to
+ * inject additional context into the caller thread. By default, the [Unconfined][Dispatchers.Unconfined] dispatcher
+ * is used, so calls are performed from an arbitrary thread.
*/
-public fun <T: Any> Flow<T>.asFlux(): Flux<T> = FlowAsFlux(this)
+@JvmOverloads // binary compatibility
+public fun <T: Any> Flow<T>.asFlux(context: CoroutineContext = EmptyCoroutineContext): Flux<T> =
+ FlowAsFlux(this, Dispatchers.Unconfined + context)
-private class FlowAsFlux<T : Any>(private val flow: Flow<T>) : Flux<T>() {
+private class FlowAsFlux<T : Any>(
+ private val flow: Flow<T>,
+ private val context: CoroutineContext
+) : Flux<T>() {
override fun subscribe(subscriber: CoreSubscriber<in T>?) {
if (subscriber == null) throw NullPointerException()
val hasContext = !subscriber.currentContext().isEmpty
val source = if (hasContext) flow.flowOn(subscriber.currentContext().asCoroutineContext()) else flow
- subscriber.onSubscribe(FlowSubscription(source, subscriber))
+ subscriber.onSubscribe(FlowSubscription(source, subscriber, context))
}
}
diff --git a/reactive/kotlinx-coroutines-reactor/src/Scheduler.kt b/reactive/kotlinx-coroutines-reactor/src/Scheduler.kt
index e176c07..4fb5514 100644
--- a/reactive/kotlinx-coroutines-reactor/src/Scheduler.kt
+++ b/reactive/kotlinx-coroutines-reactor/src/Scheduler.kt
@@ -39,7 +39,7 @@
}
/** @suppress */
- override fun invokeOnTimeout(timeMillis: Long, block: Runnable): DisposableHandle =
+ override fun invokeOnTimeout(timeMillis: Long, block: Runnable, context: CoroutineContext): DisposableHandle =
scheduler.schedule(block, timeMillis, TimeUnit.MILLISECONDS).asDisposableHandle()
/** @suppress */
diff --git a/reactive/kotlinx-coroutines-reactor/test/FlowAsFluxTest.kt b/reactive/kotlinx-coroutines-reactor/test/FlowAsFluxTest.kt
index e4bd8b3..cecc895 100644
--- a/reactive/kotlinx-coroutines-reactor/test/FlowAsFluxTest.kt
+++ b/reactive/kotlinx-coroutines-reactor/test/FlowAsFluxTest.kt
@@ -4,10 +4,13 @@
import kotlinx.coroutines.flow.*
import kotlinx.coroutines.reactive.*
import org.junit.Test
+import org.reactivestreams.*
import reactor.core.publisher.*
import reactor.util.context.Context
+import java.util.concurrent.*
import kotlin.test.*
+@Suppress("ReactiveStreamsSubscriberImplementation")
class FlowAsFluxTest : TestBase() {
@Test
fun testFlowAsFluxContextPropagation() {
@@ -68,4 +71,78 @@
}
finish(4)
}
-}
\ No newline at end of file
+
+ @Test
+ fun testUnconfinedDefaultContext() {
+ expect(1)
+ val thread = Thread.currentThread()
+ fun checkThread() {
+ assertSame(thread, Thread.currentThread())
+ }
+ flowOf(42).asFlux().subscribe(object : Subscriber<Int> {
+ private lateinit var subscription: Subscription
+
+ override fun onSubscribe(s: Subscription) {
+ expect(2)
+ subscription = s
+ subscription.request(2)
+ }
+
+ override fun onNext(t: Int) {
+ checkThread()
+ expect(3)
+ assertEquals(42, t)
+ }
+
+ override fun onComplete() {
+ checkThread()
+ expect(4)
+ }
+
+ override fun onError(t: Throwable?) {
+ expectUnreached()
+ }
+ })
+ finish(5)
+ }
+
+ @Test
+ fun testConfinedContext() {
+ expect(1)
+ val threadName = "FlowAsFluxTest.testConfinedContext"
+ fun checkThread() {
+ val currentThread = Thread.currentThread()
+ assertTrue(currentThread.name.startsWith(threadName), "Unexpected thread $currentThread")
+ }
+ val completed = CountDownLatch(1)
+ newSingleThreadContext(threadName).use { dispatcher ->
+ flowOf(42).asFlux(dispatcher).subscribe(object : Subscriber<Int> {
+ private lateinit var subscription: Subscription
+
+ override fun onSubscribe(s: Subscription) {
+ expect(2)
+ subscription = s
+ subscription.request(2)
+ }
+
+ override fun onNext(t: Int) {
+ checkThread()
+ expect(3)
+ assertEquals(42, t)
+ }
+
+ override fun onComplete() {
+ checkThread()
+ expect(4)
+ completed.countDown()
+ }
+
+ override fun onError(t: Throwable?) {
+ expectUnreached()
+ }
+ })
+ completed.await()
+ }
+ finish(5)
+ }
+}
diff --git a/reactive/kotlinx-coroutines-reactor/test/FluxSingleTest.kt b/reactive/kotlinx-coroutines-reactor/test/FluxSingleTest.kt
index 3879c62..cc336ba 100644
--- a/reactive/kotlinx-coroutines-reactor/test/FluxSingleTest.kt
+++ b/reactive/kotlinx-coroutines-reactor/test/FluxSingleTest.kt
@@ -69,6 +69,72 @@
}
@Test
+ fun testAwaitSingleOrDefault() {
+ val flux = flux {
+ send(Flux.empty<String>().awaitSingleOrDefault("O") + "K")
+ }
+
+ checkSingleValue(flux) {
+ assertEquals("OK", it)
+ }
+ }
+
+ @Test
+ fun testAwaitSingleOrDefaultException() {
+ val flux = flux {
+ send(Flux.just("O", "#").awaitSingleOrDefault("!") + "K")
+ }
+
+ checkErroneous(flux) {
+ assert(it is IllegalArgumentException)
+ }
+ }
+
+ @Test
+ fun testAwaitSingleOrNull() {
+ val flux = flux<String?> {
+ send(Flux.empty<String>().awaitSingleOrNull() ?: "OK")
+ }
+
+ checkSingleValue(flux) {
+ assertEquals("OK", it)
+ }
+ }
+
+ @Test
+ fun testAwaitSingleOrNullException() {
+ val flux = flux {
+ send((Flux.just("O", "#").awaitSingleOrNull() ?: "!") + "K")
+ }
+
+ checkErroneous(flux) {
+ assert(it is IllegalArgumentException)
+ }
+ }
+
+ @Test
+ fun testAwaitSingleOrElse() {
+ val flux = flux {
+ send(Flux.empty<String>().awaitSingleOrElse { "O" } + "K")
+ }
+
+ checkSingleValue(flux) {
+ assertEquals("OK", it)
+ }
+ }
+
+ @Test
+ fun testAwaitSingleOrElseException() {
+ val flux = flux {
+ send(Flux.just("O", "#").awaitSingleOrElse { "!" } + "K")
+ }
+
+ checkErroneous(flux) {
+ assert(it is IllegalArgumentException)
+ }
+ }
+
+ @Test
fun testAwaitFirst() {
val flux = flux {
send(Flux.just("O", "#").awaitFirst() + "K")
diff --git a/reactive/kotlinx-coroutines-rx2/api/kotlinx-coroutines-rx2.api b/reactive/kotlinx-coroutines-rx2/api/kotlinx-coroutines-rx2.api
index 22f4038..4370325 100644
--- a/reactive/kotlinx-coroutines-rx2/api/kotlinx-coroutines-rx2.api
+++ b/reactive/kotlinx-coroutines-rx2/api/kotlinx-coroutines-rx2.api
@@ -30,11 +30,19 @@
public final class kotlinx/coroutines/rx2/RxConvertKt {
public static final fun asCompletable (Lkotlinx/coroutines/Job;Lkotlin/coroutines/CoroutineContext;)Lio/reactivex/Completable;
public static final fun asFlow (Lio/reactivex/ObservableSource;)Lkotlinx/coroutines/flow/Flow;
+ public static final fun asFlowable (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/CoroutineContext;)Lio/reactivex/Flowable;
+ public static synthetic fun asFlowable$default (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/CoroutineContext;ILjava/lang/Object;)Lio/reactivex/Flowable;
public static final fun asMaybe (Lkotlinx/coroutines/Deferred;Lkotlin/coroutines/CoroutineContext;)Lio/reactivex/Maybe;
public static final fun asObservable (Lkotlinx/coroutines/channels/ReceiveChannel;Lkotlin/coroutines/CoroutineContext;)Lio/reactivex/Observable;
+ public static final fun asObservable (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/CoroutineContext;)Lio/reactivex/Observable;
+ public static synthetic fun asObservable$default (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/CoroutineContext;ILjava/lang/Object;)Lio/reactivex/Observable;
public static final fun asSingle (Lkotlinx/coroutines/Deferred;Lkotlin/coroutines/CoroutineContext;)Lio/reactivex/Single;
- public static final fun from (Lkotlinx/coroutines/flow/Flow;)Lio/reactivex/Flowable;
- public static final fun from (Lkotlinx/coroutines/flow/Flow;)Lio/reactivex/Observable;
+ public static final synthetic fun from (Lkotlinx/coroutines/flow/Flow;)Lio/reactivex/Flowable;
+ public static final synthetic fun from (Lkotlinx/coroutines/flow/Flow;)Lio/reactivex/Observable;
+ public static final synthetic fun from (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/CoroutineContext;)Lio/reactivex/Flowable;
+ public static final synthetic fun from (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/CoroutineContext;)Lio/reactivex/Observable;
+ public static synthetic fun from$default (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/CoroutineContext;ILjava/lang/Object;)Lio/reactivex/Flowable;
+ public static synthetic fun from$default (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/CoroutineContext;ILjava/lang/Object;)Lio/reactivex/Observable;
}
public final class kotlinx/coroutines/rx2/RxFlowableKt {
@@ -76,7 +84,7 @@
public fun equals (Ljava/lang/Object;)Z
public final fun getScheduler ()Lio/reactivex/Scheduler;
public fun hashCode ()I
- public fun invokeOnTimeout (JLjava/lang/Runnable;)Lkotlinx/coroutines/DisposableHandle;
+ public fun invokeOnTimeout (JLjava/lang/Runnable;Lkotlin/coroutines/CoroutineContext;)Lkotlinx/coroutines/DisposableHandle;
public fun scheduleResumeAfterDelay (JLkotlinx/coroutines/CancellableContinuation;)V
public fun toString ()Ljava/lang/String;
}
diff --git a/reactive/kotlinx-coroutines-rx2/src/RxChannel.kt b/reactive/kotlinx-coroutines-rx2/src/RxChannel.kt
index e253161..633693e 100644
--- a/reactive/kotlinx-coroutines-rx2/src/RxChannel.kt
+++ b/reactive/kotlinx-coroutines-rx2/src/RxChannel.kt
@@ -64,7 +64,7 @@
@Suppress("INVISIBLE_REFERENCE", "INVISIBLE_MEMBER")
private class SubscriptionChannel<T> :
- LinkedListChannel<T>(), Observer<T>, MaybeObserver<T>
+ LinkedListChannel<T>(null), Observer<T>, MaybeObserver<T>
{
private val _subscription = atomic<Disposable?>(null)
diff --git a/reactive/kotlinx-coroutines-rx2/src/RxConvert.kt b/reactive/kotlinx-coroutines-rx2/src/RxConvert.kt
index 0be606f..41c82ed 100644
--- a/reactive/kotlinx-coroutines-rx2/src/RxConvert.kt
+++ b/reactive/kotlinx-coroutines-rx2/src/RxConvert.kt
@@ -10,12 +10,13 @@
import kotlinx.coroutines.channels.*
import kotlinx.coroutines.flow.*
import kotlinx.coroutines.reactive.*
+import org.reactivestreams.*
import java.util.concurrent.atomic.*
import kotlin.coroutines.*
/**
* Converts this job to the hot reactive completable that signals
- * with [onCompleted][CompletableSubscriber.onCompleted] when the corresponding job completes.
+ * with [onCompleted][CompletableObserver.onComplete] when the corresponding job completes.
*
* Every subscriber gets the signal at the same time.
* Unsubscribing from the resulting completable **does not** affect the original job in any way.
@@ -49,7 +50,7 @@
/**
* Converts this deferred value to the hot reactive single that signals either
- * [onSuccess][SingleSubscriber.onSuccess] or [onError][SingleSubscriber.onError].
+ * [onSuccess][SingleObserver.onSuccess] or [onError][SingleObserver.onError].
*
* Every subscriber gets the same completion value.
* Unsubscribing from the resulting single **does not** affect the original deferred value in any way.
@@ -65,21 +66,6 @@
}
/**
- * Converts a stream of elements received from the channel to the hot reactive observable.
- *
- * Every subscriber receives values from this channel in **fan-out** fashion. If the are multiple subscribers,
- * they'll receive values in round-robin way.
- */
-@Deprecated(
- message = "Deprecated in the favour of Flow",
- level = DeprecationLevel.WARNING, replaceWith = ReplaceWith("this.consumeAsFlow().asObservable()")
-)
-public fun <T : Any> ReceiveChannel<T>.asObservable(context: CoroutineContext): Observable<T> = rxObservable(context) {
- for (t in this@asObservable)
- send(t)
-}
-
-/**
* Transforms given cold [ObservableSource] into cold [Flow].
*
* The resulting flow is _cold_, which means that [ObservableSource.subscribe] is called every time a terminal operator
@@ -95,7 +81,13 @@
val observer = object : Observer<T> {
override fun onComplete() { close() }
override fun onSubscribe(d: Disposable) { if (!disposableRef.compareAndSet(null, d)) d.dispose() }
- override fun onNext(t: T) { sendBlocking(t) }
+ override fun onNext(t: T) {
+ try {
+ sendBlocking(t)
+ } catch (ignored: Throwable) { // TODO: Replace when this issue is fixed: https://github.com/Kotlin/kotlinx.coroutines/issues/974
+ // Is handled by the downstream flow
+ }
+ }
override fun onError(e: Throwable) { close(e) }
}
@@ -106,15 +98,19 @@
/**
* Converts the given flow to a cold observable.
* The original flow is cancelled when the observable subscriber is disposed.
+ *
+ * An optional [context] can be specified to control the execution context of calls to [Observer] methods.
+ * You can set a [CoroutineDispatcher] to confine them to a specific thread and/or various [ThreadContextElement] to
+ * inject additional context into the caller thread. By default, the [Unconfined][Dispatchers.Unconfined] dispatcher
+ * is used, so calls are performed from an arbitrary thread.
*/
-@JvmName("from")
@ExperimentalCoroutinesApi
-public fun <T: Any> Flow<T>.asObservable() : Observable<T> = Observable.create { emitter ->
+public fun <T: Any> Flow<T>.asObservable(context: CoroutineContext = EmptyCoroutineContext) : Observable<T> = Observable.create { emitter ->
/*
* ATOMIC is used here to provide stable behaviour of subscribe+dispose pair even if
* asObservable is already invoked from unconfined
*/
- val job = GlobalScope.launch(Dispatchers.Unconfined, start = CoroutineStart.ATOMIC) {
+ val job = GlobalScope.launch(Dispatchers.Unconfined + context, start = CoroutineStart.ATOMIC) {
try {
collect { value -> emitter.onNext(value) }
emitter.onComplete()
@@ -135,7 +131,35 @@
/**
* Converts the given flow to a cold flowable.
* The original flow is cancelled when the flowable subscriber is disposed.
+ *
+ * An optional [context] can be specified to control the execution context of calls to [Subscriber] methods.
+ * You can set a [CoroutineDispatcher] to confine them to a specific thread and/or various [ThreadContextElement] to
+ * inject additional context into the caller thread. By default, the [Unconfined][Dispatchers.Unconfined] dispatcher
+ * is used, so calls are performed from an arbitrary thread.
*/
-@JvmName("from")
@ExperimentalCoroutinesApi
-public fun <T: Any> Flow<T>.asFlowable(): Flowable<T> = Flowable.fromPublisher(asPublisher())
+public fun <T: Any> Flow<T>.asFlowable(context: CoroutineContext = EmptyCoroutineContext): Flowable<T> =
+ Flowable.fromPublisher(asPublisher(context))
+
+@Deprecated(
+ message = "Deprecated in the favour of Flow",
+ level = DeprecationLevel.ERROR,
+ replaceWith = ReplaceWith("this.consumeAsFlow().asObservable(context)", "kotlinx.coroutines.flow.consumeAsFlow")
+) // Deprecated since 1.4.0
+public fun <T : Any> ReceiveChannel<T>.asObservable(context: CoroutineContext): Observable<T> = rxObservable(context) {
+ for (t in this@asObservable)
+ send(t)
+}
+
+@Suppress("UNUSED") // KT-42513
+@JvmOverloads // binary compatibility
+@JvmName("from")
+@Deprecated(level = DeprecationLevel.HIDDEN, message = "") // Since 1.4, was experimental prior to that
+public fun <T: Any> Flow<T>._asFlowable(context: CoroutineContext = EmptyCoroutineContext): Flowable<T> =
+ asFlowable(context)
+
+@Suppress("UNUSED") // KT-42513
+@JvmOverloads // binary compatibility
+@JvmName("from")
+@Deprecated(level = DeprecationLevel.HIDDEN, message = "") // Since 1.4, was experimental prior to that
+public fun <T: Any> Flow<T>._asObservable(context: CoroutineContext = EmptyCoroutineContext) : Observable<T> = asObservable(context)
diff --git a/reactive/kotlinx-coroutines-rx2/src/RxScheduler.kt b/reactive/kotlinx-coroutines-rx2/src/RxScheduler.kt
index 3ddb676..9952eb9 100644
--- a/reactive/kotlinx-coroutines-rx2/src/RxScheduler.kt
+++ b/reactive/kotlinx-coroutines-rx2/src/RxScheduler.kt
@@ -38,7 +38,7 @@
}
/** @suppress */
- override fun invokeOnTimeout(timeMillis: Long, block: Runnable): DisposableHandle {
+ override fun invokeOnTimeout(timeMillis: Long, block: Runnable, context: CoroutineContext): DisposableHandle {
val disposable = scheduler.scheduleDirect(block, timeMillis, TimeUnit.MILLISECONDS)
return DisposableHandle { disposable.dispose() }
}
diff --git a/reactive/kotlinx-coroutines-rx2/test/ConvertTest.kt b/reactive/kotlinx-coroutines-rx2/test/ConvertTest.kt
index a433665..cfc3240 100644
--- a/reactive/kotlinx-coroutines-rx2/test/ConvertTest.kt
+++ b/reactive/kotlinx-coroutines-rx2/test/ConvertTest.kt
@@ -6,6 +6,7 @@
import kotlinx.coroutines.*
import kotlinx.coroutines.channels.*
+import kotlinx.coroutines.flow.*
import org.junit.Assert
import org.junit.Test
import kotlin.test.*
@@ -126,7 +127,7 @@
delay(50)
send("K")
}
- val observable = c.asObservable(Dispatchers.Unconfined)
+ val observable = c.consumeAsFlow().asObservable(Dispatchers.Unconfined)
checkSingleValue(observable.reduce { t1, t2 -> t1 + t2 }.toSingle()) {
assertEquals("OK", it)
}
@@ -140,7 +141,7 @@
delay(50)
throw TestException("K")
}
- val observable = c.asObservable(Dispatchers.Unconfined)
+ val observable = c.consumeAsFlow().asObservable(Dispatchers.Unconfined)
val single = rxSingle(Dispatchers.Unconfined) {
var result = ""
try {
@@ -155,4 +156,4 @@
assertEquals("OK", it)
}
}
-}
\ No newline at end of file
+}
diff --git a/reactive/kotlinx-coroutines-rx2/test/FlowAsFlowableTest.kt b/reactive/kotlinx-coroutines-rx2/test/FlowAsFlowableTest.kt
new file mode 100644
index 0000000..1cbded6
--- /dev/null
+++ b/reactive/kotlinx-coroutines-rx2/test/FlowAsFlowableTest.kt
@@ -0,0 +1,89 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.rx2
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+import org.junit.Test
+import org.reactivestreams.*
+import java.util.concurrent.*
+import kotlin.test.*
+
+@Suppress("ReactiveStreamsSubscriberImplementation")
+class FlowAsFlowableTest : TestBase() {
+ @Test
+ fun testUnconfinedDefaultContext() {
+ expect(1)
+ val thread = Thread.currentThread()
+ fun checkThread() {
+ assertSame(thread, Thread.currentThread())
+ }
+ flowOf(42).asFlowable().subscribe(object : Subscriber<Int> {
+ private lateinit var subscription: Subscription
+
+ override fun onSubscribe(s: Subscription) {
+ expect(2)
+ subscription = s
+ subscription.request(2)
+ }
+
+ override fun onNext(t: Int) {
+ checkThread()
+ expect(3)
+ assertEquals(42, t)
+ }
+
+ override fun onComplete() {
+ checkThread()
+ expect(4)
+ }
+
+ override fun onError(t: Throwable?) {
+ expectUnreached()
+ }
+ })
+ finish(5)
+ }
+
+ @Test
+ fun testConfinedContext() {
+ expect(1)
+ val threadName = "FlowAsFlowableTest.testConfinedContext"
+ fun checkThread() {
+ val currentThread = Thread.currentThread()
+ assertTrue(currentThread.name.startsWith(threadName), "Unexpected thread $currentThread")
+ }
+ val completed = CountDownLatch(1)
+ newSingleThreadContext(threadName).use { dispatcher ->
+ flowOf(42).asFlowable(dispatcher).subscribe(object : Subscriber<Int> {
+ private lateinit var subscription: Subscription
+
+ override fun onSubscribe(s: Subscription) {
+ expect(2)
+ subscription = s
+ subscription.request(2)
+ }
+
+ override fun onNext(t: Int) {
+ checkThread()
+ expect(3)
+ assertEquals(42, t)
+ }
+
+ override fun onComplete() {
+ checkThread()
+ expect(4)
+ completed.countDown()
+ }
+
+ override fun onError(t: Throwable?) {
+ expectUnreached()
+ }
+ })
+ completed.await()
+ }
+ finish(5)
+ }
+}
diff --git a/reactive/kotlinx-coroutines-rx2/test/FlowAsObservableTest.kt b/reactive/kotlinx-coroutines-rx2/test/FlowAsObservableTest.kt
index 0908b34..3cde182 100644
--- a/reactive/kotlinx-coroutines-rx2/test/FlowAsObservableTest.kt
+++ b/reactive/kotlinx-coroutines-rx2/test/FlowAsObservableTest.kt
@@ -4,9 +4,12 @@
package kotlinx.coroutines.rx2
+import io.reactivex.*
+import io.reactivex.disposables.*
import kotlinx.coroutines.*
import kotlinx.coroutines.flow.*
import org.junit.Test
+import java.util.concurrent.*
import kotlin.test.*
class FlowAsObservableTest : TestBase() {
@@ -139,4 +142,70 @@
observable.subscribe({ expect(2) }, { expectUnreached() }, { finish(3) })
}
+
+ @Test
+ fun testUnconfinedDefaultContext() {
+ expect(1)
+ val thread = Thread.currentThread()
+ fun checkThread() {
+ assertSame(thread, Thread.currentThread())
+ }
+ flowOf(42).asObservable().subscribe(object : Observer<Int> {
+ override fun onSubscribe(d: Disposable) {
+ expect(2)
+ }
+
+ override fun onNext(t: Int) {
+ checkThread()
+ expect(3)
+ assertEquals(42, t)
+ }
+
+ override fun onComplete() {
+ checkThread()
+ expect(4)
+ }
+
+ override fun onError(t: Throwable) {
+ expectUnreached()
+ }
+ })
+ finish(5)
+ }
+
+ @Test
+ fun testConfinedContext() {
+ expect(1)
+ val threadName = "FlowAsObservableTest.testConfinedContext"
+ fun checkThread() {
+ val currentThread = Thread.currentThread()
+ assertTrue(currentThread.name.startsWith(threadName), "Unexpected thread $currentThread")
+ }
+ val completed = CountDownLatch(1)
+ newSingleThreadContext(threadName).use { dispatcher ->
+ flowOf(42).asObservable(dispatcher).subscribe(object : Observer<Int> {
+ override fun onSubscribe(d: Disposable) {
+ expect(2)
+ }
+
+ override fun onNext(t: Int) {
+ checkThread()
+ expect(3)
+ assertEquals(42, t)
+ }
+
+ override fun onComplete() {
+ checkThread()
+ expect(4)
+ completed.countDown()
+ }
+
+ override fun onError(e: Throwable) {
+ expectUnreached()
+ }
+ })
+ completed.await()
+ }
+ finish(5)
+ }
}
diff --git a/reactive/kotlinx-coroutines-rx2/test/IntegrationTest.kt b/reactive/kotlinx-coroutines-rx2/test/IntegrationTest.kt
index 22e0e72..540fa76 100644
--- a/reactive/kotlinx-coroutines-rx2/test/IntegrationTest.kt
+++ b/reactive/kotlinx-coroutines-rx2/test/IntegrationTest.kt
@@ -6,6 +6,7 @@
import io.reactivex.*
import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
import org.junit.Test
import org.junit.runner.*
import org.junit.runners.*
@@ -92,7 +93,7 @@
assertFailsWith<IllegalArgumentException> { observable.awaitSingle() }
checkNumbers(n, observable)
val channel = observable.openSubscription()
- checkNumbers(n, channel.asObservable(ctx(coroutineContext)))
+ checkNumbers(n, channel.consumeAsFlow().asObservable(ctx(coroutineContext)))
channel.cancel()
}
@@ -131,4 +132,4 @@
assertEquals(n, last)
}
-}
\ No newline at end of file
+}
diff --git a/reactive/kotlinx-coroutines-rx2/test/ObservableSourceAsFlowStressTest.kt b/reactive/kotlinx-coroutines-rx2/test/ObservableSourceAsFlowStressTest.kt
new file mode 100644
index 0000000..159f372
--- /dev/null
+++ b/reactive/kotlinx-coroutines-rx2/test/ObservableSourceAsFlowStressTest.kt
@@ -0,0 +1,35 @@
+/*
+ * Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.rx2
+
+import io.reactivex.*
+import kotlinx.coroutines.*
+import kotlinx.coroutines.channels.*
+import kotlinx.coroutines.flow.*
+import org.junit.*
+import java.util.concurrent.*
+
+class ObservableSourceAsFlowStressTest : TestBase() {
+
+ private val iterations = 100 * stressTestMultiplierSqrt
+
+ @Before
+ fun setup() {
+ ignoreLostThreads("RxComputationThreadPool-", "RxCachedWorkerPoolEvictor-", "RxSchedulerPurge-")
+ }
+
+ @Test
+ fun testAsFlowCancellation() = runTest {
+ repeat(iterations) {
+ val latch = Channel<Unit>(1)
+ var i = 0
+ val observable = Observable.interval(100L, TimeUnit.MICROSECONDS)
+ .doOnNext { if (++i > 100) latch.offer(Unit) }
+ val job = observable.asFlow().launchIn(CoroutineScope(Dispatchers.Default))
+ latch.receive()
+ job.cancelAndJoin()
+ }
+ }
+}
diff --git a/reactive/kotlinx-coroutines-rx3/api/kotlinx-coroutines-rx3.api b/reactive/kotlinx-coroutines-rx3/api/kotlinx-coroutines-rx3.api
index 27c3d3d..6d2dd63 100644
--- a/reactive/kotlinx-coroutines-rx3/api/kotlinx-coroutines-rx3.api
+++ b/reactive/kotlinx-coroutines-rx3/api/kotlinx-coroutines-rx3.api
@@ -26,10 +26,18 @@
public final class kotlinx/coroutines/rx3/RxConvertKt {
public static final fun asCompletable (Lkotlinx/coroutines/Job;Lkotlin/coroutines/CoroutineContext;)Lio/reactivex/rxjava3/core/Completable;
public static final fun asFlow (Lio/reactivex/rxjava3/core/ObservableSource;)Lkotlinx/coroutines/flow/Flow;
+ public static final fun asFlowable (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/CoroutineContext;)Lio/reactivex/rxjava3/core/Flowable;
+ public static synthetic fun asFlowable$default (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/CoroutineContext;ILjava/lang/Object;)Lio/reactivex/rxjava3/core/Flowable;
public static final fun asMaybe (Lkotlinx/coroutines/Deferred;Lkotlin/coroutines/CoroutineContext;)Lio/reactivex/rxjava3/core/Maybe;
+ public static final fun asObservable (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/CoroutineContext;)Lio/reactivex/rxjava3/core/Observable;
+ public static synthetic fun asObservable$default (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/CoroutineContext;ILjava/lang/Object;)Lio/reactivex/rxjava3/core/Observable;
public static final fun asSingle (Lkotlinx/coroutines/Deferred;Lkotlin/coroutines/CoroutineContext;)Lio/reactivex/rxjava3/core/Single;
- public static final fun from (Lkotlinx/coroutines/flow/Flow;)Lio/reactivex/rxjava3/core/Flowable;
- public static final fun from (Lkotlinx/coroutines/flow/Flow;)Lio/reactivex/rxjava3/core/Observable;
+ public static final synthetic fun from (Lkotlinx/coroutines/flow/Flow;)Lio/reactivex/rxjava3/core/Flowable;
+ public static final synthetic fun from (Lkotlinx/coroutines/flow/Flow;)Lio/reactivex/rxjava3/core/Observable;
+ public static final synthetic fun from (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/CoroutineContext;)Lio/reactivex/rxjava3/core/Flowable;
+ public static final synthetic fun from (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/CoroutineContext;)Lio/reactivex/rxjava3/core/Observable;
+ public static synthetic fun from$default (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/CoroutineContext;ILjava/lang/Object;)Lio/reactivex/rxjava3/core/Flowable;
+ public static synthetic fun from$default (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/CoroutineContext;ILjava/lang/Object;)Lio/reactivex/rxjava3/core/Observable;
}
public final class kotlinx/coroutines/rx3/RxFlowableKt {
@@ -63,7 +71,7 @@
public fun equals (Ljava/lang/Object;)Z
public final fun getScheduler ()Lio/reactivex/rxjava3/core/Scheduler;
public fun hashCode ()I
- public fun invokeOnTimeout (JLjava/lang/Runnable;)Lkotlinx/coroutines/DisposableHandle;
+ public fun invokeOnTimeout (JLjava/lang/Runnable;Lkotlin/coroutines/CoroutineContext;)Lkotlinx/coroutines/DisposableHandle;
public fun scheduleResumeAfterDelay (JLkotlinx/coroutines/CancellableContinuation;)V
public fun toString ()Ljava/lang/String;
}
diff --git a/reactive/kotlinx-coroutines-rx3/src/RxChannel.kt b/reactive/kotlinx-coroutines-rx3/src/RxChannel.kt
index acb907b..737cf67 100644
--- a/reactive/kotlinx-coroutines-rx3/src/RxChannel.kt
+++ b/reactive/kotlinx-coroutines-rx3/src/RxChannel.kt
@@ -54,7 +54,7 @@
@Suppress("INVISIBLE_REFERENCE", "INVISIBLE_MEMBER")
private class SubscriptionChannel<T> :
- LinkedListChannel<T>(), Observer<T>, MaybeObserver<T>
+ LinkedListChannel<T>(null), Observer<T>, MaybeObserver<T>
{
private val _subscription = atomic<Disposable?>(null)
diff --git a/reactive/kotlinx-coroutines-rx3/src/RxConvert.kt b/reactive/kotlinx-coroutines-rx3/src/RxConvert.kt
index f9e2e21..0978423 100644
--- a/reactive/kotlinx-coroutines-rx3/src/RxConvert.kt
+++ b/reactive/kotlinx-coroutines-rx3/src/RxConvert.kt
@@ -10,12 +10,13 @@
import kotlinx.coroutines.channels.*
import kotlinx.coroutines.flow.*
import kotlinx.coroutines.reactive.*
+import org.reactivestreams.*
import java.util.concurrent.atomic.*
import kotlin.coroutines.*
/**
* Converts this job to the hot reactive completable that signals
- * with [onCompleted][CompletableSubscriber.onCompleted] when the corresponding job completes.
+ * with [onCompleted][CompletableObserver.onComplete] when the corresponding job completes.
*
* Every subscriber gets the signal at the same time.
* Unsubscribing from the resulting completable **does not** affect the original job in any way.
@@ -49,7 +50,7 @@
/**
* Converts this deferred value to the hot reactive single that signals either
- * [onSuccess][SingleSubscriber.onSuccess] or [onError][SingleSubscriber.onError].
+ * [onSuccess][SingleObserver.onSuccess] or [onError][SingleObserver.onError].
*
* Every subscriber gets the same completion value.
* Unsubscribing from the resulting single **does not** affect the original deferred value in any way.
@@ -80,7 +81,13 @@
val observer = object : Observer<T> {
override fun onComplete() { close() }
override fun onSubscribe(d: Disposable) { if (!disposableRef.compareAndSet(null, d)) d.dispose() }
- override fun onNext(t: T) { sendBlocking(t) }
+ override fun onNext(t: T) {
+ try {
+ sendBlocking(t)
+ } catch (ignored: Throwable) { // TODO: Replace when this issue is fixed: https://github.com/Kotlin/kotlinx.coroutines/issues/974
+ // Is handled by the downstream flow
+ }
+ }
override fun onError(e: Throwable) { close(e) }
}
@@ -91,15 +98,19 @@
/**
* Converts the given flow to a cold observable.
* The original flow is cancelled when the observable subscriber is disposed.
+ *
+ * An optional [context] can be specified to control the execution context of calls to [Observer] methods.
+ * You can set a [CoroutineDispatcher] to confine them to a specific thread and/or various [ThreadContextElement] to
+ * inject additional context into the caller thread. By default, the [Unconfined][Dispatchers.Unconfined] dispatcher
+ * is used, so calls are performed from an arbitrary thread.
*/
-@JvmName("from")
@ExperimentalCoroutinesApi
-public fun <T: Any> Flow<T>.asObservable() : Observable<T> = Observable.create { emitter ->
+public fun <T: Any> Flow<T>.asObservable(context: CoroutineContext = EmptyCoroutineContext) : Observable<T> = Observable.create { emitter ->
/*
* ATOMIC is used here to provide stable behaviour of subscribe+dispose pair even if
* asObservable is already invoked from unconfined
*/
- val job = GlobalScope.launch(Dispatchers.Unconfined, start = CoroutineStart.ATOMIC) {
+ val job = GlobalScope.launch(Dispatchers.Unconfined + context, start = CoroutineStart.ATOMIC) {
try {
collect { value -> emitter.onNext(value) }
emitter.onComplete()
@@ -120,7 +131,25 @@
/**
* Converts the given flow to a cold flowable.
* The original flow is cancelled when the flowable subscriber is disposed.
+ *
+ * An optional [context] can be specified to control the execution context of calls to [Subscriber] methods.
+ * You can set a [CoroutineDispatcher] to confine them to a specific thread and/or various [ThreadContextElement] to
+ * inject additional context into the caller thread. By default, the [Unconfined][Dispatchers.Unconfined] dispatcher
+ * is used, so calls are performed from an arbitrary thread.
*/
-@JvmName("from")
@ExperimentalCoroutinesApi
-public fun <T: Any> Flow<T>.asFlowable(): Flowable<T> = Flowable.fromPublisher(asPublisher())
+public fun <T: Any> Flow<T>.asFlowable(context: CoroutineContext = EmptyCoroutineContext): Flowable<T> =
+ Flowable.fromPublisher(asPublisher(context))
+
+@Suppress("UNUSED") // KT-42513
+@JvmOverloads // binary compatibility
+@JvmName("from")
+@Deprecated(level = DeprecationLevel.HIDDEN, message = "") // Since 1.4, was experimental prior to that
+public fun <T: Any> Flow<T>._asFlowable(context: CoroutineContext = EmptyCoroutineContext): Flowable<T> =
+ asFlowable(context)
+
+@Suppress("UNUSED") // KT-42513
+@JvmOverloads // binary compatibility
+@JvmName("from")
+@Deprecated(level = DeprecationLevel.HIDDEN, message = "") // Since 1.4, was experimental prior to that
+public fun <T: Any> Flow<T>._asObservable(context: CoroutineContext = EmptyCoroutineContext) : Observable<T> = asObservable(context)
diff --git a/reactive/kotlinx-coroutines-rx3/src/RxScheduler.kt b/reactive/kotlinx-coroutines-rx3/src/RxScheduler.kt
index 6e91aee..a426aea 100644
--- a/reactive/kotlinx-coroutines-rx3/src/RxScheduler.kt
+++ b/reactive/kotlinx-coroutines-rx3/src/RxScheduler.kt
@@ -38,7 +38,7 @@
}
/** @suppress */
- override fun invokeOnTimeout(timeMillis: Long, block: Runnable): DisposableHandle {
+ override fun invokeOnTimeout(timeMillis: Long, block: Runnable, context: CoroutineContext): DisposableHandle {
val disposable = scheduler.scheduleDirect(block, timeMillis, TimeUnit.MILLISECONDS)
return DisposableHandle { disposable.dispose() }
}
diff --git a/reactive/kotlinx-coroutines-rx3/test/FlowAsFlowableTest.kt b/reactive/kotlinx-coroutines-rx3/test/FlowAsFlowableTest.kt
new file mode 100644
index 0000000..a73fee4
--- /dev/null
+++ b/reactive/kotlinx-coroutines-rx3/test/FlowAsFlowableTest.kt
@@ -0,0 +1,89 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.rx3
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+import org.junit.Test
+import org.reactivestreams.*
+import java.util.concurrent.*
+import kotlin.test.*
+
+@Suppress("ReactiveStreamsSubscriberImplementation")
+class FlowAsFlowableTest : TestBase() {
+ @Test
+ fun testUnconfinedDefaultContext() {
+ expect(1)
+ val thread = Thread.currentThread()
+ fun checkThread() {
+ assertSame(thread, Thread.currentThread())
+ }
+ flowOf(42).asFlowable().subscribe(object : Subscriber<Int> {
+ private lateinit var subscription: Subscription
+
+ override fun onSubscribe(s: Subscription) {
+ expect(2)
+ subscription = s
+ subscription.request(2)
+ }
+
+ override fun onNext(t: Int) {
+ checkThread()
+ expect(3)
+ assertEquals(42, t)
+ }
+
+ override fun onComplete() {
+ checkThread()
+ expect(4)
+ }
+
+ override fun onError(t: Throwable?) {
+ expectUnreached()
+ }
+ })
+ finish(5)
+ }
+
+ @Test
+ fun testConfinedContext() {
+ expect(1)
+ val threadName = "FlowAsFlowableTest.testConfinedContext"
+ fun checkThread() {
+ val currentThread = Thread.currentThread()
+ assertTrue(currentThread.name.startsWith(threadName), "Unexpected thread $currentThread")
+ }
+ val completed = CountDownLatch(1)
+ newSingleThreadContext(threadName).use { dispatcher ->
+ flowOf(42).asFlowable(dispatcher).subscribe(object : Subscriber<Int> {
+ private lateinit var subscription: Subscription
+
+ override fun onSubscribe(s: Subscription) {
+ expect(2)
+ subscription = s
+ subscription.request(2)
+ }
+
+ override fun onNext(t: Int) {
+ checkThread()
+ expect(3)
+ assertEquals(42, t)
+ }
+
+ override fun onComplete() {
+ checkThread()
+ expect(4)
+ completed.countDown()
+ }
+
+ override fun onError(t: Throwable?) {
+ expectUnreached()
+ }
+ })
+ completed.await()
+ }
+ finish(5)
+ }
+}
diff --git a/reactive/kotlinx-coroutines-rx3/test/FlowAsObservableTest.kt b/reactive/kotlinx-coroutines-rx3/test/FlowAsObservableTest.kt
index 50c4ae7..5759f9f 100644
--- a/reactive/kotlinx-coroutines-rx3/test/FlowAsObservableTest.kt
+++ b/reactive/kotlinx-coroutines-rx3/test/FlowAsObservableTest.kt
@@ -4,9 +4,12 @@
package kotlinx.coroutines.rx3
+import io.reactivex.rxjava3.core.*
+import io.reactivex.rxjava3.disposables.*
import kotlinx.coroutines.*
import kotlinx.coroutines.flow.*
import org.junit.Test
+import java.util.concurrent.*
import kotlin.test.*
class FlowAsObservableTest : TestBase() {
@@ -139,4 +142,70 @@
observable.subscribe({ expect(2) }, { expectUnreached() }, { finish(3) })
}
+
+ @Test
+ fun testUnconfinedDefaultContext() {
+ expect(1)
+ val thread = Thread.currentThread()
+ fun checkThread() {
+ assertSame(thread, Thread.currentThread())
+ }
+ flowOf(42).asObservable().subscribe(object : Observer<Int> {
+ override fun onSubscribe(d: Disposable) {
+ expect(2)
+ }
+
+ override fun onNext(t: Int) {
+ checkThread()
+ expect(3)
+ assertEquals(42, t)
+ }
+
+ override fun onComplete() {
+ checkThread()
+ expect(4)
+ }
+
+ override fun onError(t: Throwable) {
+ expectUnreached()
+ }
+ })
+ finish(5)
+ }
+
+ @Test
+ fun testConfinedContext() {
+ expect(1)
+ val threadName = "FlowAsObservableTest.testConfinedContext"
+ fun checkThread() {
+ val currentThread = Thread.currentThread()
+ assertTrue(currentThread.name.startsWith(threadName), "Unexpected thread $currentThread")
+ }
+ val completed = CountDownLatch(1)
+ newSingleThreadContext(threadName).use { dispatcher ->
+ flowOf(42).asObservable(dispatcher).subscribe(object : Observer<Int> {
+ override fun onSubscribe(d: Disposable) {
+ expect(2)
+ }
+
+ override fun onNext(t: Int) {
+ checkThread()
+ expect(3)
+ assertEquals(42, t)
+ }
+
+ override fun onComplete() {
+ checkThread()
+ expect(4)
+ completed.countDown()
+ }
+
+ override fun onError(e: Throwable) {
+ expectUnreached()
+ }
+ })
+ completed.await()
+ }
+ finish(5)
+ }
}
diff --git a/reactive/kotlinx-coroutines-rx3/test/ObservableSourceAsFlowStressTest.kt b/reactive/kotlinx-coroutines-rx3/test/ObservableSourceAsFlowStressTest.kt
new file mode 100644
index 0000000..431a7a7
--- /dev/null
+++ b/reactive/kotlinx-coroutines-rx3/test/ObservableSourceAsFlowStressTest.kt
@@ -0,0 +1,36 @@
+/*
+ * Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.rx3
+
+import io.reactivex.rxjava3.core.*
+import io.reactivex.rxjava3.exceptions.*
+import kotlinx.coroutines.*
+import kotlinx.coroutines.channels.*
+import kotlinx.coroutines.flow.*
+import org.junit.*
+import java.util.concurrent.*
+
+class ObservableSourceAsFlowStressTest : TestBase() {
+
+ private val iterations = 100 * stressTestMultiplierSqrt
+
+ @Before
+ fun setup() {
+ ignoreLostThreads("RxComputationThreadPool-", "RxCachedWorkerPoolEvictor-", "RxSchedulerPurge-")
+ }
+
+ @Test
+ fun testAsFlowCancellation() = runTest {
+ repeat(iterations) {
+ val latch = Channel<Unit>(1)
+ var i = 0
+ val observable = Observable.interval(100L, TimeUnit.MICROSECONDS)
+ .doOnNext { if (++i > 100) latch.offer(Unit) }
+ val job = observable.asFlow().launchIn(CoroutineScope(Dispatchers.Default))
+ latch.receive()
+ job.cancelAndJoin()
+ }
+ }
+}
diff --git a/settings.gradle b/settings.gradle
index d22d65f..3a07891 100644
--- a/settings.gradle
+++ b/settings.gradle
@@ -8,7 +8,7 @@
// JMH
id "net.ltgt.apt" version "0.21"
- id "me.champeau.gradle.jmh" version "0.5.0"
+ id "me.champeau.gradle.jmh" version "0.5.2"
}
}
diff --git a/site/build.gradle.kts b/site/build.gradle.kts
index a18062a..eba7b1a 100644
--- a/site/build.gradle.kts
+++ b/site/build.gradle.kts
@@ -7,7 +7,7 @@
val buildDocsDir = "$buildDir/docs"
val jekyllDockerImage = "jekyll/jekyll:${version("jekyll")}"
-val copyDocs = tasks.register<Copy>("copyDocs") {
+val copyDocs by tasks.registering(Copy::class) {
val dokkaTasks = rootProject.getTasksByName("dokka", true)
from(dokkaTasks.map { "${it.project.buildDir}/dokka" }) {
@@ -21,12 +21,12 @@
dependsOn(dokkaTasks)
}
-val copyExampleFrontendJs = tasks.register<Copy>("copyExampleFrontendJs") {
+val copyExampleFrontendJs by tasks.registering(Copy::class) {
val srcBuildDir = project(":example-frontend-js").buildDir
from("$srcBuildDir/dist")
into("$buildDocsDir/example-frontend-js")
- dependsOn(":example-frontend-js:bundle")
+ dependsOn(":example-frontend-js:browserDistribution")
}
tasks.register<Exec>("site") {
diff --git a/ui/coroutines-guide-ui.md b/ui/coroutines-guide-ui.md
index 071f794..9c1251f 100644
--- a/ui/coroutines-guide-ui.md
+++ b/ui/coroutines-guide-ui.md
@@ -110,7 +110,7 @@
`app/build.gradle` file:
```groovy
-implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.3.8"
+implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.4.1"
```
You can clone [kotlinx.coroutines](https://github.com/Kotlin/kotlinx.coroutines) project from GitHub onto your
@@ -310,7 +310,7 @@
controls the implementation of the channel that this actor is using for its mailbox. The description of all
the available choices is given in documentation of the [`Channel()`][Channel] factory function.
-Let us change the code to use `ConflatedChannel` by passing [Channel.CONFLATED] capacity value. The
+Let us change the code to use a conflated channel by passing [Channel.CONFLATED] capacity value. The
change is only to the line that creates an actor:
```kotlin
diff --git a/ui/kotlinx-coroutines-android/android-unit-tests/test/ordered/tests/TestComponent.kt b/ui/kotlinx-coroutines-android/android-unit-tests/test/ordered/tests/TestComponent.kt
index 9cf813b..c677d99 100644
--- a/ui/kotlinx-coroutines-android/android-unit-tests/test/ordered/tests/TestComponent.kt
+++ b/ui/kotlinx-coroutines-android/android-unit-tests/test/ordered/tests/TestComponent.kt
@@ -21,7 +21,7 @@
fun launchDelayed() {
scope.launch {
- delay(Long.MAX_VALUE)
+ delay(Long.MAX_VALUE / 2)
delayedLaunchCompleted = true
}
}
diff --git a/ui/kotlinx-coroutines-android/animation-app/gradle.properties b/ui/kotlinx-coroutines-android/animation-app/gradle.properties
index 0be3b9c..c4aa675 100644
--- a/ui/kotlinx-coroutines-android/animation-app/gradle.properties
+++ b/ui/kotlinx-coroutines-android/animation-app/gradle.properties
@@ -20,8 +20,8 @@
# http://www.gradle.org/docs/current/userguide/multi_project_builds.html#sec:decoupled_projects
# org.gradle.parallel=true
-kotlin_version=1.3.71
-coroutines_version=1.3.8
+kotlin_version=1.4.0
+coroutines_version=1.4.1
android.useAndroidX=true
android.enableJetifier=true
diff --git a/ui/kotlinx-coroutines-android/api/kotlinx-coroutines-android.api b/ui/kotlinx-coroutines-android/api/kotlinx-coroutines-android.api
index b97d846..090c14e 100644
--- a/ui/kotlinx-coroutines-android/api/kotlinx-coroutines-android.api
+++ b/ui/kotlinx-coroutines-android/api/kotlinx-coroutines-android.api
@@ -1,7 +1,7 @@
public abstract class kotlinx/coroutines/android/HandlerDispatcher : kotlinx/coroutines/MainCoroutineDispatcher, kotlinx/coroutines/Delay {
public fun delay (JLkotlin/coroutines/Continuation;)Ljava/lang/Object;
public abstract fun getImmediate ()Lkotlinx/coroutines/android/HandlerDispatcher;
- public fun invokeOnTimeout (JLjava/lang/Runnable;)Lkotlinx/coroutines/DisposableHandle;
+ public fun invokeOnTimeout (JLjava/lang/Runnable;Lkotlin/coroutines/CoroutineContext;)Lkotlinx/coroutines/DisposableHandle;
}
public final class kotlinx/coroutines/android/HandlerDispatcherKt {
diff --git a/ui/kotlinx-coroutines-android/build.gradle.kts b/ui/kotlinx-coroutines-android/build.gradle.kts
index 4be32fc..4f24788 100644
--- a/ui/kotlinx-coroutines-android/build.gradle.kts
+++ b/ui/kotlinx-coroutines-android/build.gradle.kts
@@ -6,10 +6,6 @@
import org.jetbrains.dokka.gradle.DokkaTask
import java.net.URL
-repositories {
- google()
-}
-
configurations {
create("r8")
}
@@ -25,59 +21,20 @@
"r8"("com.android.tools.build:builder:4.0.0-alpha06") // Contains r8-2.0.4-dev
}
-open class RunR8Task : JavaExec() {
-
- @OutputDirectory
- lateinit var outputDex: File
-
- @InputFile
- lateinit var inputConfig: File
-
- @InputFile
- val inputConfigCommon: File = File("testdata/r8-test-common.pro")
-
- @InputFiles
- val jarFile: File = project.tasks.named<Zip>("jar").get().archivePath
-
- init {
- classpath = project.configurations["r8"]
- main = "com.android.tools.r8.R8"
- }
-
- override fun exec() {
- // Resolve classpath only during execution
- val arguments = mutableListOf(
- "--release",
- "--no-desugaring",
- "--output", outputDex.absolutePath,
- "--pg-conf", inputConfig.absolutePath
- )
- arguments.addAll(project.configurations.runtimeClasspath.files.map { it.absolutePath })
- arguments.add(jarFile.absolutePath)
-
- args = arguments
-
- project.delete(outputDex)
- outputDex.mkdirs()
-
- super.exec()
- }
-}
-
val optimizedDexDir = File(buildDir, "dex-optim/")
val unOptimizedDexDir = File(buildDir, "dex-unoptim/")
val optimizedDexFile = File(optimizedDexDir, "classes.dex")
val unOptimizedDexFile = File(unOptimizedDexDir, "classes.dex")
-val runR8 = tasks.register<RunR8Task>("runR8") {
+val runR8 by tasks.registering(RunR8::class) {
outputDex = optimizedDexDir
inputConfig = file("testdata/r8-test-rules.pro")
dependsOn("jar")
}
-val runR8NoOptim = tasks.register<RunR8Task>("runR8NoOptim") {
+val runR8NoOptim by tasks.registering(RunR8::class) {
outputDex = unOptimizedDexDir
inputConfig = file("testdata/r8-test-rules-no-optim.pro")
@@ -100,9 +57,6 @@
}
}
-tasks.withType<DokkaTask>().configureEach {
- externalDocumentationLink(delegateClosureOf<ExternalDocumentationLink.Builder> {
- url = URL("https://developer.android.com/reference/")
- packageListUrl = projectDir.toPath().resolve("package.list").toUri().toURL()
- })
-}
+externalDocumentationLink(
+ url = "https://developer.android.com/reference/"
+)
diff --git a/ui/kotlinx-coroutines-android/example-app/gradle.properties b/ui/kotlinx-coroutines-android/example-app/gradle.properties
index 0be3b9c..c4aa675 100644
--- a/ui/kotlinx-coroutines-android/example-app/gradle.properties
+++ b/ui/kotlinx-coroutines-android/example-app/gradle.properties
@@ -20,8 +20,8 @@
# http://www.gradle.org/docs/current/userguide/multi_project_builds.html#sec:decoupled_projects
# org.gradle.parallel=true
-kotlin_version=1.3.71
-coroutines_version=1.3.8
+kotlin_version=1.4.0
+coroutines_version=1.4.1
android.useAndroidX=true
android.enableJetifier=true
diff --git a/ui/kotlinx-coroutines-android/resources/META-INF/com.android.tools/r8-from-1.6.0/coroutines.pro b/ui/kotlinx-coroutines-android/resources/META-INF/com.android.tools/r8-from-1.6.0/coroutines.pro
index fd25b21..0d04990 100644
--- a/ui/kotlinx-coroutines-android/resources/META-INF/com.android.tools/r8-from-1.6.0/coroutines.pro
+++ b/ui/kotlinx-coroutines-android/resources/META-INF/com.android.tools/r8-from-1.6.0/coroutines.pro
@@ -9,6 +9,8 @@
boolean ANDROID_DETECTED return true;
}
+-keep class kotlinx.coroutines.android.AndroidDispatcherFactory {*;}
+
# Disable support for "Missing Main Dispatcher", since we always have Android main dispatcher
-assumenosideeffects class kotlinx.coroutines.internal.MainDispatchersKt {
boolean SUPPORT_MISSING return false;
diff --git a/ui/kotlinx-coroutines-android/src/HandlerDispatcher.kt b/ui/kotlinx-coroutines-android/src/HandlerDispatcher.kt
index 1693409..af79da7 100644
--- a/ui/kotlinx-coroutines-android/src/HandlerDispatcher.kt
+++ b/ui/kotlinx-coroutines-android/src/HandlerDispatcher.kt
@@ -140,7 +140,7 @@
continuation.invokeOnCancellation { handler.removeCallbacks(block) }
}
- override fun invokeOnTimeout(timeMillis: Long, block: Runnable): DisposableHandle {
+ override fun invokeOnTimeout(timeMillis: Long, block: Runnable, context: CoroutineContext): DisposableHandle {
handler.postDelayed(block, timeMillis.coerceAtMost(MAX_DELAY))
return object : DisposableHandle {
override fun dispose() {
diff --git a/ui/kotlinx-coroutines-javafx/api/kotlinx-coroutines-javafx.api b/ui/kotlinx-coroutines-javafx/api/kotlinx-coroutines-javafx.api
index 620e904..e2c3b8f 100644
--- a/ui/kotlinx-coroutines-javafx/api/kotlinx-coroutines-javafx.api
+++ b/ui/kotlinx-coroutines-javafx/api/kotlinx-coroutines-javafx.api
@@ -5,7 +5,7 @@
public abstract class kotlinx/coroutines/javafx/JavaFxDispatcher : kotlinx/coroutines/MainCoroutineDispatcher, kotlinx/coroutines/Delay {
public fun delay (JLkotlin/coroutines/Continuation;)Ljava/lang/Object;
public fun dispatch (Lkotlin/coroutines/CoroutineContext;Ljava/lang/Runnable;)V
- public fun invokeOnTimeout (JLjava/lang/Runnable;)Lkotlinx/coroutines/DisposableHandle;
+ public fun invokeOnTimeout (JLjava/lang/Runnable;Lkotlin/coroutines/CoroutineContext;)Lkotlinx/coroutines/DisposableHandle;
public fun scheduleResumeAfterDelay (JLkotlinx/coroutines/CancellableContinuation;)V
}
diff --git a/ui/kotlinx-coroutines-javafx/build.gradle b/ui/kotlinx-coroutines-javafx/build.gradle
deleted file mode 100644
index 77f1b09..0000000
--- a/ui/kotlinx-coroutines-javafx/build.gradle
+++ /dev/null
@@ -1,34 +0,0 @@
-/*
- * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
- */
-
-plugins {
- id 'org.openjfx.javafxplugin'
-}
-
-javafx {
- version = javafx_version
- modules = ['javafx.controls']
- configuration = 'compile'
-}
-
-task checkJdk8() {
- // only fail w/o JDK_18 when actually trying to test, not during project setup phase
- doLast {
- if (!System.env.JDK_18) {
- throw new GradleException("JDK_18 environment variable is not defined. " +
- "Can't run JDK 8 compatibility tests. " +
- "Please ensure JDK 8 is installed and that JDK_18 points to it.")
- }
- }
-}
-
-task jdk8Test(type: Test, dependsOn: [compileTestKotlin, checkJdk8]) {
- classpath = files { test.classpath }
- testClassesDirs = files { test.testClassesDirs }
- executable = "$System.env.JDK_18/bin/java"
-}
-
-// Run these tests only during nightly stress test
-jdk8Test.onlyIf { project.properties['stressTest'] != null }
-build.dependsOn jdk8Test
diff --git a/ui/kotlinx-coroutines-javafx/build.gradle.kts b/ui/kotlinx-coroutines-javafx/build.gradle.kts
new file mode 100644
index 0000000..112441e
--- /dev/null
+++ b/ui/kotlinx-coroutines-javafx/build.gradle.kts
@@ -0,0 +1,50 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+plugins {
+ id("org.openjfx.javafxplugin")
+}
+
+javafx {
+ version = version("javafx")
+ modules = listOf("javafx.controls")
+ configuration = "compile"
+}
+
+val JDK_18: String? by lazy {
+ System.getenv("JDK_18")
+}
+
+val checkJdk8 by tasks.registering {
+ // only fail w/o JDK_18 when actually trying to test, not during project setup phase
+ doLast {
+ if (JDK_18 == null) {
+ throw GradleException(
+ """
+ JDK_18 environment variable is not defined.
+ Can't run JDK 8 compatibility tests.
+ Please ensure JDK 8 is installed and that JDK_18 points to it.
+ """.trimIndent()
+ )
+ }
+ }
+}
+
+val jdk8Test by tasks.registering(Test::class) {
+ // Run these tests only during nightly stress test
+ onlyIf { project.properties["stressTest"] != null }
+
+ val test = tasks.test.get()
+
+ classpath = test.classpath
+ testClassesDirs = test.testClassesDirs
+ executable = "$JDK_18/bin/java"
+
+ dependsOn("compileTestKotlin")
+ dependsOn(checkJdk8)
+}
+
+tasks.build {
+ dependsOn(jdk8Test)
+}
diff --git a/ui/kotlinx-coroutines-javafx/src/JavaFxConvert.kt b/ui/kotlinx-coroutines-javafx/src/JavaFxConvert.kt
index 903b60a..c7fcb1c 100644
--- a/ui/kotlinx-coroutines-javafx/src/JavaFxConvert.kt
+++ b/ui/kotlinx-coroutines-javafx/src/JavaFxConvert.kt
@@ -24,7 +24,7 @@
* Adjacent applications of [flowOn], [buffer], [conflate], and [produceIn] to the result of `asFlow` are fused.
* [conflate] has no effect, as this flow is already conflated; one can use [buffer] to change that instead.
*/
-@ExperimentalCoroutinesApi
+@ExperimentalCoroutinesApi // Since 1.3.x
public fun <T> ObservableValue<T>.asFlow(): Flow<T> = callbackFlow<T> {
val listener = ChangeListener<T> { _, _, newValue ->
try {
diff --git a/ui/kotlinx-coroutines-javafx/src/JavaFxDispatcher.kt b/ui/kotlinx-coroutines-javafx/src/JavaFxDispatcher.kt
index a13a683..c3069d6 100644
--- a/ui/kotlinx-coroutines-javafx/src/JavaFxDispatcher.kt
+++ b/ui/kotlinx-coroutines-javafx/src/JavaFxDispatcher.kt
@@ -42,7 +42,7 @@
}
/** @suppress */
- override fun invokeOnTimeout(timeMillis: Long, block: Runnable): DisposableHandle {
+ override fun invokeOnTimeout(timeMillis: Long, block: Runnable, context: CoroutineContext): DisposableHandle {
val timeline = schedule(timeMillis, TimeUnit.MILLISECONDS, EventHandler {
block.run()
})
diff --git a/ui/kotlinx-coroutines-swing/api/kotlinx-coroutines-swing.api b/ui/kotlinx-coroutines-swing/api/kotlinx-coroutines-swing.api
index 09556e8..d33191f 100644
--- a/ui/kotlinx-coroutines-swing/api/kotlinx-coroutines-swing.api
+++ b/ui/kotlinx-coroutines-swing/api/kotlinx-coroutines-swing.api
@@ -1,7 +1,7 @@
public abstract class kotlinx/coroutines/swing/SwingDispatcher : kotlinx/coroutines/MainCoroutineDispatcher, kotlinx/coroutines/Delay {
public fun delay (JLkotlin/coroutines/Continuation;)Ljava/lang/Object;
public fun dispatch (Lkotlin/coroutines/CoroutineContext;Ljava/lang/Runnable;)V
- public fun invokeOnTimeout (JLjava/lang/Runnable;)Lkotlinx/coroutines/DisposableHandle;
+ public fun invokeOnTimeout (JLjava/lang/Runnable;Lkotlin/coroutines/CoroutineContext;)Lkotlinx/coroutines/DisposableHandle;
public fun scheduleResumeAfterDelay (JLkotlinx/coroutines/CancellableContinuation;)V
}
diff --git a/ui/kotlinx-coroutines-swing/src/SwingDispatcher.kt b/ui/kotlinx-coroutines-swing/src/SwingDispatcher.kt
index 77f109d..054ed1f 100644
--- a/ui/kotlinx-coroutines-swing/src/SwingDispatcher.kt
+++ b/ui/kotlinx-coroutines-swing/src/SwingDispatcher.kt
@@ -36,7 +36,7 @@
}
/** @suppress */
- override fun invokeOnTimeout(timeMillis: Long, block: Runnable): DisposableHandle {
+ override fun invokeOnTimeout(timeMillis: Long, block: Runnable, context: CoroutineContext): DisposableHandle {
val timer = schedule(timeMillis, TimeUnit.MILLISECONDS, ActionListener {
block.run()
})
