Support 'ExternalStaticDebugProbes' (in collaboration with the kotlin-stdlib)

Author: sellmair

Diff for: integration-testing/README.md

@@ -8,6 +8,7 @@ The tests are the following:
 * `coreAgentTest` checks that `kotlinx-coroutines-core` can be run as a Java agent.
 * `debugAgentTest` checks that the coroutine debugger can be run as a Java agent.
 * `debugDynamicAgentTest` checks that `kotlinx-coroutines-debug` agent can self-attach dynamically to JVM as a standalone dependency.
+* `externalStaticDebugProbesTest` checks that a `ExternalStaticDebugProbes` is picked up by the kotlin stdlib
 * `smokeTest` builds the multiplatform test project that depends on coroutines.
 
 The `integration-testing` project is expected to be in a subdirectory of the main `kotlinx.coroutines` project.

Diff for: integration-testing/build.gradle

@@ -1,3 +1,6 @@
+import org.jetbrains.kotlin.gradle.plugin.KotlinPluginWrapperKt
+import org.jetbrains.kotlin.tooling.core.KotlinToolingVersionKt
+
 buildscript {
 
     /*
@@ -158,6 +161,17 @@ sourceSets {
     tasks.compileDebugDynamicAgentJpmsTestJava.configure {
         options.release.set(17)
     }
+
+    externalStaticDebugProbesTest {
+        kotlin
+        compileClasspath += sourceSets.test.runtimeClasspath
+        runtimeClasspath += sourceSets.test.runtimeClasspath
+
+        dependencies {
+            implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:$coroutines_version"
+            implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+        }
+    }
 }
 
 compileDebugAgentTestKotlin {
@@ -209,12 +223,19 @@ task coreAgentTest(type: Test) {
     classpath = sourceSet.runtimeClasspath
 }
 
+task externalStaticDebugProbesTest(type: Test) {
+    enabled = KotlinPluginWrapperKt.getKotlinToolingVersion(project) >= KotlinToolingVersionKt.KotlinToolingVersion("2.1.255-SNAPSHOT")
+    def sourceSet = sourceSets.externalStaticDebugProbesTest
+    testClassesDirs = sourceSet.output.classesDirs
+    classpath = sourceSet.runtimeClasspath
+}
+
 compileTestKotlin {
     kotlinOptions.jvmTarget = "1.8"
 }
 
 check {
-    dependsOn([jvmCoreTest, debugDynamicAgentTest, mavenTest, debugAgentTest, coreAgentTest, debugDynamicAgentJpmsTest, 'smokeTest:build'])
+    dependsOn([jvmCoreTest, debugDynamicAgentTest, mavenTest, debugAgentTest, coreAgentTest, debugDynamicAgentJpmsTest, externalStaticDebugProbesTest, 'smokeTest:build'])
 }
 compileKotlin {
     kotlinOptions {

Diff for: integration-testing/src/externalStaticDebugProbesTest/kotlin/ExternalStaticDebugProbes.kt

@@ -0,0 +1,10 @@
+package kotlinx.coroutines.external
+
+import kotlinx.coroutines.debug.internal.AbstractStaticDebugProbes
+import kotlin.coroutines.*
+
+object ExternalStaticDebugProbes: AbstractStaticDebugProbes() {
+    override fun <T> probeCoroutineCreated(completion: Continuation<T>): Continuation<T> {
+        return super.probeCoroutineCreated(completion)
+    }
+}

Diff for: integration-testing/src/externalStaticDebugProbesTest/kotlin/ExternalStaticDebugProbesTest.kt

@@ -0,0 +1,21 @@
+import org.junit.*
+import kotlinx.coroutines.*
+import kotlinx.coroutines.external.ExternalStaticDebugProbes
+import org.junit.Test
+import java.io.*
+
+class ExternalStaticDebugProbesTest {
+
+    @Test
+    fun testDumpCoroutines() {
+        println("Hello")
+        runBlocking {
+            val baos = ByteArrayOutputStream()
+            ExternalStaticDebugProbes.dumpCoroutines(PrintStream(baos))
+            // if the agent works, then dumps should contain something,
+            // at least the fact that this test is running.
+            val dump = baos.toString()
+            Assert.assertTrue(dump, dump.contains("testDumpCoroutines"))
+        }
+    }
+}

Diff for: kotlinx-coroutines-core/api/kotlinx-coroutines-core.api

@@ -911,6 +911,14 @@ public final class kotlinx/coroutines/channels/TickerMode : java/lang/Enum {
 	public static fun values ()[Lkotlinx/coroutines/channels/TickerMode;
 }
 
+public abstract class kotlinx/coroutines/debug/internal/AbstractStaticDebugProbes {
+	public fun <init> ()V
+	public final fun dumpCoroutines (Ljava/io/PrintStream;)V
+	public fun probeCoroutineCreated (Lkotlin/coroutines/Continuation;)Lkotlin/coroutines/Continuation;
+	public fun probeCoroutineResumed (Lkotlin/coroutines/Continuation;)V
+	public fun probeCoroutineSuspended (Lkotlin/coroutines/Continuation;)V
+}
+
 public final class kotlinx/coroutines/debug/internal/DebugCoroutineInfo {
 	public final fun getContext ()Lkotlin/coroutines/CoroutineContext;
 	public final fun getCreationStackTrace ()Ljava/util/List;

Diff for: kotlinx-coroutines-core/jvm/src/debug/internal/AbstractStaticDebugProbes.kt

@@ -0,0 +1,59 @@
+package kotlinx.coroutines.debug.internal
+
+import kotlinx.coroutines.*
+import java.io.*
+import kotlin.coroutines.*
+
+/**
+ * Allows to statically install 'Debug Probes' at the known location
+ * (kotlinx.coroutines.external.ExternalStaticDebugProbes).
+ *
+ * **Discussion**
+ *
+ * There are three methods of installing/engaging coroutines 'Debug Probes'
+ *
+ * 1) Dynamic Attach (using the 'kotlinx-coroutines-debug' module)
+ *  This uses runtime byte-code alteration to replace the 'Debug Probes' straight from the kotlin-stdlib
+ *
+ * 2) Static Attach using an Agent
+ *  This uses a java agent to replace the 'Debug Probes' from the kotlin-stdlib statically
+ *
+ * 3) ExternalStaticDebugProbes
+ *  The kotlin-stdlib compiled against a class at
+ *  `kotlinx.coroutines.external.ExternalStaticDebugProbes` which is not available at runtime, by default.
+ *  If a class at this location is present, then the kotlin-stdlib will call into it.
+ *
+ *  ```kotlin
+ *  package kotlinx.coroutines.external
+ *  object ExternalStaticDebugProbes: AbstractStaticDebugProbes() {
+ *      override fun <T> probeCoroutineCreated(completion: Continuation<T>): Continuation<T> {
+ *          // intercept
+ *          // ...
+ *
+ *          // forward to debugger machinery
+ *          return super.probeCoroutineCreated(completion)
+ *      }
+ *  }
+ *  ```
+ */
+@Suppress("unused")
+@DelicateCoroutinesApi
+@ExperimentalCoroutinesApi
+abstract class AbstractStaticDebugProbes {
+    init {
+        require(javaClass.name == "kotlinx.coroutines.external.ExternalStaticDebugProbes")
+        AgentInstallationType.isInstalledStatically = true
+        DebugProbesImpl.install()
+    }
+
+    open fun probeCoroutineResumed(frame: Continuation<*>) = DebugProbesImpl.probeCoroutineResumed(frame)
+
+    open fun probeCoroutineSuspended(frame: Continuation<*>) = DebugProbesImpl.probeCoroutineSuspended(frame)
+
+    open fun <T> probeCoroutineCreated(completion: Continuation<T>): Continuation<T> =
+        DebugProbesImpl.probeCoroutineCreated(completion)
+
+    fun dumpCoroutines(out: PrintStream) {
+        DebugProbesImpl.dumpCoroutines(out)
+    }
+}