Formalize the internal IDEA dependencies for binary compatibility

Author: dkhalanskyjb

kotlinx-coroutines-core/api/kotlinx-coroutines-core.api

@@ -888,6 +888,16 @@ public final class kotlinx/coroutines/debug/internal/DebugCoroutineInfo {
 	public final fun lastObservedStackTrace ()Ljava/util/List;
 }
 
+public final class kotlinx/coroutines/debug/internal/DebugProbesImpl {
+	public static final field INSTANCE Lkotlinx/coroutines/debug/internal/DebugProbesImpl;
+	public final fun dumpCoroutinesInfo ()Ljava/util/List;
+	public final fun dumpCoroutinesInfoAsJsonAndReferences ()[Ljava/lang/Object;
+	public final fun dumpDebuggerInfo ()Ljava/util/List;
+	public final fun enhanceStackTraceWithThreadDump (Lkotlinx/coroutines/debug/internal/DebugCoroutineInfo;Ljava/util/List;)Ljava/util/List;
+	public final fun enhanceStackTraceWithThreadDumpAsJson (Lkotlinx/coroutines/debug/internal/DebugCoroutineInfo;)Ljava/lang/String;
+	public final fun isInstalled ()Z
+}
+
 public final class kotlinx/coroutines/debug/internal/DebuggerInfo : java/io/Serializable {
 	public fun <init> (Lkotlinx/coroutines/debug/internal/DebugCoroutineInfoImpl;Lkotlin/coroutines/CoroutineContext;)V
 	public final fun getCoroutineId ()Ljava/lang/Long;

kotlinx-coroutines-core/jvm/src/debug/internal/DebugProbesImpl.kt

@@ -18,6 +18,7 @@ import kotlin.coroutines.jvm.internal.CoroutineStackFrame
 import kotlin.synchronized
 import _COROUTINE.ArtificialStackFrames
 
+@PublishedApi
 internal object DebugProbesImpl {
     private val ARTIFICIAL_FRAME = ArtificialStackFrames().coroutineCreation()
     private val dateFormat = SimpleDateFormat("yyyy/MM/dd HH:mm:ss")
@@ -31,16 +32,16 @@ internal object DebugProbesImpl {
     private val installations = atomic(0)
 
     /**
-     * This internal method is used by IDEA debugger under the JVM name of
+     * This internal method is used by the IDEA debugger under the JVM name
      * "isInstalled$kotlinx_coroutines_debug".
      */
-    internal val isInstalled: Boolean get() = installations.value > 0
+    val isInstalled: Boolean get() = installations.value > 0
 
-    // To sort coroutines by creation order, used as unique id
+    // To sort coroutines by creation order, used as a unique id
     private val sequenceNumber = atomic(0L)
 
-    public var sanitizeStackTraces: Boolean = true
-    public var enableCreationStackTraces: Boolean = true
+    internal var sanitizeStackTraces: Boolean = true
+    internal var enableCreationStackTraces: Boolean = true
 
     /*
      * Substitute for service loader, DI between core and debug modules.
@@ -55,27 +56,28 @@ internal object DebugProbesImpl {
         ctor.newInstance() as Function1<Boolean, Unit>
     }.getOrNull()
 
-    /*
-     * This is an optimization in the face of KT-29997:
-     * Consider suspending call stack a()->b()->c() and c() completes its execution and every call is
+    /**
+     * Because `probeCoroutinesResumed` is called for every resumed continuation (see KT-29997 and the related code),
+     * we perform a performance optimization:
+     * Imagine a suspending call stack a()->b()->c(), where c() completes its execution and every call is
      * "almost" in tail position.
      *
-     * Then at least three RUNNING -> RUNNING transitions will occur consecutively and complexity of each is O(depth).
-     * To avoid that quadratic complexity, we are caching lookup result for such chains in this map and update it incrementally.
+     * Then at least three RUNNING -> RUNNING transitions will occur consecutively, the complexity of each O(depth).
+     * To avoid this quadratic complexity, we are caching lookup result for such chains in this map and update it incrementally.
      *
      * [DebugCoroutineInfoImpl] keeps a lot of auxiliary information about a coroutine, so we use a weak reference queue
      * to promptly release the corresponding memory when the reference to the coroutine itself was already collected.
      */
     private val callerInfoCache = ConcurrentWeakMap<CoroutineStackFrame, DebugCoroutineInfoImpl>(weakRefQueue = true)
 
-    fun install() {
+    internal fun install() {
         if (installations.incrementAndGet() > 1) return
         startWeakRefCleanerThread()
         if (AgentInstallationType.isInstalledStatically) return
         dynamicAttach?.invoke(true) // attach
     }
 
-    fun uninstall() {
+    internal fun uninstall() {
         check(isInstalled) { "Agent was not installed" }
         if (installations.decrementAndGet() != 0) return
         stopWeakRefCleanerThread()
@@ -98,7 +100,7 @@ internal object DebugProbesImpl {
         thread.join()
     }
 
-    fun hierarchyToString(job: Job): String {
+    internal fun hierarchyToString(job: Job): String {
         check(isInstalled) { "Debug probes are not installed" }
         val jobToStack = capturedCoroutines
             .filter { it.delegate.context[Job] != null }
@@ -174,7 +176,7 @@ internal object DebugProbesImpl {
      * Internal (JVM-public) method used by IDEA debugger as of 1.6.0-RC.
      */
     @OptIn(ExperimentalStdlibApi::class)
-    public fun dumpCoroutinesInfoAsJsonAndReferences(): Array<Any> {
+    fun dumpCoroutinesInfoAsJsonAndReferences(): Array<Any> {
         val coroutinesInfo = dumpCoroutinesInfo()
         val size = coroutinesInfo.size
         val lastObservedThreads = ArrayList<Thread?>(size)
@@ -210,7 +212,7 @@ internal object DebugProbesImpl {
     /*
      * Internal (JVM-public) method used by IDEA debugger as of 1.6.0-RC.
      */
-    public fun enhanceStackTraceWithThreadDumpAsJson(info: DebugCoroutineInfo): String {
+    fun enhanceStackTraceWithThreadDumpAsJson(info: DebugCoroutineInfo): String {
         val stackTraceElements = enhanceStackTraceWithThreadDump(info, info.lastObservedStackTrace)
         val stackTraceElementsInfoAsJson = mutableListOf<String>()
         for (element in stackTraceElements) {
@@ -234,17 +236,17 @@ internal object DebugProbesImpl {
     /*
      * Internal (JVM-public) method used by IDEA debugger as of 1.4-M3.
      */
-    public fun dumpCoroutinesInfo(): List<DebugCoroutineInfo> =
+    fun dumpCoroutinesInfo(): List<DebugCoroutineInfo> =
         dumpCoroutinesInfoImpl { owner, context -> DebugCoroutineInfo(owner.info, context) }
 
     /*
      * Internal (JVM-public) method to be used by IDEA debugger in the future (not used as of 1.4-M3).
      * It is equivalent to [dumpCoroutinesInfo], but returns serializable (and thus less typed) objects.
      */
-    public fun dumpDebuggerInfo(): List<DebuggerInfo> =
+    fun dumpDebuggerInfo(): List<DebuggerInfo> =
         dumpCoroutinesInfoImpl { owner, context -> DebuggerInfo(owner.info, context) }
 
-    public fun dumpCoroutines(out: PrintStream): Unit = synchronized(out) {
+    internal fun dumpCoroutines(out: PrintStream): Unit = synchronized(out) {
         /*
          * This method synchronizes both on `out` and `this` for a reason:
          * 1) Taking a write lock is required to have a consistent snapshot of coroutines.
@@ -306,7 +308,7 @@ internal object DebugProbesImpl {
      * It is similar to [enhanceStackTraceWithThreadDumpImpl], but uses debugger-facing [DebugCoroutineInfo] type.
      */
     @Suppress("unused")
-    public fun enhanceStackTraceWithThreadDump(
+    fun enhanceStackTraceWithThreadDump(
         info: DebugCoroutineInfo,
         coroutineTrace: List<StackTraceElement>
     ): List<StackTraceElement> =