Merge pull request #646 from Kotlin/version-0.30.1

Version 0.30.1

Author: qwwdfsad

CHANGES.md

@@ -1,5 +1,13 @@
 # Change log for kotlinx.coroutines
 
+## Version 0.30.1
+ Maintenance release:
+ * 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. 
+ * 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.
+ * Fixed bug with thread unsafety of shutdown sequence in `EventLoop`.
+ * 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).
+ * Atomicfu version is updated with fixes in JS transformer (see #609)
+
 ## Version 0.30.0
 
 * **[Major]** Further improvements in exception handling — no failure exception is lost. 

COMPATIBILITY.md

@@ -18,8 +18,8 @@ stable public API, and thus `kotlinx.coroutines` is leaving its "experimental" s
 Version `1.0.0` (starting with its release candidate build) will have all its deprecated declarations removed and `kotlinx.coroutines.experimental` package will be renamed to `kotlinx.coroutines` without functional changes.
 In order to migrate `kotlinx.coroutines` to `1.0.0`, follow these steps:
 
-1. Update `kotlinx.coroutines` to `0.30.0` version.
+1. Update `kotlinx.coroutines` to `0.30.1` version.
 2. Inspect compiler warnings about deprecated API and migrate it to a proposed alternative. Most of deprecated API has a corresponding   replacement which can be applied from IDEA with quickfix.
-3. Update Kotlin version to `1.3.0` or to the latest `1.3.0-rc` and `kotlinx.coroutines` to version `0.30.0-eap13`. Then just get rid of `experimental` suffix in all imports.
+3. Update Kotlin version to `1.3.0` or to the latest `1.3.0-rc` and `kotlinx.coroutines` to version `0.30.1-eap13`. Then just get rid of `experimental` suffix in all imports.
 4. Update `kotlinx.coroutines` to version `1.0.0` or to the corresponding release candidate of it).
 

README.md

