Debug improvements (#900)

Debug improvements

* Rename printHierarchy to printJob and hierarchyToString to jobToString, introduce corresponding methods for scope to simplify scopes debugging
* Remove CoroutineState.job in favor of CoroutineState.jobOrNull
* Use runCatching in Continuation.toDebugString to avoid crashes on some Androids with R8 issue

Addresses #858

Author: qwwdfsad

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

@@ -5,7 +5,6 @@ public final class kotlinx/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
@@ -19,10 +18,13 @@ public final class kotlinx/coroutines/debug/DebugProbes {
 	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 jobToString (Lkotlinx/coroutines/Job;)Ljava/lang/String;
+	public final fun printJob (Lkotlinx/coroutines/Job;Ljava/io/PrintStream;)V
+	public static synthetic fun printJob$default (Lkotlinx/coroutines/debug/DebugProbes;Lkotlinx/coroutines/Job;Ljava/io/PrintStream;ILjava/lang/Object;)V
+	public final fun printScope (Lkotlinx/coroutines/CoroutineScope;Ljava/io/PrintStream;)V
+	public static synthetic fun printScope$default (Lkotlinx/coroutines/debug/DebugProbes;Lkotlinx/coroutines/CoroutineScope;Ljava/io/PrintStream;ILjava/lang/Object;)V
+	public final fun scopeToString (Lkotlinx/coroutines/CoroutineScope;)Ljava/lang/String;
 	public final fun setSanitizeStackTraces (Z)V
 	public final fun uninstall ()V
 	public final fun withDebugProbes (Lkotlin/jvm/functions/Function0;)V

core/kotlinx-coroutines-core/src/Debug.kt

@@ -61,7 +61,8 @@ internal actual val Any.hexAddress: String
 
 internal actual fun Continuation<*>.toDebugString(): String = when (this) {
     is DispatchedContinuation -> toString()
-    else -> "$this@$hexAddress"
+    // Workaround for #858
+    else -> kotlin.runCatching { "$this@$hexAddress" }.getOrElse { "${this::class.java.name}@$hexAddress" }
 }
 
 internal actual val Any.classSimpleName: String get() = this::class.java.simpleName

core/kotlinx-coroutines-core/test/CancellableContinuationJvmTest.kt

@@ -16,7 +16,7 @@ class CancellableContinuationJvmTest : TestBase() {
     private suspend fun checkToString() {
         suspendCancellableCoroutine<Unit> {
             it.resume(Unit)
-            assertTrue(it.toString().contains("kotlinx/coroutines/CancellableContinuationJvmTest.checkToString(CancellableContinuationJvmTest.kt:16"))
+            assertTrue(it.toString().contains("kotlinx/coroutines/CancellableContinuationJvmTest.checkToString(CancellableContinuationJvmTest.kt"))
         }
     }
 }

core/kotlinx-coroutines-debug/README.md

@@ -11,7 +11,7 @@ Call to [DebugProbes.install] installs debug agent via ByteBuddy and starts to s
 After that, you can use [DebugProbes.dumpCoroutines] to print all active (suspended or running) coroutines, including their state, creation and
 suspension stacktraces.
 Additionally, it is possible to process the list of such coroutines via [DebugProbes.dumpCoroutinesState] or dump isolated parts
-of coroutines hierarchy referenced by a [Job] instance using [DebugProbes.printHierarchy].
+of coroutines hierarchy referenced by a [Job] instance using [DebugProbes.printScope] or [DebugProbes.printJob].
 
 ### Using as JVM agent
 
@@ -59,7 +59,7 @@ fun main(args: Array<String>) = runBlocking {
     DebugProbes.dumpCoroutines()
 
     println("\nDumping only deferred")
-    DebugProbes.printHierarchy(deferred)
+    DebugProbes.printJob(deferred)
 }
 ```
 
@@ -116,5 +116,6 @@ Do not use this module in production environment and do not rely on the format o
 [DebugProbes.install]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-debug/kotlinx.coroutines.debug/-debug-probes/install.html
 [DebugProbes.dumpCoroutines]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-debug/kotlinx.coroutines.debug/-debug-probes/dump-coroutines.html
 [DebugProbes.dumpCoroutinesState]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-debug/kotlinx.coroutines.debug/-debug-probes/dump-coroutines-state.html
-[DebugProbes.printHierarchy]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-debug/kotlinx.coroutines.debug/-debug-probes/print-hierarchy.html
+[DebugProbes.printScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-debug/kotlinx.coroutines.debug/-debug-probes/print-scope.html
+[DebugProbes.printJob]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-debug/kotlinx.coroutines.debug/-debug-probes/print-job.html
 <!--- END -->

core/kotlinx-coroutines-debug/src/CoroutineState.kt

@@ -21,20 +21,14 @@ public data class CoroutineState internal constructor(
     @JvmField internal val sequenceNumber: Long
 ) {
 
-    /**
-     * [Job] associated with a current coroutine or [IllegalStateException] otherwise.
-     * May be later used in [DebugProbes.printHierarchy]
-     */
-    public val job: Job get() = continuation.context[Job] ?: error("Continuation $continuation does not have a job")
-
     /**
      * [Job] associated with a current coroutine or null.
-     * May be later used in [DebugProbes.printHierarchy]
+     * May be later used in [DebugProbes.printJob].
      */
     public val jobOrNull: Job? get() = continuation.context[Job]
 
     /**
-     * Creation stacktrace of coroutine
+     * Creation stacktrace of the coroutine.
      */
     public val creationStackTrace: List<StackTraceElement> get() = creationStackTrace()
 
@@ -80,7 +74,7 @@ public data class CoroutineState internal constructor(
     /**
      * Last observed stacktrace of the coroutine captured on its suspension or resumption point.
      * It means that for [running][State.RUNNING] coroutines resulting stacktrace is inaccurate and
-     * reflects stacktrace of the resumption point, not the actual current stacktrace
+     * reflects stacktrace of the resumption point, not the actual current stacktrace.
      */
     public fun lastObservedStackTrace(): List<StackTraceElement> {
         var frame: CoroutineStackFrame? = lastObservedFrame ?: return emptyList()
@@ -99,15 +93,15 @@ public data class CoroutineState internal constructor(
  */
 public enum class State {
     /**
-     * Created, but not yet started
+     * Created, but not yet started.
      */
     CREATED,
     /**
-     * Started and running
+     * Started and running.
      */
     RUNNING,
     /**
-     * Suspended
+     * Suspended.
      */
     SUSPENDED
 }

core/kotlinx-coroutines-debug/src/DebugProbes.kt

@@ -72,14 +72,28 @@ public object DebugProbes {
      * Returns string representation of the coroutines [job] hierarchy with additional debug information.
      * Hierarchy is printed from the [job] as a root transitively to all children.
      */
-    public fun hierarchyToString(job: Job): String = DebugProbesImpl.hierarchyToString(job)
+    public fun jobToString(job: Job): String = DebugProbesImpl.hierarchyToString(job)
 
     /**
-     * Prints [job] hierarchy representation from [hierarchyToString] to the given [out].
+     * Returns string representation of all coroutines launched within the given [scope].
+     * Throws [IllegalStateException] if the scope has no a job in it.
      */
-    public fun printHierarchy(job: Job, out: PrintStream = System.out) =
+    public fun scopeToString(scope: CoroutineScope): String =
+        jobToString(scope.coroutineContext[Job] ?: error("Job is not present in the scope"))
+
+    /**
+     * Prints [job] hierarchy representation from [jobToString] to the given [out].
+     */
+    public fun printJob(job: Job, out: PrintStream = System.out): Unit =
         out.println(DebugProbesImpl.hierarchyToString(job))
 
+    /**
+     * Prints all coroutines launched within the given [scope].
+     * Throws [IllegalStateException] if the scope has no a job in it.
+     */
+    public fun printScope(scope: CoroutineScope, out: PrintStream = System.out): Unit =
+       printJob(scope.coroutineContext[Job] ?: error("Job is not present in the scope"), out)
+
     /**
      * Returns all existing coroutine states.
      * The resulting collection represents a consistent snapshot of all existing coroutines at the moment of invocation.

core/kotlinx-coroutines-debug/test/CoroutinesDumpTest.kt

@@ -50,7 +50,7 @@ class CoroutinesDumpTest : TestBase() {
                 "\tat kotlinx.coroutines.CoroutineStart.invoke(CoroutineStart.kt:99)\n")
 
         val found = DebugProbes.dumpCoroutinesState().single { it.jobOrNull === deferred }
-        assertSame(deferred, found.job)
+        assertSame(deferred, found.jobOrNull)
         runBlocking { deferred.cancelAndJoin() }
     }
 

core/kotlinx-coroutines-debug/test/HierarchyToStringTest.kt renamed to core/kotlinx-coroutines-debug/test/ToStringTest.kt

@@ -11,7 +11,7 @@ import org.junit.Test
 import kotlin.coroutines.*
 import kotlin.test.*
 
-class HierarchyToStringTest : TestBase() {
+class ToStringTest : TestBase() {
 
     @Before
     fun setUp() {
@@ -34,9 +34,9 @@ class HierarchyToStringTest : TestBase() {
         val tab = '\t'
         val expectedString = """
             "coroutine#2":StandaloneCoroutine{Completing}
-            $tab"foo#3":DeferredCoroutine{Active}, continuation is SUSPENDED at line HierarchyToStringTest${'$'}launchHierarchy${'$'}1${'$'}1.invokeSuspend(HierarchyToStringTest.kt:30)
-            $tab"coroutine#4":ActorCoroutine{Active}, continuation is SUSPENDED at line HierarchyToStringTest${'$'}launchHierarchy${'$'}1${'$'}2${'$'}1.invokeSuspend(HierarchyToStringTest.kt:40)
-            $tab$tab"coroutine#5":StandaloneCoroutine{Active}, continuation is SUSPENDED at line HierarchyToStringTest${'$'}launchHierarchy${'$'}1${'$'}2${'$'}job$1.invokeSuspend(HierarchyToStringTest.kt:37)
+            $tab"foo#3":DeferredCoroutine{Active}, continuation is SUSPENDED at line ToStringTest${'$'}launchHierarchy${'$'}1${'$'}1.invokeSuspend(ToStringTest.kt:30)
+            $tab"coroutine#4":ActorCoroutine{Active}, continuation is SUSPENDED at line ToStringTest${'$'}launchHierarchy${'$'}1${'$'}2${'$'}1.invokeSuspend(ToStringTest.kt:40)
+            $tab$tab"coroutine#5":StandaloneCoroutine{Active}, continuation is SUSPENDED at line ToStringTest${'$'}launchHierarchy${'$'}1${'$'}2${'$'}job$1.invokeSuspend(ToStringTest.kt:37)
             """.trimIndent()
 
         checkHierarchy(isCompleting = true, expectedString = expectedString)
@@ -46,22 +46,22 @@ class HierarchyToStringTest : TestBase() {
     fun testActiveHierarchy() = runBlocking {
         val tab = '\t'
         val expectedString = """
-            "coroutine#2":StandaloneCoroutine{Active}, continuation is SUSPENDED at line HierarchyToStringTest${'$'}launchHierarchy${'$'}1.invokeSuspend(HierarchyToStringTest.kt:94)
-            $tab"foo#3":DeferredCoroutine{Active}, continuation is SUSPENDED at line HierarchyToStringTest${'$'}launchHierarchy${'$'}1${'$'}1.invokeSuspend(HierarchyToStringTest.kt:30)
-            $tab"coroutine#4":ActorCoroutine{Active}, continuation is SUSPENDED at line HierarchyToStringTest${'$'}launchHierarchy${'$'}1${'$'}2${'$'}1.invokeSuspend(HierarchyToStringTest.kt:40)
-            $tab$tab"coroutine#5":StandaloneCoroutine{Active}, continuation is SUSPENDED at line HierarchyToStringTest${'$'}launchHierarchy${'$'}1${'$'}2${'$'}job$1.invokeSuspend(HierarchyToStringTest.kt:37)
+            "coroutine#2":StandaloneCoroutine{Active}, continuation is SUSPENDED at line ToStringTest${'$'}launchHierarchy${'$'}1.invokeSuspend(ToStringTest.kt:94)
+            $tab"foo#3":DeferredCoroutine{Active}, continuation is SUSPENDED at line ToStringTest${'$'}launchHierarchy${'$'}1${'$'}1.invokeSuspend(ToStringTest.kt:30)
+            $tab"coroutine#4":ActorCoroutine{Active}, continuation is SUSPENDED at line ToStringTest${'$'}launchHierarchy${'$'}1${'$'}2${'$'}1.invokeSuspend(ToStringTest.kt:40)
+            $tab$tab"coroutine#5":StandaloneCoroutine{Active}, continuation is SUSPENDED at line ToStringTest${'$'}launchHierarchy${'$'}1${'$'}2${'$'}job$1.invokeSuspend(ToStringTest.kt:37)
             """.trimIndent()
         checkHierarchy(isCompleting = false, expectedString = expectedString)
     }
 
     private suspend fun CoroutineScope.checkHierarchy(isCompleting: Boolean, expectedString: String) {
         val root = launchHierarchy(isCompleting)
         repeat(4) { yield() }
+        val expected = expectedString.trimStackTrace().trimPackage()
         expect(6)
-        assertEquals(
-            expectedString.trimStackTrace().trimPackage(),
-            DebugProbes.hierarchyToString(root).trimEnd().trimStackTrace().trimPackage()
-        )
+        assertEquals(expected, DebugProbes.jobToString(root).trimEnd().trimStackTrace().trimPackage())
+        assertEquals(expected, DebugProbes.scopeToString(CoroutineScope(root)).trimEnd().trimStackTrace().trimPackage())
+
         root.cancel()
         root.join()
         finish(7)