Merge pull request #876 from Kotlin/debug-agent

Coroutines debug agent

Fixes #772

Author: qwwdfsad

README.md

@@ -31,6 +31,8 @@ GlobalScope.launch {
 * [core](core/README.md) — Kotlin/JVM implementation of common coroutines with additional features:
   * `Dispatchers.IO` dispatcher for blocking coroutines;
   * `Executor.asCoroutineDispatcher()` extension, custom thread pools, and more.
+* [debug](core/README.md) — debug utilities for coroutines.
+  * `DebugProbes` API to probe, keep track of, print and dump active coroutines.
 * [js](js/README.md) — Kotlin/JS implementation of common coroutines with `Promise` support.
 * [native](native/README.md) — Kotlin/Native implementation of common coroutines with `runBlocking` single-threaded event loop.
 * [reactive](reactive/README.md) — modules that provide builders and iteration support for various reactive streams libraries:

RELEASE.md

@@ -12,7 +12,7 @@ To release new `<version>` of `kotlinx-coroutines`:
    `git merge origin/master`   
 
 4. Search & replace `<old-version>` with `<version>` across the project files. Should replace in:
-   * [`README.md`](README.md)
+   * [`README.md`](README.md) (native, core, test, debug, modules)
    * [`coroutines-guide.md`](docs/coroutines-guide.md)
    * [`gradle.properties`](gradle.properties)
    * [`ui/kotlinx-coroutines-android/example-app/gradle.properties`](ui/kotlinx-coroutines-android/example-app/gradle.properties)    

binary-compatibility-validator/build.gradle

@@ -13,6 +13,7 @@ dependencies {
     testCompile "org.jetbrains.kotlin:kotlin-test-junit:$kotlin_version"
 
     testArtifacts project(':kotlinx-coroutines-core')
+    testArtifacts project(':kotlinx-coroutines-debug')
 
     testArtifacts project(':kotlinx-coroutines-reactive')
     testArtifacts project(':kotlinx-coroutines-reactor')

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

@@ -349,6 +349,7 @@ public class kotlinx/coroutines/JobSupport : kotlinx/coroutines/ChildJob, kotlin
 	public fun plus (Lkotlinx/coroutines/Job;)Lkotlinx/coroutines/Job;
 	public final fun registerSelectClause0 (Lkotlinx/coroutines/selects/SelectInstance;Lkotlin/jvm/functions/Function1;)V
 	public final fun start ()Z
+	public final fun toDebugString ()Ljava/lang/String;
 	public fun toString ()Ljava/lang/String;
 }
 

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

@@ -0,0 +1,38 @@
+public final class kotlinx/coroutines/debug/CoroutineState {
+	public final fun component1 ()Lkotlin/coroutines/Continuation;
+	public final fun copy (Lkotlin/coroutines/Continuation;Lkotlin/coroutines/jvm/internal/CoroutineStackFrame;J)Lkotlinx/coroutines/debug/CoroutineState;
+	public static synthetic fun copy$default (Lkotlinx/coroutines/debug/CoroutineState;Lkotlin/coroutines/Continuation;Lkotlin/coroutines/jvm/internal/CoroutineStackFrame;JILjava/lang/Object;)Lkotlinx/coroutines/debug/CoroutineState;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getContinuation ()Lkotlin/coroutines/Continuation;
+	public final fun getCreationStackTrace ()Ljava/util/List;
+	public final fun getJob ()Lkotlinx/coroutines/Job;
+	public final fun getJobOrNull ()Lkotlinx/coroutines/Job;
+	public final fun getState ()Lkotlinx/coroutines/debug/State;
+	public fun hashCode ()I
+	public final fun lastObservedStackTrace ()Ljava/util/List;
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class kotlinx/coroutines/debug/DebugProbes {
+	public static final field INSTANCE Lkotlinx/coroutines/debug/DebugProbes;
+	public final fun dumpCoroutines (Ljava/io/PrintStream;)V
+	public static synthetic fun dumpCoroutines$default (Lkotlinx/coroutines/debug/DebugProbes;Ljava/io/PrintStream;ILjava/lang/Object;)V
+	public final fun dumpCoroutinesState ()Ljava/util/List;
+	public final fun getSanitizeStackTraces ()Z
+	public final fun hierarchyToString (Lkotlinx/coroutines/Job;)Ljava/lang/String;
+	public final fun install ()V
+	public final fun printHierarchy (Lkotlinx/coroutines/Job;Ljava/io/PrintStream;)V
+	public static synthetic fun printHierarchy$default (Lkotlinx/coroutines/debug/DebugProbes;Lkotlinx/coroutines/Job;Ljava/io/PrintStream;ILjava/lang/Object;)V
+	public final fun setSanitizeStackTraces (Z)V
+	public final fun uninstall ()V
+	public final fun withDebugProbes (Lkotlin/jvm/functions/Function0;)V
+}
+
+public final class kotlinx/coroutines/debug/State : java/lang/Enum {
+	public static final field CREATED Lkotlinx/coroutines/debug/State;
+	public static final field RUNNING Lkotlinx/coroutines/debug/State;
+	public static final field SUSPENDED Lkotlinx/coroutines/debug/State;
+	public static fun valueOf (Ljava/lang/String;)Lkotlinx/coroutines/debug/State;
+	public static fun values ()[Lkotlinx/coroutines/debug/State;
+}
+

build.gradle

@@ -40,7 +40,7 @@ buildscript {
         classpath "com.moowork.gradle:gradle-node-plugin:$gradle_node_version"
 
         // JMH plugins
-        classpath "com.github.jengelman.gradle.plugins:shadow:2.0.2"
+        classpath "com.github.jengelman.gradle.plugins:shadow:4.0.2"
         classpath "me.champeau.gradle:jmh-gradle-plugin:0.4.7"
         classpath "net.ltgt.gradle:gradle-apt-plugin:0.10"
     }

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

@@ -930,7 +930,10 @@ public open class JobSupport constructor(active: Boolean) : Job, ChildJob, Paren
 
     // for nicer debugging
     public override fun toString(): String =
-        "${nameString()}{${stateString(state)}}@$hexAddress"
+        "${toDebugString()}@$hexAddress"
+
+    @InternalCoroutinesApi
+    public fun toDebugString(): String = "${nameString()}{${stateString(state)}}"
 
     /**
      * @suppress **This is unstable API and it is subject to change.**

common/kotlinx-coroutines-core-common/src/internal/ProbesSupport.common.kt

@@ -0,0 +1,9 @@
+/*
+ * Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.internal
+
+import kotlin.coroutines.*
+
+internal expect inline fun <T> probeCoroutineCreated(completion: Continuation<T>): Continuation<T>

common/kotlinx-coroutines-core-common/src/intrinsics/Undispatched.kt

@@ -15,8 +15,8 @@ import kotlin.coroutines.intrinsics.*
  * It does not use [ContinuationInterceptor] and does not update context of the current thread.
  */
 internal fun <T> (suspend () -> T).startCoroutineUnintercepted(completion: Continuation<T>) {
-    startDirect(completion) {
-        startCoroutineUninterceptedOrReturn(completion)
+    startDirect(completion) { actualCompletion ->
+        startCoroutineUninterceptedOrReturn(actualCompletion)
     }
 }
 
@@ -26,8 +26,8 @@ internal fun <T> (suspend () -> T).startCoroutineUnintercepted(completion: Conti
  * It does not use [ContinuationInterceptor] and does not update context of the current thread.
  */
 internal fun <R, T> (suspend (R) -> T).startCoroutineUnintercepted(receiver: R, completion: Continuation<T>) {
-    startDirect(completion) {
-        startCoroutineUninterceptedOrReturn(receiver, completion)
+    startDirect(completion) {  actualCompletion ->
+        startCoroutineUninterceptedOrReturn(receiver, actualCompletion)
     }
 }
 
@@ -37,9 +37,9 @@ internal fun <R, T> (suspend (R) -> T).startCoroutineUnintercepted(receiver: R,
  * It does not use [ContinuationInterceptor], but updates the context of the current thread for the new coroutine.
  */
 internal fun <T> (suspend () -> T).startCoroutineUndispatched(completion: Continuation<T>) {
-    startDirect(completion) {
+    startDirect(completion) { actualCompletion ->
         withCoroutineContext(completion.context, null) {
-            startCoroutineUninterceptedOrReturn(completion)
+            startCoroutineUninterceptedOrReturn(actualCompletion)
         }
     }
 }
@@ -50,23 +50,29 @@ internal fun <T> (suspend () -> T).startCoroutineUndispatched(completion: Contin
  * It does not use [ContinuationInterceptor], but updates the context of the current thread for the new coroutine.
  */
 internal fun <R, T> (suspend (R) -> T).startCoroutineUndispatched(receiver: R, completion: Continuation<T>) {
-    startDirect(completion) {
+    startDirect(completion) { actualCompletion ->
         withCoroutineContext(completion.context, null) {
-            startCoroutineUninterceptedOrReturn(receiver, completion)
+            startCoroutineUninterceptedOrReturn(receiver, actualCompletion)
         }
     }
 }
 
-private inline fun <T> startDirect(completion: Continuation<T>, block: () -> Any?) {
+/**
+ * Starts given [block] immediately in the current stack-frame until first suspension point.
+ * This method supports debug probes and thus can intercept completion, thus completion is provide
+ * as the parameter of [block].
+ */
+private inline fun <T> startDirect(completion: Continuation<T>, block: (Continuation<T>) -> Any?) {
+    val actualCompletion = probeCoroutineCreated(completion)
     val value = try {
-        block()
+        block(actualCompletion)
     } catch (e: Throwable) {
-        completion.resumeWithException(e)
+        actualCompletion.resumeWithException(e)
         return
     }
     if (value !== COROUTINE_SUSPENDED) {
         @Suppress("UNCHECKED_CAST")
-        completion.resume(value as T)
+        actualCompletion.resume(value as T)
     }
 }
 

core/README.md

@@ -5,5 +5,5 @@ Module name below corresponds to the artifact name in Maven/Gradle.
 
 ## Modules
 
-* [kotlinx-coroutines-core](kotlinx-coroutines-core/README.md) -- core coroutine builders and synchronization primitives. 
-
+* [kotlinx-coroutines-core](kotlinx-coroutines-core/README.md) — core coroutine builders and synchronization primitives. 
+* [kotlinx-coroutines-debug](kotlinx-coroutines-debug/README.md) — coroutines debug utilities.