Releases: Kotlin/kotlinx.coroutines
Releases · Kotlin/kotlinx.coroutines
0.20
- Migrated to Kotlin 1.2.0.
- Channels:
- Sequence-like
filter
,map
, etc extensions onReceiveChannel
are introduced (see #88 by @fvasco and #69 by @konrad-kaminski). - Introduced
ReceiveChannel.cancel
method. - All operators on
ReceiveChannel
fully consume the original channel (cancel
it when they are done) using a helperconsume
extension. - Deprecated
ActorJob
andProducerJob
;actor
now returnsSendChannel
andproduce
returnsReceiveChannel
(see #127). SendChannel.sendBlocking
extension method (see #157 by @fvasco).
- Sequence-like
- Parent-child relations between coroutines:
- Introduced an optional
parent
job parameter for all coroutine builders so that code with an explict parentJob
is more natural. - Added
parent
parameter toCompletableDeferred
constructor. - Introduced
Job.children
property. Job.cancelChildren
is now an extension (member is deprecated and hidden).Job.joinChildren
extension is introduced.- Deprecated
Job.attachChild
as a error-prone API. - Fixed StackOverflow when waiting for a lot of completed children that did not remove their handlers from the parent.
- Introduced an optional
- Use
java.util.ServiceLoader
to find default instances ofCoroutineExceptionHandler
. - Android UI integration:
- Added missing
DefaultDispatcher
on some reactive operators (see #174 by @fvasco) - Fixed
actor
andproduce
so that a cancellation of a Job cancels the underlying channel (closes and removes all the pending messages). - Fixed sporadic failure of
example-context-06
(see #160) - Fixed hang of
Job.start
on lazy coroutine with attachedinvokeOnCompletion
handler. - A more gradual introduction to
runBlocking
and coroutines in the guide (see #166).
0.19.3
0.19.2
- Fixed
ArrayBroadcastChannel
receive of stale elements onopenSubscription
. Only elements that are sent after invocation ofopenSubscription
are received now. - Added a default value for
context
parameter torxFlowable
(see PR #146 by @PhilGlass). - Exception propagation logic from cancelled coroutines is adjusted (see #152):
- When cancelled coroutine crashes due to some other exception, this other exception becomes the cancellation reason of the coroutine, while the original cancellation reason is suppressed.
UnexpectedCoroutineException
is no longer used to report those cases as is removed.- This fixes a race between crash of CPU-consuming coroutine and cancellation which resulted in an unhandled exception and lead to crashes on Android.
run
uses cancelling state & propagates exceptions when cancelled (see #147):- When coroutine that was switched into a different dispatcher using
run
is cancelled, the run invocation does not complete immediately, but waits until the body completes. - If the body completes with exception, then this exception is propagated.
- When coroutine that was switched into a different dispatcher using
- No
Job
innewSingleThreadContext
andnewFixedThreadPoolContext
anymore (see #149, #151):- This resolves the common issue of using
run(ctx)
where ctx comes from eithernewSingleThreadContext
ornewFixedThreadPoolContext
invocation. They both used to return a combination of dispatcher + job, and this job was overriding the parent job, thus preventing propagation of cancellation. Not anymore. ThreadPoolDispatcher
class is now public and is the result type for both functions. It has theclose
method to release the thread pool.
- This resolves the common issue of using
0.19.1
- Failed parent Job cancels all children jobs, then waits for them them. This makes parent-child hierarchies easier to get working right without having to use
try/catch
or other exception handlers. - Fixed a race in
ArrayBroadcastChannel
betweensend
andopenChannel
invocations (see #138). - Fixed quite a rare race in
runBlocking
that resulted inAssertionError
. Unfortunately, cannot write a reliable stress-test to reproduce it. - Updated Reactor support to leverage Bismuth release train (contributed by @sdeleuze, see PR #141)
0.19
- This release is published to Maven Central.
DefaultDispatcher
is introduced (see #136):launch
,async
,produce
,actor
and other integration-specific coroutine builders now use
DefaultDispatcher
as the default value for theircontext
parameter.- When a context is explicitly specified,
newCoroutineContext
function checks if there is any
interceptor/dispatcher defined in the context and usesDefaultDispatcher
if there is none. DefaultDispatcher
is currently defined to be equal toCommonPool
.- Examples in the guide now start with
launch { ... }
code and explanation on the nature
and the need for coroutine context starts in "Coroutine context and dispatchers" section.
- Parent coroutines now wait for their children (see #125):
- Job completing state is introduced in documentation as a state in which parent coroutine waits for its children.
Job.attachChild
andJob.cancelChildren
are introduced.Job.join
now always checks cancellation status of invoker coroutine for predictable behavior when joining
failed child coroutine.Job.cancelAndJoin
extension is introduced.CoroutineContext.cancel
andCoroutineContext.cancelChildren
extensions are introduced for convenience.withTimeout
/withTimeoutOrNull
blocks become proper coroutines that haveCoroutineScope
and wait for children, too.- Diagnostics in cancellation and unexpected exception messages are improved,
coroutine name is included in debug mode. - Fixed cancellable suspending functions to throw
CancellationException
(as was documented before) even when
the coroutine is cancelled with another application-specific exception. JobCancellationException
is introduced as a specific subclass ofCancellationException
which is
used for coroutines that are cancelled without cause and to wrap application-specific exceptions.Job.getCompletionException
is renamed toJob.getCancellationException
and return a wrapper exception if needed.- Introduced
Deferred.getCompletionExceptionOrNull
to get not-wrapped exception result ofasync
task. - Updated docs for
Job
&Deferred
to explain parent/child relations.
select
expression is modularized:SelectClause(0,1,2)
interfaces are introduced, so that synchronization
constructs can define their select clauses without having to modify
the source of theSelectBuilder
inkotlinx-corounes-core
module.Job.onJoin
,Deferred.onAwait
,Mutex.onLock
,SendChannel.onSend
,ReceiveChannel.onReceive
, etc
that were functions before are now properties returning the corresponding select clauses. Old functions
are left in bytecode for backwards compatibility on use-site, but any outside code that was implementing those
interfaces by itself must be updated.- This opens road to moving channels into a separate module in future updates.
- Renamed
TimeoutException
toTimeoutCancellationException
(old name is deprecated). - Fixed various minor problems:
kotlinx-coroutines-io
module is introduced. It is a work-in-progress onByteReadChannel
andByteWriteChannel
interfaces, their implementations, and related classes to enable convenient coroutine integration with various
asynchronous I/O libraries and sockets. It is currently unstable and will change in the next release.
0.18
- Kotlin 1.1.4 is required to use this version, which enables:
withLock
andconsumeEach
functions are now inline suspend functions.JobSupport
class implementation is optimized (one fewer field).
TimeoutException
is public (see #89).- Improvements to
Mutex
(courtesy of @fvasco): - Fixed NPE when
ArrayBroadcastChannel
is closed concurrently with receive (see #97). - Fixed bug in internal class LockFreeLinkedList that resulted in ISE under stress in extremely rare circumstances.
- Integrations:
- quasar: Introduced integration with suspendable JVM functions
that are instrumented with Parallel Universe Quasar
(thanks to the help of @pron). - reactor: Replaced deprecated
setCancellation
withonDipose
and
updated to Aluminium-SR3 release (courtesy of @yxf07, see #96) - jdk8: Added adapters for
java.time
classes (courtesy of @fvasco, see #93)
- quasar: Introduced integration with suspendable JVM functions
0.17
CompletableDeferred
is introduced as a set-once event-like communication primitive (see #70).- Coroutines guide uses it in a section on actors.
CompletableDeferred
is an interface with private impl (courtesy of @fvasco, see #86).- It extends
Deferred
interface withcomplete
andcompleteExceptionally
functions.
Job.join
andDeferred.await
wait until a cancelled coroutine stops execution (see #64).Job
andDeferred
have a new cancelling state which they enter on invocation ofcancel
.Job.invokeOnCompletion
has an additional overload withonCancelling: Boolean
parameter to install handlers that are fired as soon as coroutine enters cancelling state as opposed to waiting until it completes.- Internal
select
implementation is refactored to decouple it fromJobSupport
internal class and to optimize its state-machine. - Internal
AbstractCoroutine
class is refactored so that it is extended only by true coroutines, all of which support the new cancelling state.
CoroutineScope.context
is renamed tocoroutineContext
to avoid conflicts with other usages ofcontext
in applications (like Android context, see #75).BroadcastChannel.open
is renamed toopenSubscription
(see #54).- Fixed
StackOverflowError
in a convoy ofMutex.unlock
invokers withUnconfined
dispatcher (see #80). - Fixed
SecurityException
when trying to use coroutines library with installedSecurityManager
. - Fixed a bug in
withTimeoutOrNull
in case with nested timeouts when coroutine was cancelled before it was ever suspended. - Fixed a minor problem with
awaitFirst
on reactive streams that would have resulted in spurious stack-traces printed on the console when used with publishers/observables that continue to invokeonNext
despite being cancelled/disposed (which they are technically allowed to do by specification). - All factory functions for various interfaces are implemented as top-level functions (affects
Job
,Channel
,BroadcastChannel
,Mutex
,EventLoop
, andCoroutineExceptionHandler
). Previous approach of usingoperator invoke
on their companion objects is deprecated. - Nicer-to-use debug
toString
implementations for coroutine dispatcher tasks and continuations. - A default dispatcher for
delay
is rewritten and now shares code withEventLoopImpl
that is used byrunBlocking
. It internally supports non-defaultTimeSource
so that delay-using tests can be written with "virtual time" by replacing their time source for the duration of tests (this feature is not available outside of the library).
0.16
- Coroutines that are scheduled for execution are cancellable by default now
suspendAtomicCancellableCoroutine
function is introduced for funs like
send
/receive
/receiveOrNull
that require atomic cancellation
(they cannot be cancelled after decision was made)- Coroutines started with default mode using
async
/launch
/actor
builders can be cancelled before their execution starts CoroutineStart.ATOMIC
is introduced as a start mode to specify that
coroutine cannot be cancelled before its execution startsrun
function is also cancellable in the same way and accepts an optional
CoroutineStart
parameter to change this default.
BroadcastChannel
factory function is introducedCorouiteExceptionHandler
factory function is introduced by @konrad-kaminskiintegration
directory is introduced for all 3rd party integration projects- It has contribution guidelines and contributions from community are welcome
- Support for Guava
ListenableFuture
in the newkotlinx-coroutines-guava
module - Rx1 Scheduler support by @konrad-kaminski
- #66 Fixed a number of
Channel
andBroadcastChannel
implementation bugs related to concurrent send/close/close of channels that lead to hanging send, offer or close operations.
Thanks to @chrisly42 and @cy6erGn0m for finding them. - #67 Fixed
withTimeoutOrNull
which was returningnull
on timeout of inner or outerwithTimeout
blocks.
Thanks to @gregschlom for finding the problem. - Fixed a bug where
Job
fails to dispose a handler when it is the only handler by @uchuhimo
0.15
Version 0.15
- Switched to Kotlin version 1.1.2 (can still be used with 1.1.0).
CoroutineStart
enum is introduced forlaunch
/async
/actor
builders:- The usage of
luanch(context, start = false)
is deprecated and is replaced with
launch(context, CoroutineStart.LAZY)
CoroutineStart.UNDISPATCHED
is introduced to start coroutine execution immediately in the invoker thread,
so thatasync(context, CoroutineStart.UNDISPATCHED)
is similar to the behavior of C#async
.- Guide to UI programming with coroutines mentions the use of it to optimize
the start of coroutines from UI threads.
- The usage of
- Introduced
BroadcastChannel
interface inkotlinx-coroutines-core
module:- It extends
SendChannel
interface and providesopen
function to create subscriptions. - Subscriptions are represented with
SubscriptionReceiveChannel
interface. - The corresponding
SubscriptionReceiveChannel
interfaces are removed from reactive implementation
modules. They use an interface defined inkotlinx-coroutines-core
module. ConflatedBroadcastChannel
implementation is provided for state-observation-like use-cases, where a coroutine or a
regular code (in UI, for example) updates the state that subscriber coroutines shall react to.ArrayBroadcastChannel
implementation is provided for event-bus-like use-cases, where a sequence of events shall
be received by multiple subscribers without any omissions.- Guide to reactive streams with coroutines includes
"Rx Subject vs BroadcastChannel" section.
- It extends
- Pull requests from Konrad Kamiński are merged into reactive stream implementations:
- Support for Project Reactor
Mono
andFlux
.
Seekotlinx-coroutines-reactor
module. - Implemented Rx1
Completable.awaitCompleted
. - Added support for Rx2
Maybe
.
- Support for Project Reactor
- Better timeout support:
- Introduced
withTimeoutOrNull
function. - Implemented
onTimeout
clause forselect
expressions. - Fixed spurious concurrency inside
withTimeout
blocks on their cancellation. - Changed the behavior of
withTimeout
whenCancellationException
is suppressed inside the block. The
invocation ofwithTimeout
now always returns the result of the execution of its inner block.
- Introduced
- The
channel
property inActorScope
is promoted to a widerChannel
type, so that an actor
can have an easy access to its own inbox send channel. - Renamed
Mutex.withMutex
toMutex.withLock
, old name is deprecated.
0.14
- Switched to Kotlin version 1.1.1 (can still be used with 1.1.0)
- Introduced
consumeEach
helper function for channels and reactive streams, Rx 1.x, and Rx 2.x- It ensures that streams are unsubscribed from on any exception
- Iteration with
for
loop on reactive streams is deprecated - Guide to reactive streams with coroutines is updated virtually
all over the place to reflect these important changes
- Implemented
awaitFirstOrDefault
extension for reactive streams, Rx 1.x, and Rx 2.x - Added
Mutex.withMutex
helper function kotlinx-coroutines-android
module hasprovided
dependency on of Android APIs to
eliminate warnings when using it in android project