Skip to content

Latest commit

 

History

History
307 lines (275 loc) · 19.5 KB

CHANGES.md

File metadata and controls

307 lines (275 loc) · 19.5 KB
Raw

Change log for kotlinx.coroutines

Version 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 between send and openChannel invocations (see #138).
  • Fixed quite a rare race in runBlocking that resulted in AssertionError. Unfortunately, cannot write a reliable stress-test to reproduce it.
  • Updated Reactor support to leverage Bismuth release train (contributed by @sdeleuze, see PR #141)

Version 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 their context parameter.
    • When a context is explicitly specified, newCoroutineContext function checks if there is any interceptor/dispatcher defined in the context and uses DefaultDispatcher if there is none.
    • DefaultDispatcher is currently defined to be equal to CommonPool.
    • 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 and Job.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 and CoroutineContext.cancelChildren extensions are introduced for convenience.
    • withTimeout/withTimeoutOrNull blocks become proper coroutines that have CoroutineScope 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 of CancellationException which is used for coroutines that are cancelled without cause and to wrap application-specific exceptions.
    • Job.getCompletionException is renamed to Job.getCancellationException and return a wrapper exception if needed.
    • Introduced Deferred.getCompletionExceptionOrNull to get not-wrapped exception result of async 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 the SelectBuilder in kotlinx-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 to TimeoutCancellationException (old name is deprecated).
  • Fixed various minor problems:
    • JavaFx toolkit is now initialized by JavaFx context (see #108).
    • Fixed lost ACC_STATIC on methods (see #116).
    • Fixed link to source code from documentation (see #129).
    • Fixed delay in arbitrary contexts (see #133).
  • kotlinx-coroutines-io module is introduced. It is a work-in-progress on ByteReadChannel and ByteWriteChannel 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.

Version 0.18

  • Kotlin 1.1.4 is required to use this version, which enables:
    • withLock and consumeEach 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):
    • Introduced holdsLock (see #92).
    • Improved documentation on Mutex fairness (see #90).
  • 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 with onDipose and updated to Aluminium-SR3 release (courtesy of @yxf07, see #96)
    • jdk8: Added adapters for java.time classes (courtesy of @fvasco, see #93)

Version 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 with complete and completeExceptionally functions.
  • Job.join and Deferred.await wait until a cancelled coroutine stops execution (see #64).
    • Job and Deferred have a new cancelling state which they enter on invocation of cancel.
    • Job.invokeOnCompletion has an additional overload with onCancelling: 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 from JobSupport 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 to coroutineContext to avoid conflicts with other usages of context in applications (like Android context, see #75).
  • BroadcastChannel.open is renamed to openSubscription (see #54).
  • Fixed StackOverflowError in a convoy of Mutex.unlock invokers with Unconfined dispatcher (see #80).
  • Fixed SecurityException when trying to use coroutines library with installed SecurityManager.
  • 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 invoke onNext 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, and CoroutineExceptionHandler). Previous approach of using operator 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 with EventLoopImpl that is used by runBlocking. It internally supports non-default TimeSource 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).

Version 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 starts
    • run function is also cancellable in the same way and accepts an optional CoroutineStart parameter to change this default.
  • BroadcastChannel factory function is introduced
  • CoroutineExceptionHandler factory function is introduced by @konrad-kaminski
  • integration directory is introduced for all 3rd party integration projects
  • Fixed a number of Channel and BroadcastChannel implementation bugs related to concurrent send/close/close of channels that lead to hanging send, offer or close operations (see #66). Thanks to @chrisly42 and @cy6erGn0m for finding them.
  • Fixed withTimeoutOrNull which was returning null on timeout of inner or outer withTimeout blocks (see #67). 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

Version 0.15

  • Switched to Kotlin version 1.1.2 (can still be used with 1.1.0).
  • CoroutineStart enum is introduced for launch/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 that async(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.
  • Introduced BroadcastChannel interface in kotlinx-coroutines-core module:
    • It extends SendChannel interface and provides open 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 in kotlinx-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.
  • Pull requests from Konrad Kamiński are merged into reactive stream implementations:
    • Support for Project Reactor Mono and Flux. See kotlinx-coroutines-reactor module.
    • Implemented Rx1 Completable.awaitCompleted.
    • Added support for Rx2 Maybe.
  • Better timeout support:
    • Introduced withTimeoutOrNull function.
    • Implemented onTimeout clause for select expressions.
    • Fixed spurious concurrency inside withTimeout blocks on their cancellation.
    • Changed behavior of withTimeout when CancellationException is suppressed inside the block. Invocation of withTimeout now always returns the result of execution of its inner block.
  • The channel property in ActorScope is promoted to a wider Channel type, so that an actor can have an easy access to its own inbox send channel.
  • Renamed Mutex.withMutex to Mutex.withLock, old name is deprecated.

Version 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 has provided dependency on of Android APIs to eliminate warnings when using it in android project.

Version 0.13

  • New kotlinx-coroutinex-android module with Android UI context implementation.
  • Introduced whileSelect convenience function.
  • Implemented ConflatedChannel.
  • Renamed various toXXX conversion functions to asXXX (old names are deprecated).
  • run is optimized with fast-path case and no longer has CoroutineScope in its block.
  • Fixed dispatching logic of withTimeout (removed extra dispatch).
  • EventLoop that is used by runBlocking now implements Delay, giving more predictable test behavior.
  • Various refactorings related to resource management and timeouts:
    • Job.Registration is renamed to DisposableHandle.
    • EmptyRegistration is renamed to NonDisposableHandle.
    • Job.unregisterOnCompletion is renamed to Job.disposeOnCompletion.
    • Delay.invokeOnTimeout is introduced.
    • withTimeout now uses Delay.invokeOnTimeout when available.
  • A number of improvement for reactive streams and Rx:
    • Introduced rxFlowable builder for Rx 2.x.
    • Scheduler.asCoroutineDispatcher extension for Rx 2.x.
    • Fixed bug with sometimes missing onComplete in publish, rxObservable, and rxFlowable builders.
    • Channels that are open for reactive streams are now Closeable.
    • Fixed CompletableSource.await and added test for it.
    • Removed rx.Completable.await due to name conflict.
  • New documentation:
  • Code is published to JCenter repository.

Version 0.12

  • Switched to Kotlin version 1.1.0 release.
  • Reworked and updated utilities for Reactive Streams, Rx 1.x, and Rx 2.x with library-specific coroutine builders, suspending functions, converters and iteration support.
  • LinkedListChannel with unlimited buffer (offer always succeeds).
  • onLock select clause and an optional owner parameter in all Mutex functions.
  • selectUnbiased function.
  • actor coroutine builder.
  • Couple more examples for "Shared mutable state and concurrency" section and "Channels are fair" section with ping-pong table example in coroutines guide.

Version 0.11-rc

  • select expression with onJoin/onAwait/onSend/onReceive clauses.
  • Mutex is moved to kotlinx.coroutines.experimental.sync package.
  • ClosedSendChannelException is a subclass of CancellationException now.
  • New sections on "Shared mutable state and concurrency" and "Select expression" in coroutines guide.

Version 0.10-rc

  • Switched to Kotlin version 1.1.0-rc-91.
  • Mutex synchronization primitive is introduced.
  • buildChannel is renamed to produce, old name is deprecated.
  • Job.onCompletion is renamed to Job.invokeOnCompletion, old name is deprecated.
  • delay implementation in Swing, JavaFx, and scheduled executors is fixed to avoid an extra dispatch.
  • CancellableContinuation.resumeUndispatched is introduced to make this efficient implementation possible.
  • Remove unnecessary creation of CancellationException to improve performance, plus other performance improvements.
  • Suppress deprecated and internal APIs from docs.
  • Better docs at top level with categorized summary of classes and functions.

Version 0.8-beta

  • defer coroutine builder is renamed to async.
  • lazyDefer is deprecated, async has an optional start parameter instead.
  • LazyDeferred interface is deprecated, lazy start functionality is integrated into Job interface.
  • launch has an optional start parameter for lazily started coroutines.
  • Job.start and Job.isCompleted are introduced.
  • Deferred.isCompletedExceptionally and Deferred.isCancelled are introduced.
  • Job.getInactiveCancellationException is renamed to getCompletionException.
  • Job.join is now a member function.
  • Internal JobSupport state machine is enhanced to support new (not-started-yet) state. So, lazy coroutines do not need a separate state variable to track their started/not-started (new/active) status.
  • Exception transparency in Job.cancel (original cause is rethrown).
  • Clarified possible states for Job/CancellableContinuation/Deferred in docs.
  • Example on async-style functions and links to API reference site from coroutines guide.

Version 0.7-beta

  • Buffered and unbuffered channels are introduced: Channel, SendChannel, and ReceiveChannel interfaces, RendezvousChannel and ArrayChannel implementations, Channel() factory function and buildChannel{} coroutines builder.
  • Here context is renamed to Unconfined (the old name is deprecated).
  • A guide on coroutines is expanded: sections on contexts and channels.

Version 0.6-beta

Version 0.5-beta

  • Switched to Kotlin version 1.1.0-beta-22 (republished version).
  • Removed currentCoroutineContext and related thread-locals without replacement. Explicitly pass coroutine context around if needed.
  • lazyDefer(context) {...} coroutine builder and LazyDeferred interface are introduced.
  • The default behaviour of all coroutine dispatchers is changed to always schedule execution of new coroutine for later in this thread or thread pool. Correspondingly, CoroutineDispatcher.isDispatchNeeded function has a default implementation that returns true.
  • NonCancellable context is introduced.
  • Performance optimizations for cancellable continuations (fewer objects created).
  • A guide on coroutines is added.

Version 0.4-beta

  • Switched to Kotlin version 1.1.0-beta-18 (republished version).
  • CoroutineDispatcher methods now have context parameter.
  • Introduced CancellableContinuation.isCancelled
  • Introduced EventLoop dispatcher and made it a default for runBlocking { ... }
  • Introduced CoroutineScope interface with isActive and context properties; standard coroutine builders include it as receiver for convenience.
  • Introduced Executor.toCoroutineDispatcher() extension.
  • Delay scheduler thread is not daemon anymore, but times out automatically.
  • Debugging facilities in newCoroutineContext can be explicitly disabled with -Dkotlinx.coroutines.debug=off.
  • xxx-test files are renamed to xxx-example for clarity.
  • Fixed NPE in Job implementation when starting coroutine with already cancelled parent job.
  • Support cancellation in kotlinx-coroutines-nio module