Kotlinx.coroutines Versions Save

• Atomic update, getAndUpdate, and updateAndGet operations of MutableStateFlow (#2720).
• Executor.asCoroutineDispatcher implementation improvements (#2601):
  • If the target executor is ScheduledExecutorService, then its schedule API is used for time-related coroutine operations.
  • RemoveOnCancelPolicy is now part of the public contract.
• Introduced overloads for Task.asDeferred and Task.await that accept CancellationTokenSource for bidirectional cancellation (#2527).
• Reactive streams are updated to 1.0.3 (#2740).
• CopyableThrowable is allowed to modify the exception message during stacktrace recovery (#1931).
• CoroutineDispatcher.releaseInterceptedContinuation is now a final method (#2785).
• Closing a Handler underlying Handler.asCoroutineDispatcher now causes the dispatched coroutines to be canceled on Dispatchers.IO (#2778).
• Kotlin is updated to 1.5.20.
• Fixed a spurious ClassCastException in releaseInterceptedContinuation and IllegalStateException from tryReleaseClaimedContinuation (#2736, #2768).
• Fixed inconsistent exception message during stacktrace recovery for non-suspending channel iterators (#2749).
• Fixed linear stack usage for CompletableFuture.asDeferred when the target future has a long chain of listeners (#2730).
• Any exceptions from CoroutineDispatcher.isDispatchNeeded are now considered as fatal and are propagated to the caller (#2733).
• Internal DebugProbesKt (used in the debugger implementation) are moved from debug to core module.

Note 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.

Channels API

• 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.
• 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.
• 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.
• callbackFlow and channelFlow are promoted to stable API.

Reactive integrations

• 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).
• publish is no longer allowed to emit null values (#2646).
• Misleading awaitSingleOr* functions on Publisher type are deprecated (#2591).
• 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).
• ContextView support in kotlinx-coroutines-reactor (#2575).
• All reactive builders no longer ignore inner cancellation exceptions preventing their completion (#2262, #2646).
• MaybeSource.collect and Maybe.collect properly finish when they are completed without a value (#2617).
• All exceptions are now consistently handled according to reactive specification, whether they are considered 'fatal' or not by reactive frameworks (#2646).

Other improvements

• Kotlin version is upgraded to 1.5.0 and JVM target is updated to 1.8.
• Flow.last and Flow.lastOrNull operators (#2246).
• Flow.runningFold operator (#2641).
• CoroutinesTimeout rule for JUnit5 (#2197).
• Internals of Job and AbstractCoroutine was reworked, resulting in smaller code size, less memory footprint, and better performance (#2513, #2512).
• CancellationException from Kotlin standard library is used for cancellation on Koltin/JS and Kotlin/Native (#2638).
• Introduced new DelicateCoroutinesApi annotation that warns users about potential target API pitfalls and suggests studying API's documentation first. The only delicate API right now is GlobalScope (#2637).
• Fixed bug introduced in 1.4.3 when kotlinx-coroutines-core.jar triggered IDEA debugger failure (#2619).
• Fixed memory leak of ChildHandlerNode with reusable continuations (#2564).
• Various documentation improvements (#2555, #2589, #2592, #2583, #2437, #2616, #2633, #2560).

Changelog relative to version 1.5.0-RC

• Fail-fast during emitAll called from cancelled onCompletion operator (#2700).
• Flows returned by stateIn/shareIn keep strong reference to sharing job (#2557).
• Rename internal TimeSource to AbstractTimeSource due to import issues (#2691).
• Reverted the change that triggered IDEA coroutines debugger crash (#2695, reverted #2291).
• watchosX64 target support for Kotlin/Native (#2524).
• Various documentation fixes and improvements.

Channels API

• 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.
• 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.
• 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.
• callbackFlow and channelFlow are promoted to stable API.

Reactive integrations

• 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).
• publish is no longer allowed to emit null values (#2646).
• Misleading awaitSingleOr* functions on Publisher type are deprecated (#2591).
• 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).
• ContextView support in kotlinx-coroutines-reactor (#2575).
• All reactive builders no longer ignore inner cancellation exceptions preventing their completion (#2262, #2646).
• MaybeSource.collect and Maybe.collect properly finish when they are completed without a value (#2617).
• All exceptions are now consistently handled according to reactive specification, whether they are considered 'fatal' or not by reactive frameworks (#2646).

Other improvements

• Flow.last and Flow.lastOrNull operators (#2246).
• Flow.runningFold operator (#2641).
• CoroutinesTimeout rule for JUnit5 (#2197).
• Internals of Job and AbstractCoroutine was reworked, resulting in smaller code size, less memory footprint, and better performance (#2513, #2512).
• CancellationException from Kotlin standard library is used for cancellation on Koltin/JS and Kotlin/Native (#2638).
• Introduced new DelicateCoroutineApi annotation that warns users about potential target API pitfalls and suggests studying API's documentation first. The only delicate API right now is GlobalScope (#2637).
• Fixed bug introduced in 1.4.3 when kotlinx-coroutines-core.jar triggered IDEA debugger failure (#2619).
• Fixed memory leak of ChildHandlerNode with reusable continuations (#2564).
• Various documentation improvements (#2555, #2589, #2592, #2583, #2437, #2616, #2633, #2560).

General changes

• Thread context is properly preserved and restored for coroutines without ThreadContextElement (#985)
• ThreadContextElements are now restored in the opposite order from update (#2195)
• Improved performance of combine with 4 parameters, thanks to @alexvanyo (#2419)
• Debug agent sanitizer leaves at least one frame with source location (#1437)
• Update Reactor version in kotlinx-coroutines-reactor to 3.4.1, thanks to @sokomishalov (#2432)
• callsInPlace contract added to ReceiveChannel.consume (#941)
• CoroutineStart.UNDISPATCHED promoted to stable API (#1393)
• Kotlin updated to 1.4.30
• kotlinx.coroutines are now released directly to MavenCentral
• Reduced the size of DispatchedCoroutine by a field
• Internal class TimeSource renamed to SchedulerTimeSource to prevent wildcard import issues (#2537)

Bug fixes

• Fixed the problem that prevented implementation via delegation for Job interface (#2423)
• Fixed incorrect ProGuard rules that allowed shrinking volatile felds (#1564)
• Fixed await/asDeferred for MinimalStage implementations in jdk8 module (#2456)
• Fixed bug when onUndeliveredElement wasn't called for unlimited channels (#2435)
• Fixed a bug when ListenableFuture.isCancelled returned from asListenableFuture could have thrown an exception, thanks to @vadimsemenov (#2421)
• Coroutine in callbackFlow and produce is properly cancelled when the channel was closed separately (#2506)

• Fixed StackOverflowError in Job.toString when Job is observed in its intermediate state (#2371).
• Improved liveness and latency of Dispatchers.Default and Dispatchers.IO in low-loaded mode (#2381).
• Improved performance of consecutive Channel.cancel invocations (#2384).
• SharingStarted is now fun interface (#2397).
• Additional lint settings for SharedFlow to catch programmatic errors early (#2376).
• Fixed bug when mutex and semaphore were not released during cancellation (#2390, thanks to @Tilps for reproducing).
• Some corner cases in cancellation propagation between coroutines and listenable futures are repaired (#1442, thanks to @vadimsemenov).
• Fixed unconditional cast to CoroutineStackFrame in exception recovery that triggered failures of instrumented code (#2386).
• Platform-specific dependencies are removed from kotlinx-coroutines-javafx (#2360).

This is a patch release with an important fix to the SharedFlow implementation.

• SharedFlow: Fix scenario with concurrent emitters and cancellation of a subscriber (#2359, thanks to @vehovsky for the bug report).

Improvements

• StateFlow, SharedFlow and corresponding operators are promoted to stable API (#2316).
• Flow.debounce operator with timeout selector based on each individual element is added (#1216, thanks to @mkano9!).
• CoroutineContext.job extension property is introduced (#2159).
• Flow.combine operator is reworked:
  • Complete fairness is maintained for single-threaded dispatchers.
  • Its performance is improved, depending on the use-case, by at least 50% (#2296).
  • Quadratic complexity depending on the number of upstream flows is eliminated (#2296).
  • crossinline and inline-heavy internals are removed, fixing sporadic SIGSEGV on Mediatek Android devices (#1683, #1743).
• Flow.zip operator performance is improved by 40%.
• Various API has been promoted to stable or its deprecation level has been raised (#2316).

Bug fixes

• Suspendable stateIn operator propagates exception to the caller when upstream fails to produce initial value (#2329).
• Fix SharedFlow with replay for subscribers working at different speed (#2325).
• Do not fail debug agent installation when security manager does not provide access to system properties (#2311).
• Cancelled lazy coroutines are properly cleaned up from debug agent output (#2294).
• BlockHound false-positives are correctly filtered out (#2302, #2190, #2303).
• Potential crash during a race between cancellation and upstream in Observable.asFlow is fixed (#2104, #2299, thanks to @LouisCAD and @drinkthestars).

Breaking changes

• The concept of atomic cancellation in channels is removed. All operations in channels and corresponding Flow operators are cancellable in non-atomic way (#1813).
• If CoroutineDispatcher throws RejectedExecutionException, cancel current Job and schedule its execution to Dispatchers.IO (#2003).
• CancellableContinuation.invokeOnCancellation is invoked if the continuation was cancelled while its resume has been dispatched (#1915).
• Flow.singleOrNull operator is aligned with standard library and does not longer throw IllegalStateException on multiple values (#2289).

New experimental features

• SharedFlow primitive for managing hot sources of events with support of various subscription mechanisms, replay logs and buffering (#2034).
• Flow.shareIn and Flow.stateIn operators to transform cold instances of flow to hot SharedFlow and StateFlow respectively (#2047).

Other

• Support leak-free closeable resources transfer via onUndeliveredElement in channels (#1936).
• Changed ABI in reactive integrations for Java interoperability (#2182).
• Fixed ProGuard rules for kotlinx-coroutines-core (#2046, #2266).
• Lint settings were added to Flow to avoid accidental capturing of outer CoroutineScope for cancellation check (#2038).

External contributions

• Allow nullable types in Flow.firstOrNull and Flow.singleOrNull by @ansman (#2229).
• Add Publisher.awaitSingleOrDefault|Null|Else extensions by @sdeleuze (#1993).
• awaitCancellation top-level function by @LouisCAD (#2213).
• Significant part of our Gradle build scripts were migrated to .kts by @turansky.

Thank you for your contributions and participation in the Kotlin community!

• Support of CoroutineContext in Flow.asPublisher and similar reactive builders (#2155).
• Kotlin updated to 1.4.0.
• Transition to new HMPP publication scheme for multiplatform usages:
  • Artifacts kotlinx-coroutines-core-common and kotlinx-coroutines-core-native are removed.
  • For multiplatform usages, it's enough to depend directly on kotlinx-coroutines-core in commonMain source-set.
  • The same artifact coordinates can be used to depend on a platform-specific artifact in platform-specific source-set.

New experimental features

• Added Flow.transformWhile operator (#2065).
• Replaced scanReduce with runningReduce to be consistent with the Kotlin standard library (#2139).

Bug fixes and improvements

• Improve user experience for the upcoming coroutines debugger (#2093, #2118, #2131).
• Debugger no longer retains strong references to the running coroutines (#2129).
• Fixed race in Flow.asPublisher (#2109).
• Fixed ensureActive to work in the empty context case to fix IllegalStateException when using flow from suspend fun main (#2044).
• Fixed a problem with AbortFlowException in the Flow.first operator to avoid erroneous NoSuchElementException (#2051).
• Fixed JVM dependency on Android annotations (#2075).
• Removed keep rules mentioning kotlinx.coroutines.android from core module (#2061 by @mkj-gram).
• Corrected some docs and examples (#2062, #2071, #2076, #2107, #2098, #2127, #2078, #2135).
• Improved the docs and guide on flow cancellation (#2043).
• Updated Gradle version to 6.3 (it only affects multiplatform artifacts in this release).