@@ -2,7 +2,7 @@
 
 [![official JetBrains project](http://jb.gg/badges/official.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub)
 [![GitHub license](https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat)](http://www.apache.org/licenses/LICENSE-2.0)
-[![Download](https://api.bintray.com/packages/kotlin/kotlinx/kotlinx.coroutines/images/download.svg?version=0.30.0) ](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines/0.30.0)
+[![Download](https://api.bintray.com/packages/kotlin/kotlinx/kotlinx.coroutines/images/download.svg?version=0.30.1) ](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines/0.30.1)
 
 Library support for Kotlin coroutines with [multiplatform](#multiplatform) support.
 This is a companion version for Kotlin 1.2.70 release.
@@ -21,9 +21,12 @@ GlobalScope.launch {
 * [common](common/README.md) — common coroutines across all backends:
   * `launch` and `async` coroutine builders;
   * `Job` and `Deferred` light-weight future with cancellation support;
+  *` Dispatchers.Main` for UI dispatcher for Android, Swing and JavaFx;
   * `delay` and `yield` top-level suspending functions;
   * `Channel` and `Mutex` communication and synchronization primitives;
   * `produce` and `actor` coroutine builders;
+  * `coroutineScope` and `supervisorScope` scope builders;
+  * `SupervisorJob` for supervision of coroutines hierarchies;
   * `select` expression support and more.
 * [core](core/README.md) — Kotlin/JVM implementation of common coroutines with additional features:
   * `Dispatchers.IO` dispatcher for blocking coroutines.
@@ -39,8 +42,8 @@ GlobalScope.launch {
 ## Documentation
 
 * Presentations and videos:
-   * [Introduction to Coroutines](https://www.youtube.com/watch?v=_hfBv0a09Jc) (Roman Elizarov at KotlinConf 2017, [slides](https://www.slideshare.net/elizarov/introduction-to-coroutines-kotlinconf-2017))
-   * [Deep dive into Coroutines](https://www.youtube.com/watch?v=YrrUCSi72E8) (Roman Elizarov at KotlinConf 2017, [slides](https://www.slideshare.net/elizarov/deep-dive-into-coroutines-on-jvm-kotlinconf-2017))
+  * [Introduction to Coroutines](https://www.youtube.com/watch?v=_hfBv0a09Jc) (Roman Elizarov at KotlinConf 2017, [slides](https://www.slideshare.net/elizarov/introduction-to-coroutines-kotlinconf-2017))
+  * [Deep dive into Coroutines](https://www.youtube.com/watch?v=YrrUCSi72E8) (Roman Elizarov at KotlinConf 2017, [slides](https://www.slideshare.net/elizarov/deep-dive-into-coroutines-on-jvm-kotlinconf-2017))
 * Guides and manuals: 
   * [Guide to kotlinx.coroutines by example](docs/coroutines-guide.md) (**read it first**)
   * [Guide to UI programming with coroutines](ui/coroutines-guide-ui.md)
@@ -82,7 +85,7 @@ And make sure that you use the latest Kotlin version:
 Add dependencies (you can also add other modules that you need):
 
 ```groovy
-implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:0.30.0'
+implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:0.30.1'
 ```
 
 And make sure that you use the latest Kotlin version:
@@ -115,7 +118,7 @@ Add [`kotlinx-coroutines-android`](ui/kotlinx-coroutines-android)
 module as dependency when using `kotlinx.coroutines` on Android:
 
 ```groovy
-implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:0.30.0'
+implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:0.30.1'
 ```
 This gives you access to Android [Dispatchers.Main](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-android/kotlinx.coroutines.experimental.android/kotlinx.coroutines.experimental.-dispatchers/index.html)
 coroutine dispatcher and also makes sure that in case of crashed coroutine with unhandled exception this

binary-compatibility-validator/reference-public-api/kotlinx-coroutines-android.txt

@@ -4,6 +4,7 @@ public final class kotlinx/coroutines/experimental/android/HandlerContext : kotl
 	public final fun awaitFrame (Lkotlin/coroutines/experimental/Continuation;)Ljava/lang/Object;
 	public fun dispatch (Lkotlin/coroutines/experimental/CoroutineContext;Ljava/lang/Runnable;)V
 	public fun equals (Ljava/lang/Object;)Z
+	public synthetic fun getImmediate ()Lkotlinx/coroutines/experimental/MainCoroutineDispatcher;
 	public fun getImmediate ()Lkotlinx/coroutines/experimental/android/HandlerContext;
 	public synthetic fun getImmediate ()Lkotlinx/coroutines/experimental/android/HandlerDispatcher;
 	public fun hashCode ()I
@@ -18,7 +19,7 @@ public final class kotlinx/coroutines/experimental/android/HandlerContextKt {
 	public static final fun getUI ()Lkotlinx/coroutines/experimental/android/HandlerContext;
 }
 
-public abstract class kotlinx/coroutines/experimental/android/HandlerDispatcher : kotlinx/coroutines/experimental/CoroutineDispatcher, kotlinx/coroutines/experimental/Delay {
+public abstract class kotlinx/coroutines/experimental/android/HandlerDispatcher : kotlinx/coroutines/experimental/MainCoroutineDispatcher, kotlinx/coroutines/experimental/Delay {
 	public synthetic fun delay (JLjava/util/concurrent/TimeUnit;Lkotlin/coroutines/experimental/Continuation;)Ljava/lang/Object;
 	public fun delay (JLkotlin/coroutines/experimental/Continuation;)Ljava/lang/Object;
 	public abstract fun getImmediate ()Lkotlinx/coroutines/experimental/android/HandlerDispatcher;
@@ -32,6 +33,6 @@ public final class kotlinx/coroutines/experimental/android/HandlerDispatcherKt {
 	public static final fun from (Landroid/os/Handler;)Lkotlinx/coroutines/experimental/android/HandlerDispatcher;
 	public static final fun from (Landroid/os/Handler;Ljava/lang/String;)Lkotlinx/coroutines/experimental/android/HandlerDispatcher;
 	public static synthetic fun from$default (Landroid/os/Handler;Ljava/lang/String;ILjava/lang/Object;)Lkotlinx/coroutines/experimental/android/HandlerDispatcher;
-	public static final fun getMain (Lkotlinx/coroutines/experimental/Dispatchers;)Lkotlinx/coroutines/experimental/android/HandlerDispatcher;
+	public static final synthetic fun getMain (Lkotlinx/coroutines/experimental/Dispatchers;)Lkotlinx/coroutines/experimental/android/HandlerDispatcher;
 }
 

binary-compatibility-validator/reference-public-api/kotlinx-coroutines-core.txt

@@ -314,14 +314,15 @@ public final class kotlinx/coroutines/experimental/DispatchedTask$DefaultImpls {
 }
 
 public final class kotlinx/coroutines/experimental/Dispatchers {
-	public static final field Default Lkotlinx/coroutines/experimental/CoroutineDispatcher;
 	public static final field INSTANCE Lkotlinx/coroutines/experimental/Dispatchers;
-	public static final field Unconfined Lkotlinx/coroutines/experimental/CoroutineDispatcher;
+	public static final fun getDefault ()Lkotlinx/coroutines/experimental/CoroutineDispatcher;
+	public static final fun getIO ()Lkotlinx/coroutines/experimental/CoroutineDispatcher;
+	public static final fun getMain ()Lkotlinx/coroutines/experimental/MainCoroutineDispatcher;
+	public static final fun getUnconfined ()Lkotlinx/coroutines/experimental/CoroutineDispatcher;
 }
 
 public final class kotlinx/coroutines/experimental/DispatchersKt {
 	public static final field IO_PARALLELISM_PROPERTY_NAME Ljava/lang/String;
-	public static final fun getIO (Lkotlinx/coroutines/experimental/Dispatchers;)Lkotlinx/coroutines/experimental/CoroutineDispatcher;
 }
 
 public abstract interface class kotlinx/coroutines/experimental/DisposableHandle {
@@ -468,6 +469,11 @@ public final class kotlinx/coroutines/experimental/LazyDeferredKt {
 	public static final fun lazyDefer (Lkotlin/coroutines/experimental/CoroutineContext;Lkotlin/jvm/functions/Function2;)Lkotlinx/coroutines/experimental/Deferred;
 }
 
+public abstract class kotlinx/coroutines/experimental/MainCoroutineDispatcher : kotlinx/coroutines/experimental/CoroutineDispatcher {
+	public fun <init> ()V
+	public abstract fun getImmediate ()Lkotlinx/coroutines/experimental/MainCoroutineDispatcher;
+}
+
 public final class kotlinx/coroutines/experimental/NonCancellable : kotlin/coroutines/experimental/AbstractCoroutineContextElement, kotlinx/coroutines/experimental/Job {
 	public static final field INSTANCE Lkotlinx/coroutines/experimental/NonCancellable;
 	public fun attachChild (Lkotlinx/coroutines/experimental/ChildJob;)Lkotlinx/coroutines/experimental/ChildHandle;

binary-compatibility-validator/reference-public-api/kotlinx-coroutines-javafx.txt

@@ -1,18 +1,18 @@
 public final class kotlinx/coroutines/experimental/javafx/JavaFx : kotlinx/coroutines/experimental/javafx/JavaFxDispatcher {
 	public static final field INSTANCE Lkotlinx/coroutines/experimental/javafx/JavaFx;
 	public final fun awaitPulse (Lkotlin/coroutines/experimental/Continuation;)Ljava/lang/Object;
-	public fun dispatch (Lkotlin/coroutines/experimental/CoroutineContext;Ljava/lang/Runnable;)V
-	public fun invokeOnTimeout (JLjava/lang/Runnable;)Lkotlinx/coroutines/experimental/DisposableHandle;
-	public fun scheduleResumeAfterDelay (JLkotlinx/coroutines/experimental/CancellableContinuation;)V
+	public fun getImmediate ()Lkotlinx/coroutines/experimental/MainCoroutineDispatcher;
 	public fun toString ()Ljava/lang/String;
 }
 
-public abstract class kotlinx/coroutines/experimental/javafx/JavaFxDispatcher : kotlinx/coroutines/experimental/CoroutineDispatcher, kotlinx/coroutines/experimental/Delay {
+public abstract class kotlinx/coroutines/experimental/javafx/JavaFxDispatcher : kotlinx/coroutines/experimental/MainCoroutineDispatcher, kotlinx/coroutines/experimental/Delay {
 	public synthetic fun delay (JLjava/util/concurrent/TimeUnit;Lkotlin/coroutines/experimental/Continuation;)Ljava/lang/Object;
 	public fun delay (JLkotlin/coroutines/experimental/Continuation;)Ljava/lang/Object;
+	public fun dispatch (Lkotlin/coroutines/experimental/CoroutineContext;Ljava/lang/Runnable;)V
 	public fun invokeOnTimeout (JLjava/lang/Runnable;)Lkotlinx/coroutines/experimental/DisposableHandle;
 	public synthetic fun invokeOnTimeout (JLjava/util/concurrent/TimeUnit;Ljava/lang/Runnable;)Lkotlinx/coroutines/experimental/DisposableHandle;
 	public synthetic fun scheduleResumeAfterDelay (JLjava/util/concurrent/TimeUnit;Lkotlinx/coroutines/experimental/CancellableContinuation;)V
+	public fun scheduleResumeAfterDelay (JLkotlinx/coroutines/experimental/CancellableContinuation;)V
 }
 
 public final class kotlinx/coroutines/experimental/javafx/JavaFxDispatcherKt {

binary-compatibility-validator/reference-public-api/kotlinx-coroutines-swing.txt

@@ -1,17 +1,17 @@
 public final class kotlinx/coroutines/experimental/swing/Swing : kotlinx/coroutines/experimental/swing/SwingDispatcher {
 	public static final field INSTANCE Lkotlinx/coroutines/experimental/swing/Swing;
-	public fun dispatch (Lkotlin/coroutines/experimental/CoroutineContext;Ljava/lang/Runnable;)V
-	public fun invokeOnTimeout (JLjava/lang/Runnable;)Lkotlinx/coroutines/experimental/DisposableHandle;
-	public fun scheduleResumeAfterDelay (JLkotlinx/coroutines/experimental/CancellableContinuation;)V
+	public fun getImmediate ()Lkotlinx/coroutines/experimental/MainCoroutineDispatcher;
 	public fun toString ()Ljava/lang/String;
 }
 
-public abstract class kotlinx/coroutines/experimental/swing/SwingDispatcher : kotlinx/coroutines/experimental/CoroutineDispatcher, kotlinx/coroutines/experimental/Delay {
+public abstract class kotlinx/coroutines/experimental/swing/SwingDispatcher : kotlinx/coroutines/experimental/MainCoroutineDispatcher, kotlinx/coroutines/experimental/Delay {
 	public synthetic fun delay (JLjava/util/concurrent/TimeUnit;Lkotlin/coroutines/experimental/Continuation;)Ljava/lang/Object;
 	public fun delay (JLkotlin/coroutines/experimental/Continuation;)Ljava/lang/Object;
+	public fun dispatch (Lkotlin/coroutines/experimental/CoroutineContext;Ljava/lang/Runnable;)V
 	public fun invokeOnTimeout (JLjava/lang/Runnable;)Lkotlinx/coroutines/experimental/DisposableHandle;
 	public synthetic fun invokeOnTimeout (JLjava/util/concurrent/TimeUnit;Ljava/lang/Runnable;)Lkotlinx/coroutines/experimental/DisposableHandle;
 	public synthetic fun scheduleResumeAfterDelay (JLjava/util/concurrent/TimeUnit;Lkotlinx/coroutines/experimental/CancellableContinuation;)V
+	public fun scheduleResumeAfterDelay (JLkotlinx/coroutines/experimental/CancellableContinuation;)V
 }
 
 public final class kotlinx/coroutines/experimental/swing/SwingDispatcherKt {

common/kotlinx-coroutines-core-common/src/AbstractContinuation.kt

@@ -105,7 +105,7 @@ internal abstract class AbstractContinuation<in T>(
     /**
      * It is used when parent is cancelled to get the cancellation cause for this continuation.
      */
-    open fun getParentCancellationCause(parent: Job): Throwable =
+    open fun getContinuationCancellationCause(parent: Job): Throwable =
         parent.getCancellationException()
 
     private fun trySuspend(): Boolean {

common/kotlinx-coroutines-core-common/src/Dispatchers.common.kt

@@ -4,13 +4,12 @@
 
 package kotlinx.coroutines.experimental
 
-import kotlinx.coroutines.experimental.internal.*
 import kotlin.coroutines.experimental.*
 
 /**
  * Groups various implementations of [CoroutineDispatcher].
  */
-public object Dispatchers {
+expect object Dispatchers {
     /**
      * The default [CoroutineDispatcher] that is used by all standard builders like
      * [launch][CoroutineScope.launch], [async][CoroutineScope.async], etc
@@ -19,9 +18,27 @@ public object Dispatchers {
      * It is backed by a shared pool of threads on JVM. By default, the maximal number of threads used
      * by this dispatcher is equal to the number CPU cores, but is at least two.
      */
-    @JvmField
-    public val Default: CoroutineDispatcher =
-        createDefaultDispatcher()
+    public val Default: CoroutineDispatcher
+
+    /**
+     * A coroutine dispatcher that is confined to the Main thread operating with UI objects.
+     * Usually such dispatcher is single-threaded.
+     *
+     * Access to this property may throw [IllegalStateException] if no main dispatchers are present in the classpath.
+     *
+     * Depending on platform and classpath it can be mapped to different dispatchers:
+     * - On JS and Native it is equivalent of [Default] dispatcher.
+     * - On JVM it either Android main thread dispatcher, JavaFx or Swing EDT dispatcher. It is chosen by
+     *   [`ServiceLoader`](https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html).
+     *
+     * In order to work with `Main` dispatcher, following artifact should be added to project runtime dependencies:
+     *  - `kotlinx-coroutines-android` for Android Main thread dispatcher
+     *  - `kotlinx-coroutines-javafx` for JavaFx Application thread dispatcher
+     *  - `kotlinx-coroutines-swing` for Swing EDT dispatcher
+     *
+     * Implementation note: [MainCoroutineDispatcher.immediate] is not supported on Native and JS platforms.
+     */
+    public val Main: MainCoroutineDispatcher
 
     /**
      * A coroutine dispatcher that is not confined to any specific thread.
@@ -39,8 +56,6 @@ public object Dispatchers {
      * **Note: This is an experimental api.**
      * Semantics, order of execution, and particular implementation details of this dispatcher may change in the future.
      */
-    @JvmField
     @ExperimentalCoroutinesApi
-    public val Unconfined: CoroutineDispatcher =
-        kotlinx.coroutines.experimental.Unconfined
-}
+    public val Unconfined: CoroutineDispatcher
+}

common/kotlinx-coroutines-core-common/src/Job.kt

@@ -425,13 +425,30 @@ public inline fun DisposableHandle(crossinline block: () -> Unit) =
 internal interface ChildJob : Job {
     /**
      * Parent is cancelling its child by invoking this method.
-     * Child finds the cancellation cause using [getCancellationException] of the [parentJob].
+     * Child finds the cancellation cause using [ParentJob.getChildJobCancellationCause].
      * This method does nothing is the child is already being cancelled.
      *
      * @suppress **This is unstable API and it is subject to change.**
      */
     @InternalCoroutinesApi
-    public fun parentCancelled(parentJob: Job)
+    public fun parentCancelled(parentJob: ParentJob)
+}
+
+/**
+ * A reference that child receives from its parent when it is being cancelled by the parent.
+ *
+ * @suppress **This is unstable API and it is subject to change.**
+ */
+@InternalCoroutinesApi
+internal interface ParentJob : Job {
+    /**
+     * Child job is using this method to learn its cancellation cause when the parent cancels it with [ChildJob.parentCancelled].
+     * This method is invoked only if the child was not already being cancelled.
+     *
+     * @suppress **This is unstable API and it is subject to change.**
+     */
+    @InternalCoroutinesApi
+    public fun getChildJobCancellationCause(): Throwable
 }
 
 /**