1# Change log for kotlinx.coroutines 2 3## Version 1.7.0 4 5### Core API significant improvements 6 7* New `Channel` implementation with significant performance improvements across the API (#3621). 8* New `select` operator implementation: faster, more lightweight, and more robust (#3020). 9* `Mutex` and `Semaphore` now share the same underlying data structure (#3020). 10* `Dispatchers.IO` is added to K/N (#3205) 11 * `newFixedThreadPool` and `Dispatchers.Default` implementations on K/N were wholly rewritten to support graceful growth under load (#3595). 12* `kotlinx-coroutines-test` rework: 13 - Add the `timeout` parameter to `runTest` for the whole-test timeout, 10 seconds by default (#3270). This replaces the configuration of quiescence timeouts, which is now deprecated (#3603). 14 - The `withTimeout` exception messages indicate if the timeout used the virtual time (#3588). 15 - `TestCoroutineScheduler`, `runTest`, and `TestScope` API are promoted to stable (#3622). 16 - `runTest` now also fails if there were uncaught exceptions in coroutines not inherited from the test coroutine (#1205). 17 18### Breaking changes 19 20* Old K/N memory model is no longer supported (#3375). 21* New generic upper bounds were added to reactive integration API where the language since 1.8.0 dictates (#3393). 22* `kotlinx-coroutines-core` and `kotlinx-coroutines-jdk8` artifacts were merged into a single artifact (#3268). 23* Artificial stackframes in stacktrace recovery no longer contain the `\b` symbol and are now navigable in IDE and supplied with proper documentation (#2291). 24* `CoroutineContext.isActive` returns `true` for contexts without any job in them (#3300). 25 26### Bug fixes and improvements 27 28* Kotlin version is updated to 1.8.20 29* Atomicfu version is updated to 0.20.2. 30* `JavaFx` version is updated to 17.0.2 in `kotlinx-coroutines-javafx` (#3671).. 31* JPMS is supported (#2237). Thanks @lion7! 32* `BroadcastChannel` and all the corresponding API are deprecated (#2680). 33* Added all supported K/N targets (#3601, #812, #855). 34* K/N `Dispatchers.Default` is backed by the number of threads equal to the number of available cores (#3366). 35* Fixed an issue where some coroutines' internal exceptions were not properly serializable (#3328). 36* Introduced `Job.parent` API (#3201). 37* Fixed a bug when `TestScheduler` leaked cancelled jobs (#3398). 38* `TestScope.timeSource` now provides comparable time marks (#3617). Thanks @hfhbd! 39* Fixed an issue when cancelled `withTimeout` handles were preserved in JS runtime (#3440). 40* Ensure `awaitFrame` only awaits a single frame when used from the main looper (#3432). Thanks @pablobaxter! 41* Obsolete `Class-Path` attribute was removed from `kotlinx-coroutines-debug.jar` manifest (#3361). 42* Fixed a bug when `updateThreadContext` operated on the parent context (#3411). 43* Added new `Flow.filterIsInstance` extension (#3240). 44* `Dispatchers.Default` thread name prefixes are now configurable with system property (#3231). 45* Added `Flow.timeout` operator as `@FlowPreview` (#2624). Thanks @pablobaxter! 46* Improved the performance of the `future` builder in case of exceptions (#3475). Thanks @He-Pin! 47* `Mono.awaitSingleOrNull` now waits for the `onComplete` signal (#3487). 48* `Channel.isClosedForSend` and `Channel.isClosedForReceive` are promoted from experimental to delicate (#3448). 49* Fixed a data race in native `EventLoop` (#3547). 50* `Dispatchers.IO.limitedParallelism(valueLargerThanIOSize)` no longer creates an additional wrapper (#3442). Thanks @dovchinnikov! 51* Various `@FlowPreview` and `@ExperimentalCoroutinesApi` are promoted to experimental and stable respectively (#3542, #3097, #3548). 52* Performance improvements in `Dispatchers.Default` and `Dispatchers.IO` (#3416, #3418). 53* Fixed a bug when internal `suspendCancellableCoroutineReusable` might have hanged (#3613). 54* Introduced internal API to process events in the current system dispatcher (#3439). 55* Global `CoroutineExceptionHandler` is no longer invoked in case of unprocessed `future` failure (#3452). 56* Performance improvements and reduced thread-local pressure for the `withContext` operator (#3592). 57* Improved performance of `DebugProbes` (#3527). 58* Fixed a bug when the coroutine debugger might have detected the state of a coroutine incorrectly (#3193). 59* `CoroutineDispatcher.asExecutor()` runs tasks without dispatching if the dispatcher is unconfined (#3683). Thanks @odedniv! 60* `SharedFlow.toMutableList` and `SharedFlow.toSet` lints are introduced (#3706). 61* `Channel.invokeOnClose` is promoted to stable API (#3358). 62* Improved lock contention in `Dispatchers.Default` and `Dispatchers.IO` during the startup phase (#3652). 63* Fixed a bug that led to threads oversubscription in `Dispatchers.Default` (#3642). 64* Fixed a bug that allowed `limitedParallelism` to perform dispatches even after the underlying dispatcher was closed (#3672). 65* Fixed a bug that prevented stacktrace recovery when the exception's constructor from `cause` was selected (#3714). 66* Improved sanitizing of stracktrace-recovered traces (#3714). 67* Introduced an internal flag to disable uncaught exceptions reporting in tests as a temporary migration mechanism (#3736). 68* Various documentation improvements and fixes. 69 70### Changelog relative to version 1.7.0-RC 71 72* Fixed a bug that prevented stacktrace recovery when the exception's constructor from `cause` was selected (#3714). 73* Improved sanitizing of stracktrace-recovered traces (#3714). 74* Introduced an internal flag to disable uncaught exceptions reporting in tests as a temporary migration mechanism (#3736). 75 76## Version 1.7.0-RC 77 78* Kotlin version is updated to 1.8.20. 79* Atomicfu version is updated to 0.20.2. 80* `JavaFx` version is updated to 17.0.2 in `kotlinx-coroutines-javafx` (#3671). 81* `previous-compilation-data.bin` file is removed from JAR resources (#3668). 82* `CoroutineDispatcher.asExecutor()` runs tasks without dispatching if the dispatcher is unconfined (#3683). Thanks @odedniv! 83* `SharedFlow.toMutableList` lint overload is undeprecated (#3706). 84* `Channel.invokeOnClose` is promoted to stable API (#3358). 85* Improved lock contention in `Dispatchers.Default` and `Dispatchers.IO` during the startup phase (#3652). 86* Fixed a bug that led to threads oversubscription in `Dispatchers.Default` (#3642). 87* Fixed a bug that allowed `limitedParallelism` to perform dispatches even after the underlying dispatcher was closed (#3672). 88* Restored binary compatibility of previously experimental `TestScope.runTest(Long)` (#3673). 89 90## Version 1.7.0-Beta 91 92### Core API significant improvements 93 94* New `Channel` implementation with significant performance improvements across the API (#3621). 95* New `select` operator implementation: faster, more lightweight, and more robust (#3020). 96* `Mutex` and `Semaphore` now share the same underlying data structure (#3020). 97* `Dispatchers.IO` is added to K/N (#3205) 98 * `newFixedThreadPool` and `Dispatchers.Default` implementations on K/N were wholly rewritten to support graceful growth under load (#3595). 99* `kotlinx-coroutines-test` rework: 100 - Add the `timeout` parameter to `runTest` for the whole-test timeout, 10 seconds by default (#3270). This replaces the configuration of quiescence timeouts, which is now deprecated (#3603). 101 - The `withTimeout` exception messages indicate if the timeout used the virtual time (#3588). 102 - `TestCoroutineScheduler`, `runTest`, and `TestScope` API are promoted to stable (#3622). 103 - `runTest` now also fails if there were uncaught exceptions in coroutines not inherited from the test coroutine (#1205). 104 105### Breaking changes 106 107* Old K/N memory model is no longer supported (#3375). 108* New generic upper bounds were added to reactive integration API where the language since 1.8.0 dictates (#3393). 109* `kotlinx-coroutines-core` and `kotlinx-coroutines-jdk8` artifacts were merged into a single artifact (#3268). 110* Artificial stackframes in stacktrace recovery no longer contain the `\b` symbol and are now navigable in IDE and supplied with proper documentation (#2291). 111* `CoroutineContext.isActive` returns `true` for contexts without any job in them (#3300). 112 113### Bug fixes and improvements 114 115* Kotlin version is updated to 1.8.10. 116* JPMS is supported (#2237). Thanks @lion7! 117* `BroadcastChannel` and all the corresponding API are deprecated (#2680). 118* Added all supported K/N targets (#3601, #812, #855). 119* K/N `Dispatchers.Default` is backed by the number of threads equal to the number of available cores (#3366). 120* Fixed an issue where some coroutines' internal exceptions were not properly serializable (#3328). 121* Introduced `Job.parent` API (#3201). 122* Fixed a bug when `TestScheduler` leaked cancelled jobs (#3398). 123* `TestScope.timeSource` now provides comparable time marks (#3617). Thanks @hfhbd! 124* Fixed an issue when cancelled `withTimeout` handles were preserved in JS runtime (#3440). 125* Ensure `awaitFrame` only awaits a single frame when used from the main looper (#3432). Thanks @pablobaxter! 126* Obsolete `Class-Path` attribute was removed from `kotlinx-coroutines-debug.jar` manifest (#3361). 127* Fixed a bug when `updateThreadContext` operated on the parent context (#3411). 128* Added new `Flow.filterIsInstance` extension (#3240). 129* `Dispatchers.Default` thread name prefixes are now configurable with system property (#3231). 130* Added `Flow.timeout` operator as `@FlowPreview` (#2624). Thanks @pablobaxter! 131* Improved the performance of the `future` builder in case of exceptions (#3475). Thanks @He-Pin! 132* `Mono.awaitSingleOrNull` now waits for the `onComplete` signal (#3487). 133* `Channel.isClosedForSend` and `Channel.isClosedForReceive` are promoted from experimental to delicate (#3448). 134* Fixed a data race in native `EventLoop` (#3547). 135* `Dispatchers.IO.limitedParallelism(valueLargerThanIOSize)` no longer creates an additional wrapper (#3442). Thanks @dovchinnikov! 136* Various `@FlowPreview` and `@ExperimentalCoroutinesApi` are promoted to experimental and stable respectively (#3542, #3097, #3548). 137* Performance improvements in `Dispatchers.Default` and `Dispatchers.IO` (#3416, #3418). 138* Fixed a bug when internal `suspendCancellableCoroutineReusable` might have hanged (#3613). 139* Introduced internal API to process events in the current system dispatcher (#3439). 140* Global `CoroutineExceptionHandler` is no longer invoked in case of unprocessed `future` failure (#3452). 141* Performance improvements and reduced thread-local pressure for the `withContext` operator (#3592). 142* Improved performance of `DebugProbes` (#3527). 143* Fixed a bug when the coroutine debugger might have detected the state of a coroutine incorrectly (#3193). 144* Various documentation improvements and fixes. 145 146## Version 1.6.4 147 148* Added `TestScope.backgroundScope` for launching coroutines that perform work in the background and need to be cancelled at the end of the test (#3287). 149* Fixed the POM of `kotlinx-coroutines-debug` having an incorrect reference to `kotlinx-coroutines-bom`, which cause the builds of Maven projects using the debug module to break (#3334). 150* Fixed the `Publisher.await` functions in `kotlinx-coroutines-reactive` not ensuring that the `Subscriber` methods are invoked serially (#3360). Thank you, @EgorKulbachka! 151* Fixed a memory leak in `withTimeout` on K/N with the new memory model (#3351). 152* Added the guarantee that all `Throwable` implementations in the core library are serializable (#3328). 153* Moved the documentation to <https://kotlinlang.org/api/kotlinx.coroutines/> (#3342). 154* Various documentation improvements. 155 156## Version 1.6.3 157 158* Updated atomicfu version to 0.17.3 (#3321), fixing the projects using this library with JS IR failing to build (#3305). 159 160## Version 1.6.2 161 162* Fixed a bug with `ThreadLocalElement` not being correctly updated when the most outer `suspend` function was called directly without `kotlinx.coroutines` (#2930). 163* Fixed multiple data races: one that might have been affecting `runBlocking` event loop, and a benign data race in `Mutex` (#3250, #3251). 164* Obsolete `TestCoroutineContext` is removed, which fixes the `kotlinx-coroutines-test` JPMS package being split between `kotlinx-coroutines-core` and `kotlinx-coroutines-test` (#3218). 165* Updated the ProGuard rules to further shrink the size of the resulting DEX file with coroutines (#3111, #3263). Thanks, @agrieve! 166* Atomicfu is updated to `0.17.2`, which includes a more efficient and robust JS IR transformer (#3255). 167* Kotlin is updated to `1.6.21`, Gradle version is updated to `7.4.2` (#3281). Thanks, @wojtek-kalicinski! 168* Various documentation improvements. 169 170## Version 1.6.1 171 172* Rollback of time-related functions dispatching on `Dispatchers.Main`. 173 This behavior was introduced in 1.6.0 and then found inconvenient and erroneous (#3106, #3113). 174* Reworked the newly-introduced `CopyableThreadContextElement` to solve issues uncovered after the initial release (#3227). 175* Fixed a bug with `ThreadLocalElement` not being properly updated in racy scenarios (#2930). 176* Reverted eager loading of default `CoroutineExceptionHandler` that triggered ANR on some devices (#3180). 177* New API to convert a `CoroutineDispatcher` to a Rx scheduler (#968, #548). Thanks @recheej! 178* Fixed a memory leak with the very last element emitted from `flow` builder being retained in memory (#3197). 179* Fixed a bug with `limitedParallelism` on K/N with new memory model throwing `ClassCastException` (#3223). 180* `CoroutineContext` is added to the exception printed to the default `CoroutineExceptionHandler` to improve debuggability (#3153). 181* Static memory consumption of `Dispatchers.Default` was significantly reduced (#3137). 182* Updated slf4j version in `kotlinx-coroutines-slf4j` from 1.7.25 to 1.7.32. 183 184## Version 1.6.0 185 186Note that this is a full changelog relative to the 1.5.2 version. Changelog relative to 1.6.0-RC3 can be found at the end. 187 188### kotlinx-coroutines-test rework 189 190* `kotlinx-coroutines-test` became a multiplatform library usable from K/JVM, K/JS, and K/N. 191* Its API was completely reworked to address long-standing issues with consistency, structured concurrency and correctness (#1203, #1609, #2379, #1749, #1204, #1390, #1222, #1395, #1881, #1910, #1772, #1626, #1742, #2082, #2102, #2405, #2462 192 ). 193* The old API is deprecated for removal, but the new API is based on the similar concepts ([README](kotlinx-coroutines-test/README.md)), and the migration path is designed to be graceful: [migration guide](kotlinx-coroutines-test/MIGRATION.md). 194 195### Dispatchers 196 197* Introduced `CoroutineDispatcher.limitedParallelism` that allows obtaining a view of the original dispatcher with limited parallelism (#2919). 198* `Dispatchers.IO.limitedParallelism` usages ignore the bound on the parallelism level of `Dispatchers.IO` itself to avoid starvation (#2943). 199* Introduced new `Dispatchers.shutdown` method for containerized environments (#2558). 200* `newSingleThreadContext` and `newFixedThreadPoolContext` are promoted to delicate API (#2919). 201 202### Breaking changes 203 204* When racing with cancellation, the `future` builder no longer reports unhandled exceptions into the global `CoroutineExceptionHandler`. Thanks @vadimsemenov! (#2774, #2791). 205* `Mutex.onLock` is deprecated for removal (#2794). 206* `Dispatchers.Main` is now used as the default source of time for `delay` and `withTimeout` when present(#2972). 207 * To opt-out from this behaviour, `kotlinx.coroutines.main.delay` system property can be set to `false`. 208* Java target of coroutines build is now 8 instead of 6 (#1589). 209* **Source-breaking change**: extension `collect` no longer resolves when used with a non-in-place argument of a functional type. This is a candidate for a fix, uncovered after 1.6.0, see #3107 for the additional details. 210 211### Bug fixes and improvements 212 213* Kotlin is updated to 1.6.0. 214* Kotlin/Native [new memory model](https://blog.jetbrains.com/kotlin/2021/08/try-the-new-kotlin-native-memory-manager-development-preview/) is now supported in regular builds of coroutines conditionally depending on whether `kotlin.native.binary.memoryModel` is enabled (#2914). 215* Introduced `CopyableThreadContextElement` for mutable context elements shared among multiple coroutines. Thanks @yorickhenning! (#2893). 216* `transformWhile`, `awaitClose`, `ProducerScope`, `merge`, `runningFold`, `runingReduce`, and `scan` are promoted to stable API (#2971). 217* `SharedFlow.subscriptionCount` no longer conflates incoming updates and gives all subscribers a chance to observe a short-lived subscription (#2488, #2863, #2871). 218* `Flow` exception transparency mechanism is improved to be more exception-friendly (#3017, #2860). 219* Cancellation from `flat*` operators that leverage multiple coroutines is no longer propagated upstream (#2964). 220* `SharedFlow.collect` now returns `Nothing` (#2789, #2502). 221* `DisposableHandle` is now `fun interface`, and corresponding inline extension is removed (#2790). 222* `FlowCollector` is now `fun interface`, and corresponding inline extension is removed (#3047). 223* Deprecation level of all previously deprecated signatures is raised (#3024). 224* The version file is shipped with each JAR as a resource (#2941). 225* Unhandled exceptions on K/N are passed to the standard library function `processUnhandledException` (#2981). 226* A direct executor is used for `Task` callbacks in `kotlinx-coroutines-play-services` (#2990). 227* Metadata of coroutines artifacts leverages Gradle platform to have all versions of dependencies aligned (#2865). 228* Default `CoroutineExceptionHandler` is loaded eagerly and does not invoke `ServiceLoader` on its exception-handling path (#2552). 229* Fixed the R8 rules for `ServiceLoader` optimization (#2880). 230* Fixed BlockHound integration false-positives (#2894, #2866, #2937). 231* Fixed the exception handler being invoked several times on Android, thanks to @1zaman (#3056). 232* `SendChannel.trySendBlocking` is now available on Kotlin/Native (#3064). 233* The exception recovery mechanism now uses `ClassValue` when available (#2997). 234* JNA is updated to 5.9.0 to support Apple M1 (#3001). 235* Obsolete method on internal `Delay` interface is deprecated (#2979). 236* Support of deprecated `CommonPool` is removed. 237* `@ExperimentalTime` is no longer needed for methods that use `Duration` (#3041). 238* JDK 1.6 is no longer required for building the project (#3043). 239* New version of Dokka is used, fixing the memory leak when building the coroutines and providing brand new reference visuals (https://kotlinlang.org/api/kotlinx.coroutines/) (#3051, #3054). 240 241### Changelog relative to version 1.6.0-RC3 242 243* Restored MPP binary compatibility on K/JS and K/N (#3104). 244* Fixed Dispatchers.Main not being fully initialized on Android and Swing (#3101). 245 246## Version 1.6.0-RC3 247 248* Fixed the error in 1.6.0-RC2 because of which `Flow.collect` couldn't be called due to the `@InternalCoroutinesApi` annotation (#3082) 249* Fixed some R8 warnings introduced in 1.6.0-RC (#3090) 250* `TestCoroutineScheduler` now provides a `TimeSource` with its virtual time via the `timeSource` property. Thanks @hfhbd! (#3087) 251 252## Version 1.6.0-RC2 253 254* `@ExperimentalTime` is no longer needed for methods that use `Duration` (#3041). 255* `FlowCollector` is now `fun interface`, and corresponding inline extension is removed (#3047). 256* Fixed the exception handler being invoked several times on Android, thanks to @1zaman (#3056). 257* The deprecated `TestCoroutineScope` is no longer sealed, to simplify migration from it (#3072). 258* `runTest` gives more informative errors when it times out waiting for external completion (#3071). 259* `SendChannel.trySendBlocking` is now available on Kotlin/Native (#3064). 260* Fixed the bug due to which `Dispatchers.Main` was not used for `delay` and `withTimeout` (#3046). 261* JDK 1.6 is no longer required for building the project (#3043). 262* New version of Dokka is used, fixing the memory leak when building the coroutines and providing brand new reference visuals (https://kotlinlang.org/api/kotlinx.coroutines/) (#3051, #3054). 263 264## Version 1.6.0-RC 265 266### kotlinx-coroutines-test rework 267 268* `kotlinx-coroutines-test` became a multiplatform library usable from K/JVM, K/JS, and K/N. 269* Its API was completely reworked to address long-standing issues with consistency, structured concurrency and correctness (#1203, #1609, #2379, #1749, #1204, #1390, #1222, #1395, #1881, #1910, #1772, #1626, #1742, #2082, #2102, #2405, #2462 270 ). 271* The old API is deprecated for removal, but the new API is based on the similar concepts ([README](kotlinx-coroutines-test/README.md)), and the migration path is designed to be graceful: [migration guide](kotlinx-coroutines-test/MIGRATION.md) 272 273### Dispatchers 274 275* Introduced `CoroutineDispatcher.limitedParallelism` that allows obtaining a view of the original dispatcher with limited parallelism (#2919). 276* `Dispatchers.IO.limitedParallelism` usages ignore the bound on the parallelism level of `Dispatchers.IO` itself to avoid starvation (#2943). 277* Introduced new `Dispatchers.shutdown` method for containerized environments (#2558). 278* `newSingleThreadContext` and `newFixedThreadPoolContext` are promoted to delicate API (#2919). 279 280### Breaking changes 281 282* When racing with cancellation, the `future` builder no longer reports unhandled exceptions into the global `CoroutineExceptionHandler`. Thanks @vadimsemenov! (#2774, #2791). 283* `Mutex.onLock` is deprecated for removal (#2794). 284* `Dispatchers.Main` is now used as the default source of time for `delay` and `withTimeout` when present(#2972). 285 * To opt-out from this behaviour, `kotlinx.coroutines.main.delay` system property can be set to `false`. 286* Java target of coroutines build is now 8 instead of 6 (#1589). 287 288### Bug fixes and improvements 289 290* Kotlin is updated to 1.6.0. 291* Kotlin/Native [new memory model](https://blog.jetbrains.com/kotlin/2021/08/try-the-new-kotlin-native-memory-manager-development-preview/) is now supported in regular builds of coroutines conditionally depending on whether `kotlin.native.binary.memoryModel` is enabled (#2914). 292* Introduced `CopyableThreadContextElement` for mutable context elements shared among multiple coroutines. Thanks @yorickhenning! (#2893). 293* `transformWhile`, `awaitClose`, `ProducerScope`, `merge`, `runningFold`, `runingReduce`, and `scan` are promoted to stable API (#2971). 294* `SharedFlow.subscriptionCount` no longer conflates incoming updates and gives all subscribers a chance to observe a short-lived subscription (#2488, #2863, #2871). 295* `Flow` exception transparency mechanism is improved to be more exception-friendly (#3017, #2860). 296* Cancellation from `flat*` operators that leverage multiple coroutines is no longer propagated upstream (#2964). 297* `SharedFlow.collect` now returns `Nothing` (#2789, #2502). 298* `DisposableHandle` is now `fun interface`, and corresponding inline extension is removed (#2790). 299* Deprecation level of all previously deprecated signatures is raised (#3024). 300* The version file is shipped with each JAR as a resource (#2941). 301* Unhandled exceptions on K/N are passed to the standard library function `processUnhandledException` (#2981). 302* A direct executor is used for `Task` callbacks in `kotlinx-coroutines-play-services` (#2990). 303* Metadata of coroutines artifacts leverages Gradle platform to have all versions of dependencies aligned (#2865). 304* Default `CoroutineExceptionHandler` is loaded eagerly and does not invoke `ServiceLoader` on its exception-handling path (#2552). 305* Fixed the R8 rules for `ServiceLoader` optimization (#2880). 306* Fixed BlockHound integration false-positives (#2894, #2866, #2937). 307* The exception recovery mechanism now uses `ClassValue` when available (#2997). 308* JNA is updated to 5.9.0 to support Apple M1 (#3001). 309* Obsolete method on internal `Delay` interface is deprecated (#2979). 310* Support of deprecated `CommonPool` is removed. 311 312## Version 1.5.2 313 314* Kotlin is updated to 1.5.30. 315* New native targets for Apple Silicon are introduced. 316* Fixed a bug when `onUndeliveredElement` was incorrectly called on a properly received elements on JS (#2826). 317* Fixed `Dispatchers.Default` on React Native, it now fully relies on `setTimeout` instead of stub `process.nextTick`. Thanks to @Legion2 (#2843). 318* Optimizations of `Mutex` implementation (#2581). 319* `Mutex` implementation is made completely lock-free as stated (#2590). 320* Various documentation and guides improvements. Thanks to @MasoodFallahpoor and @Pihanya. 321 322## Version 1.5.1 323 324* Atomic `update`, `getAndUpdate`, and `updateAndGet` operations of `MutableStateFlow` (#2720). 325* `Executor.asCoroutineDispatcher` implementation improvements (#2601): 326 * If the target executor is `ScheduledExecutorService`, then its `schedule` API is used for time-related coroutine operations. 327 * `RemoveOnCancelPolicy` is now part of the public contract. 328* Introduced overloads for `Task.asDeferred` and `Task.await` that accept `CancellationTokenSource` for bidirectional cancellation (#2527). 329* Reactive streams are updated to `1.0.3` (#2740). 330* `CopyableThrowable` is allowed to modify the exception message during stacktrace recovery (#1931). 331* `CoroutineDispatcher.releaseInterceptedContinuation` is now a `final` method (#2785). 332* Closing a Handler underlying `Handler.asCoroutineDispatcher` now causes the dispatched coroutines to be canceled on `Dispatchers.IO (#2778)`. 333* Kotlin is updated to 1.5.20. 334* Fixed a spurious `ClassCastException` in `releaseInterceptedContinuation` and `IllegalStateException` from `tryReleaseClaimedContinuation` (#2736, #2768). 335* Fixed inconsistent exception message during stacktrace recovery for non-suspending channel iterators (#2749). 336* Fixed linear stack usage for `CompletableFuture.asDeferred` when the target future has a long chain of listeners (#2730). 337* Any exceptions from `CoroutineDispatcher.isDispatchNeeded` are now considered as fatal and are propagated to the caller (#2733). 338* Internal `DebugProbesKt` (used in the debugger implementation) are moved from `debug` to `core` module. 339 340## Version 1.5.0 341 342Note that this is a full changelog relative to 1.4.3 version. Changelog relative to 1.5.0-RC can be found in the end. 343 344### Channels API 345 346* Major channels API rework (#330, #974). Existing `offer`, `poll`, and `sendBlocking` methods are deprecated, internal `receiveCatching` and `onReceiveCatching` removed, `receiveOrNull` and `onReceiveOrNull` are completely deprecated. Previously deprecated `SendChannel.isFull` declaration is removed. Channel operators deprecated with `ERROR` are now `HIDDEN`. 347* New methods `receiveCatching`, `onReceiveCatching` `trySend`, `tryReceive`, and `trySendBlocking` along with the new result type `ChannelResult` are introduced. They provide better type safety, are less error-prone, and have a consistent future-proof naming scheme. The full rationale behind this change can be found [here](https://github.com/Kotlin/kotlinx.coroutines/issues/974#issuecomment-806569582). 348* `BroadcastChannel` and `ConflatedBroadcastChannel` are marked as `ObsoleteCoroutinesApi` in the favor or `SharedFlow` and `StateFlow`. The migration scheme can be found in their documentation. These classes will be deprecated in the next major release. 349* `callbackFlow` and `channelFlow` are promoted to stable API. 350 351### Reactive integrations 352 353* All existing API in modules `kotlinx-coroutines-rx2`, `kotlinx-coroutines-rx3`, `kotlinx-coroutines-reactive`, `kotlinx-coroutines-reactor`, and `kotlinx-coroutines-jdk9` were revisited and promoted to stable (#2545). 354* `publish` is no longer allowed to emit `null` values (#2646). 355* Misleading `awaitSingleOr*` functions on `Publisher` type are deprecated (#2591). 356* `MaybeSource.await` is deprecated in the favor of `awaitSingle`, additional lint functions for `Mono` are added in order to prevent ambiguous `Publisher` usages (#2628, #1587). 357* `ContextView` support in `kotlinx-coroutines-reactor` (#2575). 358* All reactive builders no longer ignore inner cancellation exceptions preventing their completion (#2262, #2646). 359* `MaybeSource.collect` and `Maybe.collect` properly finish when they are completed without a value (#2617). 360* All exceptions are now consistently handled according to reactive specification, whether they are considered 'fatal' or not by reactive frameworks (#2646). 361 362### Other improvements 363 364* Kotlin version is upgraded to 1.5.0 and JVM target is updated to 1.8. 365* `Flow.last` and `Flow.lastOrNull` operators (#2246). 366* `Flow.runningFold` operator (#2641). 367* `CoroutinesTimeout` rule for JUnit5 (#2197). 368* Internals of `Job` and `AbstractCoroutine` was reworked, resulting in smaller code size, less memory footprint, and better performance (#2513, #2512). 369* `CancellationException` from Kotlin standard library is used for cancellation on Kotlin/JS and Kotlin/Native (#2638). 370* Introduced new `DelicateCoroutinesApi` annotation that warns users about potential target API pitfalls and suggests studying API's documentation first. The only delicate API right now is `GlobalScope` (#2637). 371* Fixed bug introduced in `1.4.3` when `kotlinx-coroutines-core.jar` triggered IDEA debugger failure (#2619). 372* Fixed memory leak of `ChildHandlerNode` with reusable continuations (#2564). 373* Various documentation improvements (#2555, #2589, #2592, #2583, #2437, #2616, #2633, #2560). 374 375### Changelog relative to version 1.5.0-RC 376 377* Fail-fast during `emitAll` called from cancelled `onCompletion` operator (#2700). 378* Flows returned by `stateIn`/`shareIn` keep strong reference to sharing job (#2557). 379* Rename internal `TimeSource` to `AbstractTimeSource` due to import issues (#2691). 380* Reverted the change that triggered IDEA coroutines debugger crash (#2695, reverted #2291). 381* `watchosX64` target support for Kotlin/Native (#2524). 382* Various documentation fixes and improvements. 383 384## Version 1.5.0-RC 385 386### Channels API 387 388* Major channels API rework (#330, #974). Existing `offer`, `poll`, and `sendBlocking` methods are deprecated, internal `receiveCatching` and `onReceiveCatching` removed, `receiveOrNull` and `onReceiveOrNull` are completely deprecated. Previously deprecated `SendChannel.isFull` declaration is removed. Channel operators deprecated with `ERROR` are now `HIDDEN`. 389* New methods `receiveCatching`, `onReceiveCatching` `trySend`, `tryReceive`, and `trySendBlocking` along with the new result type `ChannelResult` are introduced. They provide better type safety, are less error-prone, and have a consistent future-proof naming scheme. The full rationale behind this change can be found [here](https://github.com/Kotlin/kotlinx.coroutines/issues/974#issuecomment-806569582). 390* `BroadcastChannel` and `ConflatedBroadcastChannel` are marked as `ObsoleteCoroutinesApi` in the favor or `SharedFlow` and `StateFlow`. The migration scheme can be found in their documentation. These classes will be deprecated in the next major release. 391* `callbackFlow` and `channelFlow` are promoted to stable API. 392 393### Reactive integrations 394 395* All existing API in modules `kotlinx-coroutines-rx2`, `kotlinx-coroutines-rx3`, `kotlinx-coroutines-reactive`, `kotlinx-coroutines-reactor`, and `kotlinx-coroutines-jdk9` were revisited and promoted to stable (#2545). 396* `publish` is no longer allowed to emit `null` values (#2646). 397* Misleading `awaitSingleOr*` functions on `Publisher` type are deprecated (#2591). 398* `MaybeSource.await` is deprecated in the favor of `awaitSingle`, additional lint functions for `Mono` are added in order to prevent ambiguous `Publisher` usages (#2628, #1587). 399* `ContextView` support in `kotlinx-coroutines-reactor` (#2575). 400* All reactive builders no longer ignore inner cancellation exceptions preventing their completion (#2262, #2646). 401* `MaybeSource.collect` and `Maybe.collect` properly finish when they are completed without a value (#2617). 402* All exceptions are now consistently handled according to reactive specification, whether they are considered 'fatal' or not by reactive frameworks (#2646). 403 404### Other improvements 405 406* `Flow.last` and `Flow.lastOrNull` operators (#2246). 407* `Flow.runningFold` operator (#2641). 408* `CoroutinesTimeout` rule for JUnit5 (#2197). 409* Internals of `Job` and `AbstractCoroutine` was reworked, resulting in smaller code size, less memory footprint, and better performance (#2513, #2512). 410* `CancellationException` from Kotlin standard library is used for cancellation on Kotlin/JS and Kotlin/Native (#2638). 411* Introduced new `DelicateCoroutineApi` annotation that warns users about potential target API pitfalls and suggests studying API's documentation first. The only delicate API right now is `GlobalScope` (#2637). 412* Fixed bug introduced in `1.4.3` when `kotlinx-coroutines-core.jar` triggered IDEA debugger failure (#2619). 413* Fixed memory leak of `ChildHandlerNode` with reusable continuations (#2564). 414* Various documentation improvements (#2555, #2589, #2592, #2583, #2437, #2616, #2633, #2560). 415 416## Version 1.4.3 417 418### General changes 419 420* Thread context is properly preserved and restored for coroutines without `ThreadContextElement` (#985) 421* `ThreadContextElement`s are now restored in the opposite order from update (#2195) 422* Improved performance of combine with 4 parameters, thanks to @alexvanyo (#2419) 423* Debug agent sanitizer leaves at least one frame with source location (#1437) 424* Update Reactor version in `kotlinx-coroutines-reactor` to `3.4.1`, thanks to @sokomishalov (#2432) 425* `callInPlace` contract added to `ReceiveChannel.consume` (#941) 426* `CoroutineStart.UNDISPATCHED` promoted to stable API (#1393) 427* Kotlin updated to 1.4.30 428* `kotlinx.coroutines` are now released directly to MavenCentral 429* Reduced the size of `DispatchedCoroutine` by a field 430* Internal class `TimeSource` renamed to `SchedulerTimeSource` to prevent wildcard import issues (#2537) 431 432### Bug fixes 433 434* Fixed the problem that prevented implementation via delegation for `Job` interface (#2423) 435* Fixed incorrect ProGuard rules that allowed shrinking volatile felds (#1564) 436* Fixed `await`/`asDeferred` for `MinimalStage` implementations in jdk8 module (#2456) 437* Fixed bug when `onUndeliveredElement` wasn't called for unlimited channels (#2435) 438* Fixed a bug when `ListenableFuture.isCancelled` returned from `asListenableFuture` could have thrown an exception, thanks to @vadimsemenov (#2421) 439* Coroutine in `callbackFlow` and `produce` is properly cancelled when the channel was closed separately (#2506) 440 441## Version 1.4.2 442 443* Fixed `StackOverflowError` in `Job.toString` when `Job` is observed in its intermediate state (#2371). 444* Improved liveness and latency of `Dispatchers.Default` and `Dispatchers.IO` in low-loaded mode (#2381). 445* Improved performance of consecutive `Channel.cancel` invocations (#2384). 446* `SharingStarted` is now `fun` interface (#2397). 447* Additional lint settings for `SharedFlow` to catch programmatic errors early (#2376). 448* Fixed bug when mutex and semaphore were not released during cancellation (#2390, thanks to @Tilps for reproducing). 449* Some corner cases in cancellation propagation between coroutines and listenable futures are repaired (#1442, thanks to @vadimsemenov). 450* Fixed unconditional cast to `CoroutineStackFrame` in exception recovery that triggered failures of instrumented code (#2386). 451* Platform-specific dependencies are removed from `kotlinx-coroutines-javafx` (#2360). 452 453## Version 1.4.1 454 455This is a patch release with an important fix to the `SharedFlow` implementation. 456 457* SharedFlow: Fix scenario with concurrent emitters and cancellation of subscriber (#2359, thanks to @vehovsky for the bug report). 458 459## Version 1.4.0 460 461### Improvements 462 463* `StateFlow`, `SharedFlow` and corresponding operators are promoted to stable API (#2316). 464* `Flow.debounce` operator with timeout selector based on each individual element is added (#1216, thanks to @mkano9!). 465* `CoroutineContext.job` extension property is introduced (#2159). 466* `Flow.combine operator` is reworked: 467 * Complete fairness is maintained for single-threaded dispatchers. 468 * Its performance is improved, depending on the use-case, by at least 50% (#2296). 469 * Quadratic complexity depending on the number of upstream flows is eliminated (#2296). 470 * `crossinline` and `inline`-heavy internals are removed, fixing sporadic SIGSEGV on Mediatek Android devices (#1683, #1743). 471* `Flow.zip` operator performance is improved by 40%. 472* Various API has been promoted to stable or its deprecation level has been raised (#2316). 473 474### Bug fixes 475 476* Suspendable `stateIn` operator propagates exception to the caller when upstream fails to produce initial value (#2329). 477* Fix `SharedFlow` with replay for subscribers working at different speed (#2325). 478* Do not fail debug agent installation when security manager does not provide access to system properties (#2311). 479* Cancelled lazy coroutines are properly cleaned up from debug agent output (#2294). 480* `BlockHound` false-positives are correctly filtered out (#2302, #2190, #2303). 481* Potential crash during a race between cancellation and upstream in `Observable.asFlow` is fixed (#2104, #2299, thanks to @LouisCAD and @drinkthestars). 482 483## Version 1.4.0-M1 484 485### Breaking changes 486 487* The concept of atomic cancellation in channels is removed. All operations in channels 488 and corresponding `Flow` operators are cancellable in non-atomic way (#1813). 489* If `CoroutineDispatcher` throws `RejectedExecutionException`, cancel current `Job` and schedule its execution to `Dispatchers.IO` (#2003). 490* `CancellableContinuation.invokeOnCancellation` is invoked if the continuation was cancelled while its resume has been dispatched (#1915). 491* `Flow.singleOrNull` operator is aligned with standard library and does not longer throw `IllegalStateException` on multiple values (#2289). 492 493### New experimental features 494 495* `SharedFlow` primitive for managing hot sources of events with support of various subscription mechanisms, replay logs and buffering (#2034). 496* `Flow.shareIn` and `Flow.stateIn` operators to transform cold instances of flow to hot `SharedFlow` and `StateFlow` respectively (#2047). 497 498### Other 499 500* Support leak-free closeable resources transfer via `onUndeliveredElement` in channels (#1936). 501* Changed ABI in reactive integrations for Java interoperability (#2182). 502* Fixed ProGuard rules for `kotlinx-coroutines-core` (#2046, #2266). 503* Lint settings were added to `Flow` to avoid accidental capturing of outer `CoroutineScope` for cancellation check (#2038). 504 505### External contributions 506 507* Allow nullable types in `Flow.firstOrNull` and `Flow.singleOrNull` by @ansman (#2229). 508* Add `Publisher.awaitSingleOrDefault|Null|Else` extensions by @sdeleuze (#1993). 509* `awaitCancellation` top-level function by @LouisCAD (#2213). 510* Significant part of our Gradle build scripts were migrated to `.kts` by @turansky. 511 512Thank you for your contributions and participation in the Kotlin community! 513 514## Version 1.3.9 515 516* Support of `CoroutineContext` in `Flow.asPublisher` and similar reactive builders (#2155). 517* Kotlin updated to 1.4.0. 518* Transition to new HMPP publication scheme for multiplatform usages: 519 * Artifacts `kotlinx-coroutines-core-common` and `kotlinx-coroutines-core-native` are removed. 520 * For multiplatform usages, it's enough to [depend directly](README.md#multiplatform) on `kotlinx-coroutines-core` in `commonMain` source-set. 521 * The same artifact coordinates can be used to depend on platform-specific artifact in platform-specific source-set. 522 523## Version 1.3.8 524 525### New experimental features 526 527* Added `Flow.transformWhile operator` (#2065). 528* Replaced `scanReduce` with `runningReduce` to be consistent with the Kotlin standard library (#2139). 529 530### Bug fixes and improvements 531 532* Improve user experience for the upcoming coroutines debugger (#2093, #2118, #2131). 533* Debugger no longer retains strong references to the running coroutines (#2129). 534* Fixed race in `Flow.asPublisher` (#2109). 535* Fixed `ensureActive` to work in the empty context case to fix `IllegalStateException` when using flow from `suspend fun main` (#2044). 536* Fixed a problem with `AbortFlowException` in the `Flow.first` operator to avoid erroneous `NoSuchElementException` (#2051). 537* Fixed JVM dependency on Android annotations (#2075). 538* Removed keep rules mentioning `kotlinx.coroutines.android` from core module (#2061 by @mkj-gram). 539* Corrected some docs and examples (#2062, #2071, #2076, #2107, #2098, #2127, #2078, #2135). 540* Improved the docs and guide on flow cancellation (#2043). 541* Updated Gradle version to `6.3` (it only affects multiplatform artifacts in this release). 542 543## Version 1.3.7 544 545* Fixed problem that triggered Android Lint failure (#2004). 546* New `Flow.cancellable()` operator for cooperative cancellation (#2026). 547* Emissions from `flow` builder now check cancellation status and are properly cancellable (#2026). 548* New `currentCoroutineContext` function to use unambiguously in the contexts with `CoroutineScope` in receiver position (#2026). 549* `EXACTLY_ONCE` contract support in coroutine builders. 550* Various documentation improvements. 551 552## Version 1.3.6 553 554### Flow 555 556* `StateFlow`, new primitive for state handling (#1973, #1816, #395). The `StateFlow` is designed to eventually replace `ConflatedBroadcastChannel` for state publication scenarios. Please, try it and share your feedback. Note, that Flow-based primitives to publish events will be added later. For events you should continue to either use `BroadcastChannel(1)`, if you put events into the `StateFlow`, protect them from double-processing with flags. 557* `Flow.onEmpty` operator is introduced (#1890). 558* Behavioural change in `Flow.onCompletion`, it is aligned with `invokeOnCompletion` now and passes `CancellationException` to its cause parameter (#1693). 559* A lot of Flow operators have left its experimental status and are promoted to stable API. 560 561### Other 562 563* `runInterruptible` primitive to tie cancellation with thread interruption for blocking calls. Contributed by @jxdabc (#1947). 564* Integration module with RxJava3 is introduced. Contributed by @ZacSweers (#1883) 565* Integration with [BlockHound](https://github.com/reactor/BlockHound) in `kotlinx-coroutines-debug` module (#1821, #1060). 566* Memory leak in ArrayBroadcastChannel is fixed (#1885). 567* Behavioural change in `suspendCancellableCoroutine`, cancellation is established before invoking passed block argument (#1671). 568* Debug agent internals are moved into `kotlinx-coroutines-core` for better integration with IDEA. It should not affect library users and all the redundant code should be properly eliminated with R8. 569* ClassCastException with reusable continuations bug is fixed (#1966). 570* More precise scheduler detection for `Executor.asCoroutineDispatcher` (#1992). 571* Kotlin updated to 1.3.71. 572 573## Version 1.3.5 574 575* `firstOrNull` operator. Contributed by @bradynpoulsen. 576* `java.time` adapters for Flow operators. Contributed by @fvasco. 577* `kotlin.time.Duration` support (#1402). Contributed by @fvasco. 578* Memory leak with a mix of reusable and non-reusable continuations is fixed (#1855). 579* `DebugProbes` are ready for production installation: its performance is increased, the flag to disable creation stacktraces to reduce the footprint is introduced (#1379, #1372). 580* Stacktrace recovery workaround for Android 6.0 and earlier bug (#1866). 581* New integration module: `kotlinx-coroutines-jdk9` with adapters for `java.util.concurrent.Flow`. 582* `BroadcastChannel.close` properly starts lazy coroutine (#1713). 583* `kotlinx-coroutines-bom` is published without Gradle metadata. 584* Make calls to service loader in reactor integrations optimizable by R8 (#1817). 585 586## Version 1.3.4 587 588### Flow 589 590* Detect missing `awaitClose` calls in `callbackFlow` to make it less error-prone when used with callbacks (#1762, #1770). This change makes `callbackFlow` **different** from `channelFlow`. 591* `ReceiveChannel.asFlow` extension is introduced (#1490). 592* Enforce exception transparency invariant in `flow` builder (#1657). 593* Proper `Dispatcher` support in `Flow` reactive integrations (#1765). 594* Batch `Subscription.request` calls in `Flow` reactive integration (#766). 595* `ObservableValue.asFlow` added to JavaFx integration module (#1695). 596* `ObservableSource.asFlow` added to RxJava2 integration module (#1768). 597 598### Other changes 599 600* `kotlinx-coroutines-core` is optimized for R8, making it much smaller for Android usages (75 KB for `1.3.4` release). 601* Performance of `Dispatchers.Default` is improved (#1704, #1706). 602* Kotlin is updated to 1.3.70. 603* `CoroutineDispatcher` and `ExecutorCoroutineDispatcher` experimental coroutine context keys are introduced (#1805). 604* Performance of various `Channel` operations is improved (#1565). 605 606## Version 1.3.3 607 608### Flow 609* `Flow.take` performance is significantly improved (#1538). 610* `Flow.merge` operator (#1491). 611* Reactive Flow adapters are promoted to stable API (#1549). 612* Reusable cancellable continuations were introduced that improved the performance of various flow operators and iteration over channels (#1534). 613* Fixed interaction of multiple flows with `take` operator (#1610). 614* Throw `NoSuchElementException` instead of `UnsupportedOperationException` for empty `Flow` in `reduce` operator (#1659). 615* `onCompletion` now rethrows downstream exceptions on emit attempt (#1654). 616* Allow non-emitting `withContext` from `flow` builder (#1616). 617 618### Debugging 619 620* `DebugProbes.dumpCoroutines` is optimized to be able to print the 6-digit number of coroutines (#1535). 621* Properly capture unstarted lazy coroutines in debugger (#1544). 622* Capture coroutines launched from within a test constructor with `CoroutinesTimeout` test rule (#1542). 623* Stacktraces of `Job`-related coroutine machinery are shortened and prettified (#1574). 624* Stacktrace recovery unification that should provide a consistent experience recover of stacktrace (#1597). 625* Stacktrace recovery for `withTimeout` is supported (#1625). 626* Do not recover exception with a single `String` parameter constructor that is not a `message` (#1631). 627 628### Other features 629 630* `Dispatchers.Default` and `Dispatchers.IO` rework: CPU consumption is significantly lower, predictable idle threads termination (#840, #1046, #1286). 631* Avoid `ServiceLoader` for loading `Dispatchers.Main` (#1572, #1557, #878, #1606). 632* Consistently handle undeliverable exceptions in RxJava and Reactor integrations (#252, #1614). 633* `yield` support in immediate dispatchers (#1474). 634* `CompletableDeferred.completeWith(result: Result<T>)` is introduced. 635* Added support for tvOS and watchOS-based Native targets (#1596). 636 637### Bug fixes and improvements 638 639* Kotlin version is updated to 1.3.61. 640* `CoroutineDispatcher.isDispatchNeeded` is promoted to stable API (#1014). 641* Livelock and stackoverflows in mutual `select` expressions are fixed (#1411, #504). 642* Properly handle `null` values in `ListenableFuture` integration (#1510). 643* Making ReceiveChannel.cancel linearizability-friendly. 644* Linearizability of Channel.close in a complex contended cases (#1419). 645* ArrayChannel.isBufferEmpty atomicity is fixed (#1526). 646* Various documentation improvements. 647* Reduced bytecode size of `kotlinx-coroutines-core`, reduced size of minified `dex` when using basic functionality of `kotlinx-coroutines`. 648 649## Version 1.3.2 650 651This is a maintenance release that does not include any new features or bug fixes. 652 653* Reactive integrations for `Flow` are promoted to stable API. 654* Obsolete reactive API is deprecated. 655* Deprecation level for API deprecated in 1.3.0 is increased. 656* Various documentation improvements. 657 658## Version 1.3.1 659 660This is a minor update with various fixes: 661* Flow: Fix recursion in combineTransform<T1, T2, R> (#1466). 662* Fixed race in the Semaphore (#1477). 663* Repaired some of ListenableFuture.kt's cancellation corner cases (#1441). 664* Consistently unwrap exception in slow path of CompletionStage.asDeferred (#1479). 665* Various fixes in documentation (#1496, #1476, #1470, #1468). 666* Various cleanups and additions in tests. 667 668Note: Kotlin/Native artifacts are now published with Gradle metadata format version 1.0, so you will need 669Gradle version 5.3 or later to use this version of kotlinx.coroutines in your Kotlin/Native project. 670 671## Version 1.3.0 672 673### Flow 674 675This version is the first stable release with [`Flow`](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html) API. 676 677All `Flow` API not marked with `@FlowPreview` or `@ExperimentalCoroutinesApi` annotations are stable and here to stay. 678Flow declarations marked with `@ExperimentalCoroutinesApi` have [the same guarantees](/docs/topics/compatibility.md#experimental-api) as regular experimental API. 679Please note that API marked with `@FlowPreview` have [weak guarantees](/docs/topics/compatibility.md#flow-preview-api) on source, binary and semantic compatibility. 680 681### Changelog 682 683* A new [guide section](/docs/topics/flow.md) about Flow. 684* `CoroutineDispatcher.asExecutor` extension (#1450). 685* Fixed bug when `select` statement could report the same exception twice (#1433). 686* Fixed context preservation in `flatMapMerge` in a case when collected values were immediately emitted to another flow (#1440). 687* Reactive Flow integrations enclosing files are renamed for better interoperability with Java. 688* Default buffer size in all Flow operators is increased to 64. 689* Kotlin updated to 1.3.50. 690 691## Version 1.3.0-RC2 692 693### Flow improvements 694* Operators for UI programming are reworked for the sake of consistency, naming scheme for operator overloads is introduced: 695 * `combineLatest` is deprecated in the favor of `combine`. 696 * `combineTransform` operator for non-trivial transformations (#1224). 697 * Top-level `combine` and `combineTransform` overloads for multiple flows (#1262). 698 * `switchMap` is deprecated. `flatMapLatest`, `mapLatest` and `transformLatest` are introduced instead (#1335). 699 * `collectLatest` terminal operator (#1269). 700 701* Improved cancellation support in `flattenMerge` (#1392). 702* `channelFlow` cancellation does not leak to the parent (#1334). 703* Fixed flow invariant enforcement for `suspend fun main` (#1421). 704* `delayEach` and `delayFlow` are deprecated (#1429). 705 706### General changes 707* Integration with Reactor context 708 * Propagation of the coroutine context of `await` calls into Mono/Flux builder. 709 * Publisher.asFlow propagates coroutine context from `collect` call to the Publisher. 710 * New `Flow.asFlux ` builder. 711 712* ServiceLoader-code is adjusted to avoid I/O on the Main thread on newer (3.6.0+) Android toolchain. 713* Stacktrace recovery support for minified builds on Android (#1416). 714* Guava version in `kotlinx-coroutines-guava` updated to `28.0`. 715* `setTimeout`-based JS dispatcher for platforms where `process` is unavailable (#1404). 716* Native, JS and common modules are added to `kotlinx-coroutines-bom`. 717* Fixed bug with ignored `acquiredPermits` in `Semaphore` (#1423). 718 719## Version 1.3.0-RC 720 721### Flow 722 723* Core `Flow` API is promoted to stable 724* New basic `Flow` operators: `withIndex`, `collectIndexed`, `distinctUntilChanged` overload 725* New core `Flow` operators: `onStart` and `onCompletion` 726* `ReceiveChannel.consumeAsFlow` and `emitAll` (#1340) 727 728### General changes 729 730* Kotlin updated to 1.3.41 731* Added `kotlinx-coroutines-bom` with Maven Bill of Materials (#1110) 732* Reactive integrations are seriously improved 733 * All builders now are top-level functions instead of extensions on `CoroutineScope` and prohibit `Job` instance in their context to simplify lifecycle management 734 * Fatal exceptions are handled consistently (#1297) 735 * Integration with Reactor Context added (#284) 736* Stacktrace recovery for `suspend fun main` (#1328) 737* `CoroutineScope.cancel` extension with message (#1338) 738* Protection against non-monotonic clocks in `delay` (#1312) 739* `Duration.ZERO` is handled properly in JDK 8 extensions (#1349) 740* Library code is adjusted to be more minification-friendly 741 742## Version 1.3.0-M2 743 744 * Kotlin updated to 1.3.40. 745 * `Flow` exception transparency concept. 746 * New declarative `Flow` operators: `onCompletion`, `catch`, `retryWhen`, `launchIn`. `onError*` operators are deprecated in favour of `catch`. (#1263) 747 * `Publisher.asFlow` is integrated with `buffer` operator. 748 * `Publisher.openSubscription` default request size is `1` instead of `0` (#1267). 749 750## Version 1.3.0-M1 751 752Flow: 753 * Core `Flow` interfaces and operators are graduated from preview status to experimental. 754 * Context preservation invariant rework (#1210). 755 * `channelFlow` and `callbackFlow` replacements for `flowViaChannel` for concurrent flows or callback-based APIs. 756 * `flow` prohibits emissions from non-scoped coroutines by default and recommends to use `channelFlow` instead to avoid most of the concurrency-related bugs. 757 * Flow cannot be implemented directly 758 * `AbstractFlow` is introduced for extension (e.g. for managing state) and ensures all context preservation invariants. 759 * Buffer size is decoupled from all operators that imply channel usage (#1233) 760 * `buffer` operator can be used to adjust buffer size of any buffer-dependent operator (e.g. `channelFlow`, `flowOn` and `flatMapMerge`). 761 * `conflate` operator is introduced. 762 * Flow performance is significantly improved. 763 * New operators: `scan`, `scanReduce`, `first`, `emitAll`. 764 * `flowWith` and `flowViaChannel` are deprecated. 765 * `retry` ignores cancellation exceptions from upstream when the flow was externally cancelled (#1122). 766 * `combineLatest` overloads for multiple flows (#1193). 767 * Fixed numerical overflow in `drop` operator. 768 769Channels: 770 * `consumeEach` is promoted to experimental API (#1080). 771 * Conflated channels always deliver the latest value after closing (#332, #1235). 772 * Non-suspending `ChannelIterator.next` to improve iteration performance (#1162). 773 * Channel exception types are consistent with `produce` and are no longer swallowed as cancellation exceptions in case of programmatic errors (#957, #1128). 774 * All operators on channels (that were prone to coroutine leaks) are deprecated in the favor of `Flow`. 775 776General changes: 777 * Kotlin updated to 1.3.31 778 * `Semaphore` implementation (#1088) 779 * Loading of `Dispatchers.Main` is tweaked so the latest version of R8 can completely remove I/O when loading it (#1231). 780 * Performace of all JS dispatchers is significantly improved (#820). 781 * `withContext` checks cancellation status on exit to make reasoning about sequential concurrent code easier (#1177). 782 * Consistent exception handling mechanism for complex hierarchies (#689). 783 * Convenient overload for `CoroutinesTimeout.seconds` (#1184). 784 * Fix cancellation bug in onJoin (#1130). 785 * Prevent internal names clash that caused errors for ProGuard (#1159). 786 * POSIX's `nanosleep` as `delay` in `runBlocking ` in K/N (#1225). 787 788## Version 1.2.2 789 790* Kotlin updated to 1.3.40. 791 792## Version 1.2.1 793 794Major: 795 * Infrastructure for testing coroutine-specific code in `kotlinx-coroutines-test`: `runBlockingTest`, `TestCoroutineScope` and `TestCoroutineDispatcher`, contributed by Sean McQuillan (@objcode). Obsolete `TestCoroutineContext` from `kotlinx-coroutines-core` is deprecated. 796 * `Job.asCompletableFuture` extension in jdk8 module (#1113). 797 798Flow improvements: 799 * `flowViaChannel` rework: block parameter is no longer suspending, but provides `CoroutineScope` receiver and allows conflated channel (#1081, #1112). 800 * New operators: `switchMap`, `sample`, `debounce` (#1107). 801 * `consumerEach` is deprecated on `Publisher`, `ObservableSource` and `MaybeSource`, `collect` extension is introduced instead (#1080). 802 803Other: 804 * Race in Job.join and concurrent cancellation is fixed (#1123). 805 * Stacktrace recovery machinery improved: cycle detection works through recovered exceptions, cancellation exceptions are recovered on cancellation fast-path. 806 * Atomicfu-related bug fixes: publish transformed artifacts, do not propagate transitive atomicfu dependency (#1064, #1116). 807 * Publication to NPM fixed (#1118). 808 * Misplaced resources are removed from the final jar (#1131). 809 810## Version 1.2.0 811 812 * Kotlin updated to 1.3.30. 813 * New API: `CancellableContinuation.resume` with `onCancelling` lambda (#1044) to consistently handle closeable resources. 814 * Play services task version updated to 16.0.1. 815 * `ReceiveChannel.isEmpty` is no longer deprecated 816 817A lot of `Flow` improvements: 818 * Purity property is renamed to context preservation and became more restrictive. 819 * `zip` and `combineLatest` operators. 820 * Integration with RxJava2 821 * `flatMap`, `merge` and `concatenate` are replaced with `flattenConcat`, `flattenMerge`, `flatMapConcat` and `flatMapMerge`. 822 * Various documentation improvements and minor bug fixes. 823 824Note that `Flow` **is not** leaving its [preview status](/docs/topics/compatibility.md#flow-preview-api). 825 826## Version 1.2.0-alpha-2 827 828This release contains major [feature preview](/docs/topics/compatibility.md#flow-preview-api): cold streams aka `Flow` (#254). 829 830Performance: 831* Performance of `Dispatcher.Main` initialization is significantly improved (#878). 832 833## Version 1.2.0-alpha 834 835* Major debug agent improvements. Real stacktraces are merged with coroutine stacktraces for running coroutines, merging heuristic is improved, API is cleaned up and is on its road to stabilization (#997). 836* `CoroutineTimeout` rule or JUnit4 is introduced to simplify coroutines debugging (#938). 837* Stacktrace recovery improvements. Exceptions with custom properties are no longer copied, `CopyableThrowable` interface is introduced, machinery is [documented](https://github.com/Kotlin/kotlinx.coroutines/blob/develop/docs/debugging.md) (#921, #950). 838* `Dispatchers.Unconfined`, `MainCoroutineDispatcher.immediate`, `MainScope` and `CoroutineScope.cancel` are promoted to stable API (#972). 839* `CompletableJob` is introduced (#971). 840* Structured concurrency is integrated into futures and listenable futures (#1008). 841* `ensurePresent` and `isPresent` extensions for `ThreadLocal` (#1028). 842* `ensureActive` extensions for `CoroutineContext`, `CoroutineScope` and `Job` (#963). 843* `SendChannel.isFull` and `ReceiveChannel.isEmpty` are deprecated (#1053). 844* `withContext` checks cancellation on entering (#962). 845* Operator `invoke` on `CoroutineDispatcher` (#428). 846* Java 8 extensions for `delay` and `withTimeout` now properly handle too large values (#428). 847* A global exception handler for fatal exceptions in coroutines is introduced (#808, #773). 848* Major improvements in cancellation machinery and exceptions delivery consistency. Cancel with custom exception is completely removed. 849* Kotlin version is updated to 1.3.21. 850* Do not use private API on newer Androids to handle exceptions (#822). 851 852Bug fixes: 853* Proper `select` support in debug agent (#931). 854* Proper `supervisorScope` support in debug agent (#915). 855* Throwing `initCause` does no longer trigger an internal error (#933). 856* Lazy actors are started when calling `close` in order to cleanup their resources (#939). 857* Minor bugs in reactive integrations are fixed (#1008). 858* Experimental scheduler shutdown sequence is fixed (#990). 859 860## Version 1.1.1 861 862* Maintenance release, no changes in the codebase 863* Kotlin is updated to 1.3.20 864* Gradle is updated to 4.10 865* Native module is published with Gradle metadata v0.4 866 867## Version 1.1.0 868 869* Kotlin version updated to 1.3.11. 870* Resumes to `CancellableContinuation` in the final state produce `IllegalStateException` (#901). This change does not affect #830, races between resume and cancellation do not lead to an exceptional situation. 871* `runBlocking` is integrated with `Dispatchers.Unconfined` by sharing an internal event loop. This change does not affect the semantics of the previously correct code but allows to mix multiple `runBlocking` and unconfined tasks (#860). 872 873## Version 1.1.0-alpha 874 875### Major improvements in coroutines testing and debugging 876* New module: [`kotlinx-coroutines-debug`](https://github.com/Kotlin/kotlinx.coroutines/blob/master/core/kotlinx-coroutines-debug/README.md). Debug agent that improves coroutines stacktraces, allows to print all active coroutines and its hierarchies and can be installed as Java agent. 877* New module: [`kotlinx-coroutines-test`](https://github.com/Kotlin/kotlinx.coroutines/blob/master/core/kotlinx-coroutines-test/README.md). Allows setting arbitrary `Dispatchers.Main` implementation for tests (#810). 878* Stacktrace recovery mechanism. Exceptions from coroutines are recovered from current coroutine stacktraces to simplify exception diagnostic. Enabled in debug mode, controlled by `kotlinx.coroutines.debug` system property (#493). 879 880### Other improvements 881* `MainScope` factory and `CoroutineScope.cancel` extension (#829). One line `CoroutineScope` integration! 882* `CancellableContinuation` race between `resumeWithException` and `cancel` is addressed, exceptions during cancellation are no longer reported to exception handler (#830, #892). 883* `Dispatchers.Default` now consumes much less CPU on JVM (#840). 884* Better diagnostic and fast failure if an uninitialized dispatcher is used (#880). 885* Conflated channel becomes linearizable. 886* Fixed inconsistent coroutines state when the result of the coroutine had type `DisposableHandle` (#835). 887* Fixed `JavaFx` initialization bug (#816). 888* `TimeoutCancellationException` is thrown by `withTimeout` instead of `CancellationException` if negative timeout is supplied (#870). 889* Kotlin/Native single-threaded workers support: coroutines can be safely used in multiple independent K/N workers. 890* jsdom support in `Dispatchers.Default` on JS. 891* rxFlowable generic parameter is now restricted with Any. 892* Guava 27 support in `kotlinx-coroutines-guava`. 893* Coroutines are now built with progressive mode. 894* Various fixes in the documentation. 895 896## Version 1.0.1 897 898* Align `publisher` implementation with Reactive TCK. 899* Reimplement `future` coroutine builders on top of `AbstractCoroutine` (#751). 900* Performance optimizations in `Dispatchers.Default` and `Dispatchers.IO`. 901* Use only public API during `JavaFx` instantiation, fixes warnings on Java 9 and build on Java 11 (#463). 902* Updated contract of `CancellableContinuation.resumeWithException` (documentation fix, see #712). 903* Check cancellation on fast-path of all in-place coroutine builders (`withContext`, `coroutineScope`, `supervisorScope`, `withTimeout` and `withTimeoutOrNull`). 904* Add optional prefix to thread names of `ExperimentalCoroutineDispatcher` (#661). 905* Fixed bug when `ExperimentalCoroutineDispatcher` could end up in inconsistent state if `Thread` constructor throws an exception (#748). 906 907## Version 1.0.0 908 909* All Kotlin dependencies updated to 1.3 release version. 910* Fixed potential memory leak in `HandlerDispatcher.scheduleResumeAfterDelay`, thanks @cbeyls. 911* `yield` support for `Unconfined` and immediate dispatchers (#737). 912* Various documentation improvements. 913 914## Version 1.0.0-RC1 915 916* Coroutines API is updated to Kotlin 1.3. 917* Deprecated API is removed or marked as `internal`. 918* Experimental and internal coroutine API is marked with corresponding `kotlin.experimental.Experimental` annotation. If you are using `@ExperimentalCoroutinesApi` or `@InternalCoroutinesApi` you should explicitly opt-in, otherwise compilation warning (or error) will be produced. 919* `Unconfined` dispatcher (and all dispatchers which support immediate invocation) forms event-loop on top of current thread, thus preventing all `StackOverflowError`s. `Unconfined` dispatcher is now much safer for the general use and may leave its experimental status soon (#704). 920* Significantly improved performance of suspending hot loops in `kotlinx.coroutines` (#537). 921* Proguard rules are embedded into coroutines JAR to assist jettifier (#657) 922* Fixed bug in shutdown sequence of `runBlocking` (#692). 923* `ReceiveChannel.receiveOrNull` is marked as obsolete and deprecated. 924* `Job.cancel(cause)` and `ReceiveChannel.cancel(cause)` are deprecated, `cancel()` returns `Unit` (#713). 925 926## Version 0.30.2 927 928* `Dispatchers.Main` is instantiated lazily (see #658 and #665). 929* Blocking coroutine dispatcher views are now shutdown properly (#678). 930* Prevent leaking Kotlin 1.3 from atomicfu dependency (#659). 931* Thread-pool based dispatcher factories are marked as obsolete (#261). 932* Fixed exception loss on `withContext` cancellation (#675). 933 934## Version 0.30.1 935 936Maintenance release: 937* Added `Dispatchers.Main` to common dispatchers, which can be used from Android, Swing and JavaFx projects if a corresponding integration library is added to dependencies. 938* With `Dispatchers.Main` improvement tooling bug in Android Studio #626 is mitigated, so Android users now can safely start the migration to the latest `kotlinx.coroutines` version. 939* Fixed bug with thread unsafety of shutdown sequence in `EventLoop`. 940* Experimental coroutine dispatcher now has `close` contract similar to Java `Executor`, so it can be safely instantiated and closed multiple times (affects only unit tests). 941* Atomicfu version is updated with fixes in JS transformer (see #609) 942 943## Version 0.30.0 944 945* **[Major]** Further improvements in exception handling — no failure exception is lost. 946 * `async` and async-like builders cancel parent on failure (it affects `CompletableDeferred`, and all reactive integration builders). 947 * This makes parallel decomposition exception-safe and reliable without having to rember about `awaitAll` (see #552). 948 * `Job()` wih parent now also cancels parent on failure consistently with other scopes. 949 * All coroutine builders and `Job` implementations propagate failure to the parent unless it is a `CancellationException`. 950 * Note, "scoping" builders don't "cancel the parent" verbatim, but rethrow the corresponding exception to the caller for handling. 951 * `SupervisorJob()` and `supervisorScope { ... }` are introduced, allowing for a flexible implementation of custom exception-handling policies, see a [new section in the guide on supervision](docs/topics/exception-handling.md#supervision). 952 * Got rid of `awaitAll` in documentation and rewrote `currentScope` section (see #624). 953* **[Major]** Coroutine scheduler is used for `Dispatchers.Default` by default instead of deprecated `CommonPool`. 954 * "`DefaultDispatcher`" is used as a public name of the default impl (you'll see it thread names and in the guide). 955 * `-Dkotlinx.coroutines.scheduler=off` can be used to switch back to `CommonPool` for a time being (until deprecated CommonPool is removed). 956* Make `CoroutineStart.ATOMIC` experimental as it covers important use-case with resource cleanup in finally block (see #627). 957* Restored binary compatibility of `Executor.asCoroutineDispatcher` (see #629). 958* Fixed OOM in thread-pool dispatchers (see #571). 959* Check for cancellation when starting coroutine with `Dispatchers.Unconfined` (see #621). 960* A bunch of various performance optimizations and docs fixes, including contributions from @AlexanderPrendota, @PaulWoitaschek. 961 962## Version 0.27.0 963 964* **[Major]** Public API revision. All public API was reviewed and marked as preparation to `1.0` release: 965 1. `@Deprecated` API. All API marked as deprecated will be removed in 1.0 release without replacement. 966 2. `@ExperimentalCoroutinesApi` API. This API is experimental and may change in the future, but migration mechanisms will be provided. Signature, binary compatibility and semantics can be changed. 967 3. `@InternalCoroutinesApi`. This API is intended to be used **only** from within `kotlinx.coroutines`. It can and will be changed, broken 968 and removed in the future releases without any warnings and migration aids. If you find yourself using this API, it is better to report 969 your use-case to Github issues, so decent, stable and well-tested alternative can be provided. 970 4. `@ObsoleteCoroutinesApi`. This API has serious known flaws and will be replaced with a better alternative in the nearest releases. 971 5. Regular public API. This API is proven to be stable and is not going to be changed. If at some point it will be discovered that such API 972 has unfixable design flaws, it will be gradually deprecated with proper replacement and migration aid, but won't be removed for at least a year. 973* **[Major]** Job state machine is reworked. It includes various performance improvements, fixes in 974data-races which could appear in a rare circumstances and consolidation of cancellation and exception handling. 975Visible consequences of include more robust exception handling for large coroutines hierarchies and for different kinds of `CancellationException`, transparent parallel decomposition and consistent view of coroutines hierarchy in terms of its state (see #220 and #585). 976* NIO, Quasar and Rx1 integration modules are removed with no replacement (see #595, #601, #603). 977* `withContext` is now aligned with structured concurrency and awaits for all launched tasks, its performance is significantly improved (see #553 and #617). 978* Added integration module with Play Services Task API. Thanks @SUPERCILEX and @lucasvalenteds for the contribution! 979* Integration with Rx2 now respects nullability in type constraints (see #347). Thanks @Dmitry-Borodin for the contribution! 980* `CompletableFuture.await` and `ListenableFuture.await` now propagate cancellation to the future (see #611). 981* Cancellation of `runBlocking` machinery is improved (see #589). 982* Coroutine guide is restructured and split to multiple files for the sake of simplicity. 983* `CoroutineScope` factory methods add `Job` if it is missing from the context to enforce structured concurrency (see #610). 984* `Handler.asCoroutineDispatcher` has a `name` parameter for better debugging (see #615). 985* Fixed bug when `CoroutineSchedule` was closed from one of its threads (see #612). 986* Exceptions from `CoroutineExceptionHandler` are reported by default exception handler (see #562). 987* `CoroutineName` is now available from common modules (see #570). 988* Update to Kotlin 1.2.70. 989 990## Version 0.26.1 991 992* Android `Main` dispatcher is `async` by default which may significantly improve UI performance. Contributed by @JakeWharton (see #427). 993* Fixed bug when lazily-started coroutine with registered cancellation handler was concurrently started and cancelled. 994* Improved termination sequence in IO dispatcher. 995* Fixed bug with `CoroutineScope.plus` operator (see #559). 996* Various fixes in the documentation. Thanks to @SUPERCILEX, @yorlov, @dualscyther and @soudmaijer! 997 998## Version 0.26.0 999 1000* Major rework of `kotlinx.coroutines` concurrency model (see #410 for a full explanation of the rationale behind this change): 1001 * All coroutine builders are now extensions on `CoroutineScope` and inherit its `coroutineContext`. Standalone builders are deprecated. 1002 * As a consequence, all nested coroutines launched via builders now automatically establish parent-child relationship and inherit `CoroutineDispatcher`. 1003 * All coroutine builders use `Dispatchers.Default` by default if `CoroutineInterceptor` is not present in their context. 1004 * [CoroutineScope](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/index.html) became the first-class citizen in `kolinx.coroutines`. 1005 * `withContext` `block` argument has `CoroutineScope` as a receiver. 1006 * [GlobalScope](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-global-scope/index.html) is introduced to simplify migration to new API and to launch global-level coroutines. 1007 * `currentScope` and `coroutineScope` builders are introduced to extract and provide `CoroutineScope`. 1008 * Factory methods to create `CoroutineScope` from `CoroutineContext` are introduced. 1009 * `CoroutineScope.isActive` became an extension property. 1010 * New sections about structured concurrency in core guide: ["Structured concurrency"](docs/topics/coroutines-guide.md#structured-concurrency), ["Scope builder"](docs/topics/coroutines-guide.md#scope-builder) and ["Structured concurrency with async"](docs/topics/coroutines-guide.md#structured-concurrency-with-async). 1011 * New section in UI guide with Android example: ["Structured concurrency, lifecycle and coroutine parent-child hierarchy"](ui/coroutines-guide-ui.md#structured-concurrency,-lifecycle-and-coroutine-parent-child-hierarchy). 1012 * Deprecated reactive API is removed. 1013* Dispatchers are renamed and grouped in the Dispatchers object (see #41 and #533): 1014 * Dispatcher names are consistent. 1015 * Old dispatchers including `CommonPool` are deprecated. 1016* Fixed bug with JS error in rare cases in `invokeOnCompletion(onCancelling = true)`. 1017* Fixed loading of Android exception handler when `Thread.contextClassLoader` is mocked (see #530). 1018* Fixed bug when `IO` dispatcher silently hung (see #524 and #525) . 1019 1020## Version 0.25.3 1021 1022* Distribution no longer uses multi-version jar which is not supported on Android (see #510). 1023* JS version of the library does not depend on AtomicFu anymore: 1024 All the atomic boxes in JS are fully erased. 1025* Note that versions 0.25.1-2 are skipped for technical reasons (they were not fully released). 1026 1027## Version 0.25.0 1028 1029* Major rework on exception-handling and cancellation in coroutines (see #333, #452 and #451): 1030 * New ["Exception Handling" section in the guide](docs/topics/coroutines-guide.md#exception-handling) explains exceptions in coroutines. 1031 * Semantics of `Job.cancel` resulting `Boolean` value changed — `true` means exception was handled by the job, caller shall handle otherwise. 1032 * Exceptions are properly propagated from children to parents. 1033 * Installed `CoroutineExceptionHandler` for a family of coroutines receives one aggregated exception in case of failure. 1034 * Change `handleCoroutineException` contract, so custom exception handlers can't break coroutines machinery. 1035 * Unwrap `JobCancellationException` properly to provide exception transparency over whole call chain. 1036* Introduced support for thread-local elements in coroutines context (see #119): 1037 * `ThreadContextElement` API for custom thread-context sensitive context elements. 1038 * `ThreadLocal.asContextElement()` extension function to convert an arbitrary thread-local into coroutine context element. 1039 * New ["Thread-local data" subsection in the guide](docs/topics/coroutines-guide.md#thread-local-data) with examples. 1040 * SLF4J Mapped Diagnostic Context (MDC) integration is provided via `MDCContext` element defined in [`kotlinx-coroutines-slf4j`](integration/kotlinx-coroutines-slf4j/README.md) integration module. 1041* Introduced IO dispatcher to offload blocking I/O-intensive tasks (see #79). 1042* Introduced `ExecutorCoroutineDispatcher` instead of `CloseableCoroutineDispatcher` (see #385). 1043* Built with Kotlin 1.2.61 and Kotlin/Native 0.8.2. 1044* JAR files for `kotlinx-coroutines` are now [JEP 238](https://openjdk.java.net/jeps/238) multi-release JAR files. 1045 * On JDK9+ `VarHandle` is used for atomic operations instead of `Atomic*FieldUpdater` for better performance. 1046 * See [AtomicFu](https://github.com/Kotlin/kotlinx.atomicfu/blob/master/README.md) project for details. 1047* Reversed addition of `BlockingChecker` extension point to control where `runBlocking` can be used (see #227). 1048 * `runBlocking` can be used anywhere without limitations (again), but it would still cause problems if improperly used on UI thread. 1049* Corrected return-type of `EventLoop` pseudo-constructor (see #477, PR by @Groostav). 1050* Fixed `as*Future()` integration functions to catch all `Throwable` exceptions (see #469). 1051* Fixed `runBlocking` cancellation (see #501). 1052* Fixed races and timing bugs in `withTimeoutOrNull` (see #498). 1053* Execute `EventLoop.invokeOnTimeout` in `DefaultDispatcher` to allow busy-wait loops inside `runBlocking` (see #479). 1054* Removed `kotlinx-coroutines-io` module from the project, it has moved to [kotlinx-io](https://github.com/kotlin/kotlinx-io/). 1055* Provide experimental API to create limited view of experimental dispatcher (see #475). 1056* Various minor fixes by @LouisCAD, @Dmitry-Borodin. 1057 1058## Version 0.24.0 1059 1060* Fully multiplatform release with Kotlin/Native support (see #246): 1061 * Only single-threaded operation inside `runBlocking` event loop is supported at this moment. 1062 * See details on setting up build environment [here](native/README.md). 1063* Improved channels: 1064 * Introduced `SendChannel.invokeOnClose` (see #341). 1065 * Make `close`, `cancel`, `isClosedForSend`, `isClosedForReceive` and `offer` linearizable with other operations (see #359). 1066 * Fixed bug when send operation can be stuck in channel forever. 1067 * Fixed broadcast channels on JS (see #412). 1068* Provides `BlockingChecker` mechanism which checks current context (see #227). 1069 * Attempts to use `runBlocking` from any supported UI thread (Android, JavaFx, Swing) will result in exception. 1070* Android: 1071 * Worked around Android bugs with zero-size ForkJoinPool initialization (see #432, #288). 1072 * Introduced `UI.immediate` extension as performance-optimization to immediately execute tasks which are invoked from the UI thread (see #381). 1073 * Use it only when absolutely needed. It breaks asynchrony of coroutines and may lead to surprising and unexpected results. 1074* Fixed materialization of a `cause` exception for `Job` onCancelling handlers (see #436). 1075* Fixed JavaFx `UI` on Java 9 (see #443). 1076* Fixed and documented the order between cancellation handlers and continuation resume (see #415). 1077* Fixed resumption of cancelled continuation (see #450). 1078* Includes multiple fixes to documentation contributed by @paolop, @SahilLone, @rocketraman, @bdavisx, @mtopolnik, @Groostav. 1079* Experimental coroutines scheduler preview (JVM only): 1080 * Written from scratch and optimized for communicating coroutines. 1081 * Performs significantly better than ForkJoinPool on coroutine benchmarks and for connected applications with [ktor](https://ktor.io). 1082 * Supports automatic creating of new threads for blocking operations running on the same thread pool (with an eye on solving #79), but there is no stable public API for it just yet. 1083 * For preview, run JVM with `-Dkotlinx.coroutines.scheduler` option. In this case `DefaultDispatcher` is set to new experimental scheduler instead of FJP-based `CommonPool`. 1084 * Submit your feedback to issue #261. 1085 1086## Version 0.23.4 1087 1088* Recompiled with Kotlin 1.2.51 to solve broken metadata problem (see [KT-24944](https://youtrack.jetbrains.com/issue/KT-24944)). 1089 1090## Version 0.23.3 1091 1092* Kotlin 1.2.50. 1093* JS: Moved to atomicfu version 0.10.3 that properly matches NPM & Kotlin/JS module names (see #396). 1094* Improve source-code compatibility with previous (0.22.x) version of `openChannel().use { ... }` pattern by providing deprecated extension function `use` on `ReceiveChannel`. 1095 1096## Version 0.23.2 1097 1098* IO: fix joining and continuous writing byte array interference. 1099 1100## Version 0.23.1 1101 1102* JS: Fix dependencies in NPM: add "kotlinx-atomicfu" dependency (see #370). 1103* Introduce `broadcast` coroutine builder (see #280): 1104 * Support `BroadcastChannel.cancel` method to drop the buffer. 1105 * Introduce `ReceiveChannel.broadcast()` extension. 1106* Fixed a bunch of doc typos (PRs by @paolop). 1107* Corrected previous version's release notes (PR by @ansman). 1108 1109## Version 0.23.0 1110 1111* Kotlin 1.2.41 1112* **Coroutines core module is made mostly cross-platform for JVM and JS**: 1113 * Migrate channels and related operators to common, so channels can be used from JS (see #201). 1114 * Most of the code is shared between JVM and JS versions using cross-platform version of [AtomicFU](https://github.com/Kotlin/kotlinx.atomicfu) library. 1115 * The recent version of Kotlin allows default parameters in common code (see #348). 1116 * The project is built using Gradle 4.6. 1117* **Breaking change**: `CancellableContinuation` is not a `Job` anymore (see #219): 1118 * It does not affect casual users of `suspendCancellableCoroutine`, since all the typically used functions are still there. 1119 * `CancellableContinuation.invokeOnCompletion` is deprecated now and its semantics had subtly changed: 1120 * `invokeOnCancellation` is a replacement for `invokeOnCompletion` to install a handler. 1121 * The handler is **not** invoked on `resume` which corresponds to the typical usage pattern. 1122 * There is no need to check for `cont.isCancelled` in a typical handler code anymore (since handler is invoked only when continuation is cancelled). 1123 * Multiple cancellation handlers cannot be installed. 1124 * Cancellation handlers cannot be removed (disposed of) anymore. 1125 * This change is designed to allow better performance of suspending cancellable functions: 1126 * Now `CancellableContinuation` implementation has simpler state machine and is implemented more efficiently. 1127 * Exception handling in `AbstractContinuation` (that implements `CancellableContinuation`) is now consistent: 1128 * Always prefer exception thrown from coroutine as exceptional reason, add cancellation cause as suppressed exception. 1129* **Big change**: Deprecate `CoroutineScope.coroutineContext`: 1130 * It is replaced with top-level `coroutineContext` function from Kotlin standard library. 1131* Improve `ReceiveChannel` operators implementations to guarantee closing of the source channels under all circumstances (see #279): 1132 * `onCompletion` parameter added to `produce` and all other coroutine builders. 1133 * Introduce `ReceiveChannel.consumes(): CompletionHandler` extension function. 1134* Replace `SubscriptionReceiveChannel` with `ReceiveChannel` (see #283, PR by @deva666). 1135 * `ReceiveChannel.use` extension is introduced to preserve source compatibility, but is deprecated. 1136 * `consume` or `consumeEach` extensions should be used for channels. 1137 * When writing operators, `produce(onCompletion=consumes()) { ... }` pattern shall be used (see #279 above). 1138* JS: Kotlin is declared as peer dependency (see #339, #340, PR by @ansman). 1139* Invoke exception handler for actor on cancellation even when channel was successfully closed, so exceptions thrown by actor are always reported (see #368). 1140* Introduce `awaitAll` and `joinAll` for `Deferred` and `Job` lists correspondingly (see #171). 1141* Unwrap `CompletionException` exception in `CompletionStage.await` slow-path to provide consistent results (see #375). 1142* Add extension to `ExecutorService` to return `CloseableCoroutineDispatcher` (see #278, PR by @deva666). 1143* Fail with proper message during build if JDK_16 is not set (see #291, PR by @venkatperi). 1144* Allow negative timeouts in `delay`, `withTimeout` and `onTimeout` (see #310). 1145* Fix a few bugs (leaks on cancellation) in `delay`: 1146 * Invoke `clearTimeout` on cancellation in JSDispatcher. 1147 * Remove delayed task on cancellation from internal data structure on JVM. 1148* Introduce `ticker` function to create "ticker channels" (see #327): 1149 * It provides analogue of RX `Observable.timer` for coroutine channels. 1150 * It is currently supported on JVM only. 1151* Add a test-helper class `TestCoroutineContext` (see #297, PR by @streetsofboston). 1152 * It is currently supported on JVM only. 1153 * Ticker channels (#327) are not yet compatible with it. 1154* Implement a better way to set `CoroutineContext.DEBUG` value (see #316, PR by @dmytrodanylyk): 1155 * Made `CoroutineContext.DEBUG_PROPERTY_NAME` constant public. 1156 * Introduce public constants with `"on"`, `"off"`, `"auto"` values. 1157* Introduce system property to control `CommonPool` parallelism (see #343): 1158 * `CommonPool.DEFAULT_PARALLELISM_PROPERTY_NAME` constant is introduced with a value of "kotlinx.coroutines.default.parallelism". 1159* Include package-list files into documentation site (see #290). 1160* Fix various typos in docs (PRs by @paolop and @ArtsiomCh). 1161 1162## Version 0.22.5 1163 1164* JS: Fixed main file reference in [NPM package](https://www.npmjs.com/package/kotlinx-coroutines-core) 1165* Added context argument to `Channel.filterNot` (PR by @jcornaz). 1166* Implemented debug `toString` for channels (see #185). 1167 1168## Version 0.22.4 1169 1170* JS: Publish to NPM (see #229). 1171* JS: Use node-style dispatcher on ReactNative (see #236). 1172* [jdk8 integration](integration/kotlinx-coroutines-jdk8/README.md) improvements: 1173 * Added conversion from `CompletionStage` to `Deferred` (see #262, PR by @jcornaz). 1174 * Use fast path in `CompletionStage.await` and make it cancellable. 1175 1176## Version 0.22.3 1177 1178* Fixed `produce` builder to close the channel on completion instead of cancelling it, which lead to lost elements with buffered channels (see #256). 1179* Don't use `ForkJoinPool` if there is a `SecurityManager` present to work around JNLP problems (see #216, PR by @NikolayMetchev). 1180* JS: Check for undefined `window.addEventListener` when choosing default coroutine dispatcher (see #230, PR by @ScottPierce). 1181* Update 3rd party dependencies: 1182 * [kotlinx-coroutines-rx1](reactive/kotlinx-coroutines-rx1) to RxJava version `1.3.6`. 1183 * [kotlinx-coroutines-rx2](reactive/kotlinx-coroutines-rx2) to RxJava version `2.1.9`. 1184 * [kotlinx-coroutines-guava](integration/kotlinx-coroutines-guava) to Guava version `24.0-jre`. 1185 1186## Version 0.22.2 1187 1188* Android: Use @Keep annotation on AndroidExceptionPreHandler to fix the problem on Android with minification enabled (see #214). 1189* Reactive: Added `awaitFirstOrDefault` and `awaitFirstOrNull` extensions (see #224, PR by @konrad-kaminski). 1190* Core: Fixed `withTimeout` and `withTimeoutOrNull` that should not use equals on result (see #212, PR by @konrad-kaminski). 1191* Core: Fixed hanged receive from a closed subscription of BroadcastChannel (see #226). 1192* IO: fixed error propagation (see https://github.com/ktorio/ktor/issues/301). 1193* Include common sources into sources jar file to work around KT-20971. 1194* Fixed bugs in documentation due to MPP. 1195 1196## Version 0.22.1 1197 1198* Migrated to Kotlin 1.2.21. 1199* Improved `actor` builder documentation (see #210) and fixed bugs in rendered documentation due to multiplatform. 1200* Fixed `runBlocking` to properly support specified dispatchers (see #209). 1201* Fixed data race in `Job` implementation (it was hanging at `LockFreeLinkedList.helpDelete` on certain stress tests). 1202* `AbstractCoroutine.onCancellation` is invoked before cancellation handler that is set via `invokeOnCompletion`. 1203* Ensure that `launch` handles uncaught exception before another coroutine that uses `join` on it resumes (see #208). 1204 1205## Version 0.22 1206 1207* Migrated to Kotlin 1.2.20. 1208* Introduced stable public API for `AbstractCoroutine`: 1209 * Implements `Job`, `Continuation`, and `CoroutineScope`. 1210 * Has overridable `onStart`, `onCancellation`, `onCompleted` and `onCompletedExceptionally` functions. 1211 * Reactive integration modules are now implemented using public API only. 1212 * Notifies onXXX before all the installed handlers, so `launch` handles uncaught exceptions before "joining" coroutines wakeup (see #208). 1213 1214## Version 0.21.2 1215 1216* Fixed `openSubscription` extension for reactive `Publisher`/`Observable`/`Flowable` when used with `select { ... }` and added an optional `request` parameter to specify how many elements are requested from publisher in advance on subscription (see #197). 1217* Simplified implementation of `Channel.flatMap` using `toChannel` function to work around Android 5.0 APK install SIGSEGV (see #205). 1218 1219## Version 0.21.1 1220 1221* Improved performance of coroutine dispatching (`DispatchTask` instance is no longer allocated). 1222* Fixed `Job.cancel` and `CompletableDeferred.complete` to support cancelling/completing states and properly wait for their children to complete on join/await (see #199). 1223* Fixed a bug in binary heap implementation (used internally by `delay`) which could have resulted in wrong delay time in rare circumstances. 1224* Coroutines library for [Kotlin/JS](js/README.md): 1225 * `Promise.asDeferred` immediately installs handlers to avoid "Unhandled promise rejection" warning. 1226 * Use `window.postMessage` instead of `setTimeout` for coroutines inside the browser to avoid timeout throttling (see #194). 1227 * Use custom queue in `Window.awaitAnimationFrame` to align all animations and reduce overhead. 1228 * Introduced `Window.asCoroutineDispatcher()` extension function. 1229 1230## Version 0.21 1231 1232* Migrated to Kotlin 1.2.10. 1233* Coroutines library for [Kotlin/JS](js/README.md) and [multiplatform projects](https://kotlinlang.org/docs/reference/multiplatform.html) (see #33): 1234 * `launch` and `async` coroutine builders. 1235 * `Job` and `Deferred` light-weight future with cancellation support. 1236 * `delay` and `yield` top-level suspending functions. 1237 * `await` extension for JS `Promise` and `asPromise`/`asDeferred` conversions. 1238 * `promise` coroutine builder. 1239 * `Job()` and `CompletableDeferred()` factories. 1240 * Full support for parent-child coroutine hierarchies. 1241 * `Window.awaitAnimationFrame` extension function. 1242 * [Sample frontend Kotlin/JS application](js/example-frontend-js/README.md) with coroutine-driven animations. 1243* `run` is deprecated and renamed to `withContext` (see #134). 1244* `runBlocking` and `EventLoop` implementations optimized (see #190). 1245 1246## Version 0.20 1247 1248* Migrated to Kotlin 1.2.0. 1249* Channels: 1250 * Sequence-like `filter`, `map`, etc extensions on `ReceiveChannel` are introduced (see #88 by @fvasco and #69 by @konrad-kaminski). 1251 * Introduced `ReceiveChannel.cancel` method. 1252 * All operators on `ReceiveChannel` fully consume the original channel (`cancel` it when they are done) using a helper `consume` extension. 1253 * Deprecated `ActorJob` and `ProducerJob`; `actor` now returns `SendChannel` and `produce` returns `ReceiveChannel` (see #127). 1254 * `SendChannel.sendBlocking` extension method (see #157 by @@fvasco). 1255* Parent-child relations between coroutines: 1256 * Introduced an optional `parent` job parameter for all coroutine builders so that code with an explict parent `Job` is more natural. 1257 * Added `parent` parameter to `CompletableDeferred` constructor. 1258 * Introduced `Job.children` property. 1259 * `Job.cancelChildren` is now an extension (member is deprecated and hidden). 1260 * `Job.joinChildren` extension is introduced. 1261 * Deprecated `Job.attachChild` as a error-prone API. 1262 * Fixed StackOverflow when waiting for a lot of completed children that did not remove their handlers from the parent. 1263* Use `java.util.ServiceLoader` to find default instances of `CoroutineExceptionHandler`. 1264* Android UI integration: 1265 * Use `Thread.getUncaughtExceptionPreHandler` to make sure that exceptions are logged before crash (see #148). 1266 * Introduce `UI.awaitFrame` for animation; added sample coroutine-based animation application for Android [here](ui/kotlinx-coroutines-android/animation-app). 1267 * Fixed `delay(Long.MAX_VALUE)` (see #161) 1268* Added missing `DefaultDispatcher` on some reactive operators (see #174 by @fvasco) 1269* Fixed `actor` and `produce` so that a cancellation of a Job cancels the underlying channel (closes and removes all the pending messages). 1270* Fixed sporadic failure of `example-context-06` (see #160) 1271* Fixed hang of `Job.start` on lazy coroutine with attached `invokeOnCompletion` handler. 1272* A more gradual introduction to `runBlocking` and coroutines in the [guide](docs/topics/coroutines-guide.md) (see #166). 1273 1274## Version 0.19.3 1275 1276* Fixed `send`/`openSubscription` race in `ArrayBroadcastChannel`. 1277 This race lead to stalled (hanged) `send`/`receive` invocations. 1278* Project build has been migrated to Gradle. 1279 1280## Version 0.19.2 1281 1282* Fixed `ArrayBroadcastChannel` receive of stale elements on `openSubscription`. 1283 Only elements that are sent after invocation of `openSubscription` are received now. 1284* Added a default value for `context` parameter to `rxFlowable` (see #146 by @PhilGlass). 1285* Exception propagation logic from cancelled coroutines is adjusted (see #152): 1286 * When cancelled coroutine crashes due to some other exception, this other exception becomes the cancellation reason 1287 of the coroutine, while the original cancellation reason is suppressed. 1288 * `UnexpectedCoroutineException` is no longer used to report those cases as is removed. 1289 * This fixes a race between crash of CPU-consuming coroutine and cancellation which resulted in an unhandled exception 1290 and lead to crashes on Android. 1291* `run` uses cancelling state & propagates exceptions when cancelled (see #147): 1292 * When coroutine that was switched into a different dispatcher using `run` is cancelled, the run invocation does not 1293 complete immediately, but waits until the body completes. 1294 * If the body completes with exception, then this exception is propagated. 1295* No `Job` in `newSingleThreadContext` and `newFixedThreadPoolContext` anymore (see #149, #151): 1296 * This resolves the common issue of using `run(ctx)` where ctx comes from either `newSingleThreadContext` or 1297 `newFixedThreadPoolContext` invocation. They both used to return a combination of dispatcher + job, 1298 and this job was overriding the parent job, thus preventing propagation of cancellation. Not anymore. 1299 * `ThreadPoolDispatcher` class is now public and is the result type for both functions. 1300 It has the `close` method to release the thread pool. 1301 1302## Version 0.19.1 1303 1304* Failed parent Job cancels all children jobs, then waits for them them. 1305 This makes parent-child hierarchies easier to get working right without 1306 having to use `try/catch` or other exception handlers. 1307* Fixed a race in `ArrayBroadcastChannel` between `send` and `openChannel` invocations 1308 (see #138). 1309* Fixed quite a rare race in `runBlocking` that resulted in `AssertionError`. 1310 Unfortunately, cannot write a reliable stress-test to reproduce it. 1311* Updated Reactor support to leverage Bismuth release train 1312 (contributed by @sdeleuze, see PR #141) 1313 1314## Version 0.19 1315 1316* This release is published to Maven Central. 1317* `DefaultDispatcher` is introduced (see #136): 1318 * `launch`, `async`, `produce`, `actor` and other integration-specific coroutine builders now use 1319 `DefaultDispatcher` as the default value for their `context` parameter. 1320 * When a context is explicitly specified, `newCoroutineContext` function checks if there is any 1321 interceptor/dispatcher defined in the context and uses `DefaultDispatcher` if there is none. 1322 * `DefaultDispatcher` is currently defined to be equal to `CommonPool`. 1323 * Examples in the [guide](docs/topics/coroutines-guide.md) now start with `launch { ... }` code and explanation on the nature 1324 and the need for coroutine context starts in "Coroutine context and dispatchers" section. 1325* Parent coroutines now wait for their children (see #125): 1326 * Job _completing_ state is introduced in documentation as a state in which parent coroutine waits for its children. 1327 * `Job.attachChild` and `Job.cancelChildren` are introduced. 1328 * `Job.join` now always checks cancellation status of invoker coroutine for predictable behavior when joining 1329 failed child coroutine. 1330 * `Job.cancelAndJoin` extension is introduced. 1331 * `CoroutineContext.cancel` and `CoroutineContext.cancelChildren` extensions are introduced for convenience. 1332 * `withTimeout`/`withTimeoutOrNull` blocks become proper coroutines that have `CoroutineScope` and wait for children, too. 1333 * Diagnostics in cancellation and unexpected exception messages are improved, 1334 coroutine name is included in debug mode. 1335 * Fixed cancellable suspending functions to throw `CancellationException` (as was documented before) even when 1336 the coroutine is cancelled with another application-specific exception. 1337 * `JobCancellationException` is introduced as a specific subclass of `CancellationException` which is 1338 used for coroutines that are cancelled without cause and to wrap application-specific exceptions. 1339 * `Job.getCompletionException` is renamed to `Job.getCancellationException` and return a wrapper exception if needed. 1340 * Introduced `Deferred.getCompletionExceptionOrNull` to get not-wrapped exception result of `async` task. 1341 * Updated docs for `Job` & `Deferred` to explain parent/child relations. 1342* `select` expression is modularized: 1343 * `SelectClause(0,1,2)` interfaces are introduced, so that synchronization 1344 constructs can define their select clauses without having to modify 1345 the source of the `SelectBuilder` in `kotlinx-corounes-core` module. 1346 * `Job.onJoin`, `Deferred.onAwait`, `Mutex.onLock`, `SendChannel.onSend`, `ReceiveChannel.onReceive`, etc 1347 that were functions before are now properties returning the corresponding select clauses. Old functions 1348 are left in bytecode for backwards compatibility on use-site, but any outside code that was implementing those 1349 interfaces by itself must be updated. 1350 * This opens road to moving channels into a separate module in future updates. 1351* Renamed `TimeoutException` to `TimeoutCancellationException` (old name is deprecated). 1352* Fixed various minor problems: 1353 * JavaFx toolkit is now initialized by `JavaFx` context (see #108). 1354 * Fixed lost ACC_STATIC on <clinit> methods (see #116). 1355 * Fixed link to source code from documentation (see #129). 1356 * Fixed `delay` in arbitrary contexts (see #133). 1357* `kotlinx-coroutines-io` module is introduced. It is a work-in-progress on `ByteReadChannel` and `ByteWriteChannel` 1358 interfaces, their implementations, and related classes to enable convenient coroutine integration with various 1359 asynchronous I/O libraries and sockets. It is currently _unstable_ and **will change** in the next release. 1360 1361## Version 0.18 1362 1363* Kotlin 1.1.4 is required to use this version, which enables: 1364 * `withLock` and `consumeEach` functions are now inline suspend functions. 1365 * `JobSupport` class implementation is optimized (one fewer field). 1366* `TimeoutException` is public (see #89). 1367* Improvements to `Mutex` (courtesy of @fvasco): 1368 * Introduced `holdsLock` (see #92). 1369 * Improved documentation on `Mutex` fairness (see #90). 1370* Fixed NPE when `ArrayBroadcastChannel` is closed concurrently with receive (see #97). 1371* Fixed bug in internal class LockFreeLinkedList that resulted in ISE under stress in extremely rare circumstances. 1372* Integrations: 1373 * [quasar](integration/kotlinx-coroutines-quasar): Introduced integration with suspendable JVM functions 1374 that are instrumented with [Parallel Universe Quasar](https://docs.paralleluniverse.co/quasar/) 1375 (thanks to the help of @pron). 1376 * [reactor](reactive/kotlinx-coroutines-reactor): Replaced deprecated `setCancellation` with `onDipose` and 1377 updated to Aluminium-SR3 release (courtesy of @yxf07, see #96) 1378 * [jdk8](integration/kotlinx-coroutines-jdk8): Added adapters for `java.time` classes (courtesy of @fvasco, see #93) 1379 1380## Version 0.17 1381 1382* `CompletableDeferred` is introduced as a set-once event-like communication primitive (see #70). 1383 * [Coroutines guide](docs/topics/coroutines-guide.md) uses it in a section on actors. 1384 * `CompletableDeferred` is an interface with private impl (courtesy of @fvasco, see #86). 1385 * It extends `Deferred` interface with `complete` and `completeExceptionally` functions. 1386* `Job.join` and `Deferred.await` wait until a cancelled coroutine stops execution (see #64). 1387 * `Job` and `Deferred` have a new _cancelling_ state which they enter on invocation of `cancel`. 1388 * `Job.invokeOnCompletion` has an additional overload with `onCancelling: Boolean` parameter to 1389 install handlers that are fired as soon as coroutine enters _cancelling_ state as opposed 1390 to waiting until it _completes_. 1391 * Internal `select` implementation is refactored to decouple it from `JobSupport` internal class 1392 and to optimize its state-machine. 1393 * Internal `AbstractCoroutine` class is refactored so that it is extended only by true coroutines, 1394 all of which support the new _cancelling_ state. 1395* `CoroutineScope.context` is renamed to `coroutineContext` to avoid conflicts with other usages of `context` 1396 in applications (like Android context, see #75). 1397* `BroadcastChannel.open` is renamed to `openSubscription` (see #54). 1398* Fixed `StackOverflowError` in a convoy of `Mutex.unlock` invokers with `Unconfined` dispatcher (see #80). 1399* Fixed `SecurityException` when trying to use coroutines library with installed `SecurityManager`. 1400* Fixed a bug in `withTimeoutOrNull` in case with nested timeouts when coroutine was cancelled before it was 1401 ever suspended. 1402* Fixed a minor problem with `awaitFirst` on reactive streams that would have resulted in spurious stack-traces printed 1403 on the console when used with publishers/observables that continue to invoke `onNext` despite being cancelled/disposed 1404 (which they are technically allowed to do by specification). 1405* All factory functions for various interfaces are implemented as top-level functions 1406 (affects `Job`, `Channel`, `BroadcastChannel`, `Mutex`, `EventLoop`, and `CoroutineExceptionHandler`). 1407 Previous approach of using `operator invoke` on their companion objects is deprecated. 1408* Nicer-to-use debug `toString` implementations for coroutine dispatcher tasks and continuations. 1409* A default dispatcher for `delay` is rewritten and now shares code with `EventLoopImpl` that is used by 1410 `runBlocking`. It internally supports non-default `TimeSource` so that delay-using tests can be written 1411 with "virtual time" by replacing their time source for the duration of tests (this feature is not available 1412 outside of the library). 1413 1414## Version 0.16 1415 1416* Coroutines that are scheduled for execution are cancellable by default now 1417 * `suspendAtomicCancellableCoroutine` function is introduced for funs like 1418 `send`/`receive`/`receiveOrNull` that require atomic cancellation 1419 (they cannot be cancelled after decision was made) 1420 * Coroutines started with default mode using 1421 `async`/`launch`/`actor` builders can be cancelled before their execution starts 1422 * `CoroutineStart.ATOMIC` is introduced as a start mode to specify that 1423 coroutine cannot be cancelled before its execution starts 1424 * `run` function is also cancellable in the same way and accepts an optional 1425 `CoroutineStart` parameter to change this default. 1426* `BroadcastChannel` factory function is introduced 1427* `CoroutineExceptionHandler` factory function is introduced by @konrad-kaminski 1428* [`integration`](integration) directory is introduced for all 3rd party integration projects 1429 * It has [contribution guidelines](integration/README.md#contributing) and contributions from community are welcome 1430 * Support for Guava `ListenableFuture` in the new [`kotlinx-coroutines-guava`](integration/kotlinx-coroutines-guava) module 1431 * Rx1 Scheduler support by @konrad-kaminski 1432* Fixed a number of `Channel` and `BroadcastChannel` implementation bugs related to concurrent 1433 send/close/close of channels that lead to hanging send, offer or close operations (see #66). 1434 Thanks to @chrisly42 and @cy6erGn0m for finding them. 1435* Fixed `withTimeoutOrNull` which was returning `null` on timeout of inner or outer `withTimeout` blocks (see #67). 1436 Thanks to @gregschlom for finding the problem. 1437* Fixed a bug where `Job` fails to dispose a handler when it is the only handler by @uchuhimo 1438 1439## Version 0.15 1440 1441* Switched to Kotlin version 1.1.2 (can still be used with 1.1.0). 1442* `CoroutineStart` enum is introduced for `launch`/`async`/`actor` builders: 1443 * The usage of `luanch(context, start = false)` is deprecated and is replaced with 1444 `launch(context, CoroutineStart.LAZY)` 1445 * `CoroutineStart.UNDISPATCHED` is introduced to start coroutine execution immediately in the invoker thread, 1446 so that `async(context, CoroutineStart.UNDISPATCHED)` is similar to the behavior of C# `async`. 1447 * [Guide to UI programming with coroutines](ui/coroutines-guide-ui.md) mentions the use of it to optimize 1448 the start of coroutines from UI threads. 1449* Introduced `BroadcastChannel` interface in `kotlinx-coroutines-core` module: 1450 * It extends `SendChannel` interface and provides `open` function to create subscriptions. 1451 * Subscriptions are represented with `SubscriptionReceiveChannel` interface. 1452 * The corresponding `SubscriptionReceiveChannel` interfaces are removed from [reactive](reactive) implementation 1453 modules. They use an interface defined in `kotlinx-coroutines-core` module. 1454 * `ConflatedBroadcastChannel` implementation is provided for state-observation-like use-cases, where a coroutine or a 1455 regular code (in UI, for example) updates the state that subscriber coroutines shall react to. 1456 * `ArrayBroadcastChannel` implementation is provided for event-bus-like use-cases, where a sequence of events shall 1457 be received by multiple subscribers without any omissions. 1458 * [Guide to reactive streams with coroutines](reactive/coroutines-guide-reactive.md) includes 1459 "Rx Subject vs BroadcastChannel" section. 1460* Pull requests from Konrad Kamiński are merged into reactive stream implementations: 1461 * Support for Project Reactor `Mono` and `Flux`. 1462 See [`kotlinx-coroutines-reactor`](reactive/kotlinx-coroutines-reactor) module. 1463 * Implemented Rx1 `Completable.awaitCompleted`. 1464 * Added support for Rx2 `Maybe`. 1465* Better timeout support: 1466 * Introduced `withTimeoutOrNull` function. 1467 * Implemented `onTimeout` clause for `select` expressions. 1468 * Fixed spurious concurrency inside `withTimeout` blocks on their cancellation. 1469 * Changed behavior of `withTimeout` when `CancellationException` is suppressed inside the block. 1470 Invocation of `withTimeout` now always returns the result of execution of its inner block. 1471* The `channel` property in `ActorScope` is promoted to a wider `Channel` type, so that an actor 1472 can have an easy access to its own inbox send channel. 1473* Renamed `Mutex.withMutex` to `Mutex.withLock`, old name is deprecated. 1474 1475## Version 0.14 1476 1477* Switched to Kotlin version 1.1.1 (can still be used with 1.1.0). 1478* Introduced `consumeEach` helper function for channels and reactive streams, Rx 1.x, and Rx 2.x. 1479 * It ensures that streams are unsubscribed from on any exception. 1480 * Iteration with `for` loop on reactive streams is **deprecated**. 1481 * [Guide to reactive streams with coroutines](reactive/coroutines-guide-reactive.md) is updated virtually 1482 all over the place to reflect these important changes. 1483* Implemented `awaitFirstOrDefault` extension for reactive streams, Rx 1.x, and Rx 2.x. 1484* Added `Mutex.withMutex` helper function. 1485* `kotlinx-coroutines-android` module has `provided` dependency on of Android APIs to 1486 eliminate warnings when using it in android project. 1487 1488## Version 0.13 1489 1490* New `kotlinx-coroutinex-android` module with Android `UI` context implementation. 1491* Introduced `whileSelect` convenience function. 1492* Implemented `ConflatedChannel`. 1493* Renamed various `toXXX` conversion functions to `asXXX` (old names are deprecated). 1494* `run` is optimized with fast-path case and no longer has `CoroutineScope` in its block. 1495* Fixed dispatching logic of `withTimeout` (removed extra dispatch). 1496* `EventLoop` that is used by `runBlocking` now implements Delay, giving more predictable test behavior. 1497* Various refactorings related to resource management and timeouts: 1498 * `Job.Registration` is renamed to `DisposableHandle`. 1499 * `EmptyRegistration` is renamed to `NonDisposableHandle`. 1500 * `Job.unregisterOnCompletion` is renamed to `Job.disposeOnCompletion`. 1501 * `Delay.invokeOnTimeout` is introduced. 1502 * `withTimeout` now uses `Delay.invokeOnTimeout` when available. 1503* A number of improvement for reactive streams and Rx: 1504 * Introduced `rxFlowable` builder for Rx 2.x. 1505 * `Scheduler.asCoroutineDispatcher` extension for Rx 2.x. 1506 * Fixed bug with sometimes missing `onComplete` in `publish`, `rxObservable`, and `rxFlowable` builders. 1507 * Channels that are open for reactive streams are now `Closeable`. 1508 * Fixed `CompletableSource.await` and added test for it. 1509 * Removed `rx.Completable.await` due to name conflict. 1510* New documentation: 1511 * [Guide to UI programming with coroutines](ui/coroutines-guide-ui.md) 1512 * [Guide to reactive streams with coroutines](reactive/coroutines-guide-reactive.md) 1513* Code is published to JCenter repository. 1514 1515## Version 0.12 1516 1517* Switched to Kotlin version 1.1.0 release. 1518* Reworked and updated utilities for 1519 [Reactive Streams](kotlinx-coroutines-reactive), 1520 [Rx 1.x](kotlinx-coroutines-rx1), and 1521 [Rx 2.x](kotlinx-coroutines-rx2) with library-specific 1522 coroutine builders, suspending functions, converters and iteration support. 1523* `LinkedListChannel` with unlimited buffer (`offer` always succeeds). 1524* `onLock` select clause and an optional `owner` parameter in all `Mutex` functions. 1525* `selectUnbiased` function. 1526* `actor` coroutine builder. 1527* Couple more examples for "Shared mutable state and concurrency" section and 1528 "Channels are fair" section with ping-pong table example 1529 in [coroutines guide](docs/topics/coroutines-guide.md). 1530 1531## Version 0.11-rc 1532 1533* `select` expression with onJoin/onAwait/onSend/onReceive clauses. 1534* `Mutex` is moved to `kotlinx.coroutines.sync` package. 1535* `ClosedSendChannelException` is a subclass of `CancellationException` now. 1536* New sections on "Shared mutable state and concurrency" and "Select expression" 1537 in [coroutines guide](docs/topics/coroutines-guide.md). 1538 1539## Version 0.10-rc 1540 1541* Switched to Kotlin version 1.1.0-rc-91. 1542* `Mutex` synchronization primitive is introduced. 1543* `buildChannel` is renamed to `produce`, old name is deprecated. 1544* `Job.onCompletion` is renamed to `Job.invokeOnCompletion`, old name is deprecated. 1545* `delay` implementation in Swing, JavaFx, and scheduled executors is fixed to avoid an extra dispatch. 1546* `CancellableContinuation.resumeUndispatched` is introduced to make this efficient implementation possible. 1547* Remove unnecessary creation of `CancellationException` to improve performance, plus other performance improvements. 1548* Suppress deprecated and internal APIs from docs. 1549* Better docs at top level with categorized summary of classes and functions. 1550 1551## Version 0.8-beta 1552 1553* `defer` coroutine builder is renamed to `async`. 1554* `lazyDefer` is deprecated, `async` has an optional `start` parameter instead. 1555* `LazyDeferred` interface is deprecated, lazy start functionality is integrated into `Job` interface. 1556* `launch` has an optional `start` parameter for lazily started coroutines. 1557* `Job.start` and `Job.isCompleted` are introduced. 1558* `Deferred.isCompletedExceptionally` and `Deferred.isCancelled` are introduced. 1559* `Job.getInactiveCancellationException` is renamed to `getCompletionException`. 1560* `Job.join` is now a member function. 1561* Internal `JobSupport` state machine is enhanced to support _new_ (not-started-yet) state. 1562 So, lazy coroutines do not need a separate state variable to track their started/not-started (new/active) status. 1563* Exception transparency in `Job.cancel` (original cause is rethrown). 1564* Clarified possible states for `Job`/`CancellableContinuation`/`Deferred` in docs. 1565* Example on async-style functions and links to API reference site from [coroutines guide](docs/topics/coroutines-guide.md). 1566 1567## Version 0.7-beta 1568 1569* Buffered and unbuffered channels are introduced: `Channel`, `SendChannel`, and `ReceiveChannel` interfaces, 1570 `RendezvousChannel` and `ArrayChannel` implementations, `Channel()` factory function and `buildChannel{}` 1571 coroutines builder. 1572* `Here` context is renamed to `Unconfined` (the old name is deprecated). 1573* A [guide on coroutines](docs/topics/coroutines-guide.md) is expanded: sections on contexts and channels. 1574 1575## Version 0.6-beta 1576 1577* Switched to Kotlin version 1.1.0-beta-37. 1578* A [guide on coroutines](docs/topics/coroutines-guide.md) is expanded. 1579 1580## Version 0.5-beta 1581 1582* Switched to Kotlin version 1.1.0-beta-22 (republished version). 1583* Removed `currentCoroutineContext` and related thread-locals without replacement. 1584 Explicitly pass coroutine context around if needed. 1585* `lazyDefer(context) {...}` coroutine builder and `LazyDeferred` interface are introduced. 1586* The default behaviour of all coroutine dispatchers is changed to always schedule execution of new coroutine 1587 for later in this thread or thread pool. Correspondingly, `CoroutineDispatcher.isDispatchNeeded` function 1588 has a default implementation that returns `true`. 1589* `NonCancellable` context is introduced. 1590* Performance optimizations for cancellable continuations (fewer objects created). 1591* A [guide on coroutines](docs/topics/coroutines-guide.md) is added. 1592 1593## Version 0.4-beta 1594 1595* Switched to Kotlin version 1.1.0-beta-18 (republished version). 1596* `CoroutineDispatcher` methods now have `context` parameter. 1597* Introduced `CancellableContinuation.isCancelled` 1598* Introduced `EventLoop` dispatcher and made it a default for `runBlocking { ... }` 1599* Introduced `CoroutineScope` interface with `isActive` and `context` properties; 1600 standard coroutine builders include it as receiver for convenience. 1601* Introduced `Executor.toCoroutineDispatcher()` extension. 1602* Delay scheduler thread is not daemon anymore, but times out automatically. 1603* Debugging facilities in `newCoroutineContext` can be explicitly disabled with `-Dkotlinx.coroutines.debug=off`. 1604* xxx-test files are renamed to xxx-example for clarity. 1605* Fixed NPE in Job implementation when starting coroutine with already cancelled parent job. 1606* Support cancellation in `kotlinx-coroutines-nio` module 1607