Remove convergence loop from DominatorTree; point to LinkEvalDominatorTree

The convergence loop was shown to be ~40x too slow for production use.
Now that LinkEvalDominatorTree provides an exact solution, strip the
convergence loop machinery from DominatorTree:

- Remove collectCrossEdges constructor param, crossEdges field,
  runConvergenceLoop(), and pruneSettledCrossEdges()
- Delete LongPairList (no longer used anywhere)
- Delete ConvergenceLoopBenchmark and RealHeapEdgeCountTest
- Remove convergence loop tests from DominatorTreeTest
- Update class-level and updateDominated KDoc to document the
  approximation bug and point to LinkEvalDominatorTree as the fix
- Regenerate API dump

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: pyricau

dominator_tree.md

@@ -138,14 +138,12 @@ public final class shark/ClassReferenceReader : shark/ReferenceReader {
 
 public final class shark/DominatorTree {
 	public fun <init> ()V
-	public fun <init> (IZ)V
-	public synthetic fun <init> (IZILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public fun <init> (I)V
+	public synthetic fun <init> (IILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public final fun buildFullDominatorTree (Lshark/DominatorTree$ObjectSizeCalculator;)Ljava/util/Map;
 	public final fun computeRetainedSizes (Landroidx/collection/LongSet;Lshark/DominatorTree$ObjectSizeCalculator;)Landroidx/collection/LongLongMap;
 	public final fun contains (J)Z
 	public final fun get (J)J
-	public final fun runConvergenceLoop (I)I
-	public static synthetic fun runConvergenceLoop$default (Lshark/DominatorTree;IILjava/lang/Object;)I
 	public final fun updateDominated (JJ)Z
 	public final fun updateDominatedAsRoot (J)Z
 }

dominators_plan.md

@@ -10,7 +10,6 @@ import shark.ObjectDominators.DominatorNode
 import shark.internal.hppc.LongLongScatterMap
 import shark.internal.hppc.LongLongScatterMap.ForEachCallback
 import shark.internal.hppc.LongScatterSet
-import shark.internal.LongPairList
 import shark.internal.packedWith
 import shark.internal.unpackAsFirstInt
 import shark.internal.unpackAsSecondInt
@@ -20,32 +19,19 @@ import shark.internal.unpackAsSecondInt
  * Lowest Common Ancestor (LCA) approach to update immediate dominators as new parents are
  * discovered.
  *
- * **Known limitation**: this is an approximation, not an exact dominator algorithm (compare
- * with Lengauer-Tarjan or Cooper et al.'s iterative algorithm). It can produce incorrect
- * immediate dominators when a cross-edge (to an already-visited node) is processed using a
- * stale parent dominator, and that parent's dominator is later raised by another cross-edge
- * after the first cross-edge's children have already been settled. The child's dominator is then
- * left too specific (too far from root), so its retained size is under-attributed — some
- * objects that it truly retains exclusively are instead attributed to a higher ancestor. See
- * [updateDominated] for a concrete example and [DominatorTreeTest] for a test documenting this
- * behavior.
+ * **Known limitation**: this is an approximation, not an exact dominator algorithm. It can
+ * produce incorrect immediate dominators when a cross-edge (to an already-visited node) is
+ * processed using a stale parent dominator, and that parent's dominator is later raised by
+ * another cross-edge after the first cross-edge's children have already been settled. The child's
+ * dominator is then left too specific (too far from root), so its retained size is
+ * under-attributed — some objects that it truly retains exclusively are instead attributed to a
+ * higher ancestor. See [updateDominated] for a concrete example and [DominatorTreeTest] for a
+ * test documenting this behavior.
  *
- * **Fix**: pass `collectCrossEdges = true` to the constructor, then call [runConvergenceLoop]
- * after the BFS traversal completes and before calling [computeRetainedSizes] or
- * [buildFullDominatorTree]. The convergence loop re-processes stored cross-edges with updated
- * dominator values until the tree stabilizes.
- *
- * **Performance warning**: [runConvergenceLoop] is an O(cross-edges × depth × iterations)
- * algorithm. On real Android heap dumps the iteration count scales with the longest chain of
- * stale-dominator propagation, which can reach hundreds of iterations. Benchmarks on a 25 MB
- * heap dump show ~107 K cross-edges requiring ~780 iterations, adding ~62 seconds on top of a
- * 1.5-second analysis — roughly 40× slower. The loop is therefore **not suitable for production
- * use** in its current form and is provided only as an opt-in diagnostic / correctness-testing
- * tool.
+ * For an exact dominator tree, use [LinkEvalDominatorTree] instead.
  */
 class DominatorTree(
-  expectedElements: Int = 4,
-  collectCrossEdges: Boolean = false
+  expectedElements: Int = 4
 ) {
 
   fun interface ObjectSizeCalculator {
@@ -60,12 +46,6 @@ class DominatorTree(
    */
   private val dominated = LongLongScatterMap(expectedElements)
 
-  /**
-   * Stores cross-edges discovered during BFS, for use by [runConvergenceLoop].
-   * Only populated when `collectCrossEdges = true`.
-   */
-  private val crossEdges: LongPairList? = if (collectCrossEdges) LongPairList() else null
-
   operator fun contains(objectId: Long): Boolean = dominated.containsKey(objectId)
 
   /**
@@ -110,8 +90,7 @@ class DominatorTree(
    * The consequence is that dom(C) is left too specific (too far from root), so C's retained
    * size is incorrectly attributed to A instead of root. A's retained size is over-reported.
    *
-   * To fix this, construct with `collectCrossEdges = true` and call [runConvergenceLoop] after
-   * the full BFS traversal and before [computeRetainedSizes] or [buildFullDominatorTree].
+   * For an exact dominator tree that avoids this issue entirely, use [LinkEvalDominatorTree].
    *
    * @return true if [objectId] already had a known dominator, false otherwise.
    */
@@ -128,17 +107,6 @@ class DominatorTree(
     } else {
       val currentDominator = dominated.getSlotValue(dominatedSlot)
       if (currentDominator != ValueHolder.NULL_REFERENCE) {
-        // Only record this cross-edge if both dom(objectId) and dom(parentObjectId) are
-        // non-null. If either is already NULL_REFERENCE the convergence loop would always
-        // produce a no-op: a NULL_REFERENCE currentDominator can't be raised further, and a
-        // NULL_REFERENCE parent dominator means the LCA walk terminates in one step at the
-        // same value already set by this call.
-        if (crossEdges != null) {
-          val parentSlot = dominated.getSlot(parentObjectId)
-          if (parentSlot != -1 && dominated.getSlotValue(parentSlot) != ValueHolder.NULL_REFERENCE) {
-            crossEdges.add(objectId, parentObjectId)
-          }
-        }
         // We're looking for the Lowest Common Dominator between currentDominator and
         // parentObjectId. We know that currentDominator likely has a shorter dominator path than
         // parentObjectId since we're exploring the graph with a breadth first search. So we build
@@ -179,87 +147,6 @@ class DominatorTree(
     return hasDominator
   }
 
-  /**
-   * Re-processes stored cross-edges until the dominator tree stabilizes or [maxIterations] is
-   * reached. Must be called after the BFS traversal is complete and before calling
-   * [computeRetainedSizes] or [buildFullDominatorTree].
-   *
-   * This fixes cases where a cross-edge `P→C` was processed using a stale `dom(P)` value.
-   * When `dom(P)` is later raised by another cross-edge, `dom(C)` is not automatically updated.
-   * The convergence loop re-runs the LCA computation for each stored cross-edge until no
-   * further changes occur, propagating all such corrections.
-   *
-   * Requires `collectCrossEdges = true` to have been passed to the constructor; throws
-   * [IllegalStateException] otherwise.
-   *
-   * @param maxIterations maximum number of passes over the cross-edge set. Pass [Int.MAX_VALUE]
-   *   to run until fully stable. **Warning**: real heap graphs can require hundreds of iterations;
-   *   see the class-level KDoc for performance implications.
-   * @return the number of iterations performed.
-   */
-  fun runConvergenceLoop(maxIterations: Int = Int.MAX_VALUE): Int {
-    val edges = crossEdges
-      ?: error("Cross-edge collection not enabled. Construct DominatorTree with collectCrossEdges = true.")
-
-    var iterations = 0
-    var changed = true
-    while (changed && iterations < maxIterations) {
-      // Prune settled edges before each pass so we iterate fewer entries. This also covers
-      // edges already settled after the BFS traversal (when the LCA inside updateDominated
-      // set dom(objectId) to NULL_REFERENCE after the edge was recorded).
-      pruneSettledCrossEdges(edges)
-      changed = false
-      iterations++
-      edges.forEach { objectId, parentObjectId ->
-        val dominatedSlot = dominated.getSlot(objectId)
-        if (dominatedSlot == -1) return@forEach
-        val currentDominator = dominated.getSlotValue(dominatedSlot)
-        // If already attributed to the virtual root, it cannot be raised further.
-        if (currentDominator == ValueHolder.NULL_REFERENCE) return@forEach
-        // LCA computation: same approach as updateDominated.
-        val currentDominators = LongScatterSet()
-        var dominator = currentDominator
-        while (dominator != ValueHolder.NULL_REFERENCE) {
-          currentDominators.add(dominator)
-          val nextSlot = dominated.getSlot(dominator)
-          if (nextSlot == -1) {
-            throw IllegalStateException(
-              "Did not find dominator for $dominator when going through the dominator chain for $currentDominator: $currentDominators"
-            )
-          } else {
-            dominator = dominated.getSlotValue(nextSlot)
-          }
-        }
-        dominator = parentObjectId
-        while (dominator != ValueHolder.NULL_REFERENCE) {
-          if (dominator in currentDominators) break
-          val nextSlot = dominated.getSlot(dominator)
-          if (nextSlot == -1) {
-            throw IllegalStateException(
-              "Did not find dominator for $dominator when going through the dominator chain for $parentObjectId"
-            )
-          } else {
-            dominator = dominated.getSlotValue(nextSlot)
-          }
-        }
-        if (dominator != currentDominator) {
-          dominated[objectId] = dominator
-          changed = true
-        }
-      }
-    }
-    return iterations
-  }
-
-  private fun pruneSettledCrossEdges(edges: LongPairList) {
-    edges.forEachIndexed { index, objectId, _ ->
-      val slot = dominated.getSlot(objectId)
-      if (slot == -1 || dominated.getSlotValue(slot) == ValueHolder.NULL_REFERENCE) {
-        edges.clearAt(index)
-      }
-    }
-  }
-
   private class MutableDominatorNode {
     var shallowSize = 0
     var retainedSize = 0