[cDAC] Reshape DacDbi API GetHeapSegments to EnumerateHeapSegments and implement in cDAC (#128054)

Existing native GetHeapSegments allocates - to avoid this, I reworked it
into EnumerateHeapSegments which calls a callback on each segment to add
it to a DacDbiArray structure (potentially allocating). There are a
bunch of APIs like this.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: rcj1 <77995559+rcj1@users.noreply.github.com>
Co-authored-by: rcj1 <rachel.jarvi@gmail.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: 3 people

docs/design/datacontracts/GC.md

@@ -125,6 +125,11 @@ public readonly struct GCOomData
     IReadOnlyList<GCMemoryRegionData> GetGCBookkeepingMemoryRegions();
     // Gets GC free regions (free region lists and freeable segments)
     IReadOnlyList<GCMemoryRegionData> GetGCFreeRegions();
+
+    // Enumerates every GC heap segment for the supplied heap data. Each yielded GCHeapSegmentInfo
+    // describes a single segment with the inclusive start and exclusive end of its memory range
+    // and its generation tag (or Ephemeral).
+    IEnumerable<GCHeapSegmentInfo> EnumerateHeapSegments(GCHeapData heapData);
 ```
 
 ```csharp
@@ -145,6 +150,26 @@ public readonly struct GCMemoryRegionData
     public ulong ExtraData { get; init; }
     public int Heap { get; init; }
 }
+
+public enum GCSegmentClassification
+{
+    Unknown,
+    Gen0,
+    Gen1,
+    Gen2,
+    LOH,
+    POH,
+    NonGC,
+    // Segments-GC only: marker used by IGC.EnumerateHeapSegments to denote the ephemeral
+    // segment on the gen2 list. The caller is responsible for splitting it into the Gen1
+    // piece and an optional Gen2 prefix.
+    Ephemeral,
+}
+
+public readonly record struct GCHeapSegmentInfo(
+    TargetPointer Start,
+    TargetPointer End,
+    GCSegmentClassification Generation);
 ```
 
 ## Version 1
@@ -286,6 +311,7 @@ Constants used:
 | Name | Type | Purpose | Value |
 | --- | --- | --- | --- |
 | `WRK_HEAP_COUNT` | uint | The number of heaps in the `workstation` GC type | `1` |
+| `HEAP_SEGMENT_FLAGS_READONLY` | ulong | `HeapSegment.Flags` bit identifying a readonly (e.g. frozen, non-GC) segment. | `1` |
 
 ```csharp
 GCHeapType IGC.GetGCIdentifiers()
@@ -858,7 +884,7 @@ IReadOnlyList<GCMemoryRegionData> IGC.GetHandleTableMemoryRegions()
     // Safety caps matching native DAC
     const int MaxHandleTableRegions = 8192;
     const int MaxBookkeepingRegions = 32;
-    const int MaxSegmentListIterations = 2048;
+    const int MaxSegmentListIterations = 65536;
 
     int maxRegions = MaxHandleTableRegions;
     TargetPointer handleTableMap = target.ReadGlobalPointer("HandleTableMap");
@@ -1027,3 +1053,79 @@ TargetNUInt IGC.GetHandleExtraInfo(TargetPointer handle)
     return target.ReadNUInt(extraInfoAddr);
 }
 ```
+
+EnumerateHeapSegments
+
+Returns the raw GC heap segments for a single heap by walking the per-generation segment
+lists.
+```csharp
+IEnumerable<GCHeapSegmentInfo> IGC.EnumerateHeapSegments(GCHeapData heapData)
+{
+    // The generation table is laid out as gen0, gen1, gen2, LOH, POH (plus optional extras).
+    var gens = heapData.GenerationTable;
+    bool regions = GetGCIdentifiers().Contains("regions");
+
+    TargetPointer ephemeralSegment = heapData.EphemeralHeapSegment;
+    TargetPointer allocAllocated   = heapData.AllocAllocated;
+
+    if (regions)
+    {
+        // In regions mode each generation has its own segment list. Readonly entries on
+        // the gen2 list represent non-GC (e.g. frozen) regions and are reported as NonGC.
+        foreach (var (seg, _) in WalkSegmentList(gens[2].StartSegment))
+        {
+            var type = (seg.Flags & HEAP_SEGMENT_FLAGS_READONLY) != 0
+                ? GCSegmentClassification.NonGC
+                : GCSegmentClassification.Gen2;
+            yield return new GCHeapSegmentInfo(seg.Mem, seg.Allocated, type);
+        }
+        foreach (var (seg, _) in WalkSegmentList(gens[1].StartSegment))
+            yield return new GCHeapSegmentInfo(seg.Mem, seg.Allocated, GCSegmentClassification.Gen1);
+        foreach (var (seg, segAddr) in WalkSegmentList(gens[0].StartSegment))
+        {
+            // For the gen0 segment that matches the ephemeral_heap_segment, end is alloc_allocated.
+            TargetPointer end = segAddr == ephemeralSegment ? allocAllocated : seg.Allocated;
+            yield return new GCHeapSegmentInfo(seg.Mem, end, GCSegmentClassification.Gen0);
+        }
+    }
+    else
+    {
+        // In segments mode the gen2 list contains every SOH segment. The ephemeral
+        // segment is tagged Ephemeral as the layer-2 split marker; non-ephemeral entries
+        // are reported with their true generation (Gen2 or NonGC for readonly).
+        foreach (var (seg, segAddr) in WalkSegmentList(gens[2].StartSegment))
+        {
+            GCSegmentClassification type;
+            if (segAddr == ephemeralSegment)
+                type = GCSegmentClassification.Ephemeral;
+            else if ((seg.Flags & HEAP_SEGMENT_FLAGS_READONLY) != 0)
+                type = GCSegmentClassification.NonGC;
+            else
+                type = GCSegmentClassification.Gen2;
+            TargetPointer end = segAddr == ephemeralSegment ? allocAllocated : seg.Allocated;
+            yield return new GCHeapSegmentInfo(seg.Mem, end, type);
+        }
+    }
+
+    // LOH and POH segments are always reported as-is regardless of GC mode.
+    foreach (var (seg, _) in WalkSegmentList(gens[3].StartSegment))
+        yield return new GCHeapSegmentInfo(seg.Mem, seg.Allocated, GCSegmentClassification.LOH);
+    foreach (var (seg, _) in WalkSegmentList(gens[4].StartSegment))
+        yield return new GCHeapSegmentInfo(seg.Mem, seg.Allocated, GCSegmentClassification.POH);
+}
+
+IEnumerable<(HeapSegment Segment, TargetPointer Address)> WalkSegmentList(TargetPointer startSegment)
+{
+    // Bounded traversal of the singly-linked HeapSegment list, guarding against cycles or
+    // corrupt links via a fixed iteration cap (MaxSegmentListIterations = 65536).
+    int iterationMax = MaxSegmentListIterations;
+    TargetPointer current = startSegment;
+    while (current != TargetPointer.Null)
+    {
+        HeapSegment seg = /* read HeapSegment at current */;
+        yield return (seg, current);
+        current = seg.Next;
+        if (iterationMax-- <= 0) throw /* cycle detected */;
+    }
+}
+```

src/coreclr/debug/daccess/daccess.cpp

@@ -7976,7 +7976,7 @@ void DacFreeRegionEnumerator::AddSingleSegment(const dac_heap_segment &curr, Fre
 
 void DacFreeRegionEnumerator::AddSegmentList(DPTR(dac_heap_segment) start, FreeRegionKind kind, int heap)
 {
-    int iterationMax = 2048;
+    int iterationMax = 65536;
 
     DPTR(dac_heap_segment) curr = start;
     while (curr != nullptr)

src/coreclr/debug/daccess/dacdbiimpl.cpp

@@ -6875,10 +6875,14 @@ HRESULT STDMETHODCALLTYPE DacDbiInterfaceImpl::WalkHeap(HeapWalkHandle handle,
 
 
 
-HRESULT STDMETHODCALLTYPE DacDbiInterfaceImpl::GetHeapSegments(OUT DacDbiArrayList<COR_SEGMENT> *pSegments)
+HRESULT STDMETHODCALLTYPE DacDbiInterfaceImpl::EnumerateHeapSegments(
+    FP_HEAPSEGMENT_CALLBACK fpCallback,
+    CALLBACK_DATA pUserData)
 {
     DD_ENTER_MAY_THROW;
 
+    if (fpCallback == NULL)
+        return E_POINTER;
 
     size_t heapCount = 0;
     HeapData *heaps = 0;
@@ -6893,53 +6897,28 @@ HRESULT STDMETHODCALLTYPE DacDbiInterfaceImpl::GetHeapSegments(OUT DacDbiArrayLi
 
     NewArrayHolder<HeapData> _heapHolder = heaps;
 
-    // Count the number of segments to know how much to allocate.
-    int total = 0;
-    for (size_t i = 0; i < heapCount; ++i)
-    {
-        total += (int)heaps[i].SegmentCount;
-        if (!region)
-        {
-            // SegmentCount is +1 due to the ephemeral segment containing more than one
-            // generation (Gen1 + Gen0, and sometimes part of Gen2).
-            total++;
-
-            // It's possible that part of Gen2 lives on the ephemeral segment.  If so,
-            // we need to add one more to the output.
-            const size_t eph = heaps[i].EphemeralSegment;
-            _ASSERTE(eph < heaps[i].SegmentCount);
-            if (heaps[i].Segments[eph].Start != heaps[i].Gen1Start)
-                total++;
-        }
-    }
-
-    pSegments->Alloc(total);
+    if (FAILED(hr))
+        return hr;
 
-    // Now walk all segments and write them to the array.
-    int curr = 0;
+    // Now walk all segments and emit them through the callback.
     for (size_t i = 0; i < heapCount; ++i)
     {
-        _ASSERTE(curr < total);
         if (!region)
         {
             // Generation 0 is not in the segment list.
-            COR_SEGMENT &seg = (*pSegments)[curr++];
-            seg.start = heaps[i].Gen0Start;
-            seg.end = heaps[i].Gen0End;
-            seg.type = CorDebug_Gen0;
-            seg.heap = (ULONG)i;
+            fpCallback(heaps[i].Gen0Start, heaps[i].Gen0End, (int)CorDebug_Gen0, (ULONG)i, pUserData);
         }
 
         for (size_t j = 0; j < heaps[i].SegmentCount; ++j)
         {
             if (region)
             {
-                _ASSERTE(curr < total);
-                COR_SEGMENT &seg = (*pSegments)[curr++];
-                seg.start = heaps[i].Segments[j].Start;
-                seg.end = heaps[i].Segments[j].End;
-                seg.type = (CorDebugGenerationTypes)heaps[i].Segments[j].Generation;
-                seg.heap = (ULONG)i;
+                fpCallback(
+                    heaps[i].Segments[j].Start,
+                    heaps[i].Segments[j].End,
+                    (int)heaps[i].Segments[j].Generation,
+                    (ULONG)i,
+                    pUserData);
             }
             else if (heaps[i].Segments[j].Generation == 1)
             {
@@ -6948,43 +6927,29 @@ HRESULT STDMETHODCALLTYPE DacDbiInterfaceImpl::GetHeapSegments(OUT DacDbiArrayLi
                 _ASSERTE(heaps[i].Segments[j].Start <= heaps[i].Gen1Start);
                 _ASSERTE(heaps[i].Segments[j].End > heaps[i].Gen1Start);
 
-                {
-                    _ASSERTE(curr < total);
-                    COR_SEGMENT &seg = (*pSegments)[curr++];
-                    seg.start = heaps[i].Gen1Start;
-                    seg.end = heaps[i].Gen0Start;
-                    seg.type = CorDebug_Gen1;
-                    seg.heap = (ULONG)i;
-                }
+                fpCallback(heaps[i].Gen1Start, heaps[i].Gen0Start, (int)CorDebug_Gen1, (ULONG)i, pUserData);
 
                 // It's possible for Gen2 to take up a portion of the ephemeral segment.
                 // We test for that here.
                 if (heaps[i].Segments[j].Start != heaps[i].Gen1Start)
                 {
-                    _ASSERTE(curr < total);
-                    COR_SEGMENT &seg = (*pSegments)[curr++];
-                    seg.start = heaps[i].Segments[j].Start;
-                    seg.end = heaps[i].Gen1Start;
-                    seg.type = CorDebug_Gen2;
-                    seg.heap = (ULONG)i;
+                    fpCallback(heaps[i].Segments[j].Start, heaps[i].Gen1Start, (int)CorDebug_Gen2, (ULONG)i, pUserData);
                 }
             }
             else
             {
                 // Otherwise, we have a gen2, POH, LOH or NonGC
-                _ASSERTE(curr < total);
-                COR_SEGMENT &seg = (*pSegments)[curr++];
-                seg.start = heaps[i].Segments[j].Start;
-                seg.end = heaps[i].Segments[j].End;
-
                 _ASSERTE(heaps[i].Segments[j].Generation <= CorDebug_NonGC);
-                seg.type = (CorDebugGenerationTypes)heaps[i].Segments[j].Generation;
-                seg.heap = (ULONG)i;
+                fpCallback(
+                    heaps[i].Segments[j].Start,
+                    heaps[i].Segments[j].End,
+                    (int)heaps[i].Segments[j].Generation,
+                    (ULONG)i,
+                    pUserData);
             }
         }
     }
 
-    _ASSERTE(total == curr);
     return hr;
 }
 

src/coreclr/debug/daccess/dacdbiimpl.h

@@ -118,7 +118,7 @@ class DacDbiInterfaceImpl :
                      OUT COR_HEAPOBJECT * objects,
                      OUT ULONG *fetched);
 
-    HRESULT STDMETHODCALLTYPE GetHeapSegments(OUT DacDbiArrayList<COR_SEGMENT> *pSegments);
+    HRESULT STDMETHODCALLTYPE EnumerateHeapSegments(FP_HEAPSEGMENT_CALLBACK fpCallback, CALLBACK_DATA pUserData);
 
 
     HRESULT STDMETHODCALLTYPE IsValidObject(CORDB_ADDRESS obj, OUT BOOL * pResult);

src/coreclr/debug/di/process.cpp

@@ -2188,6 +2188,43 @@ HRESULT CordbProcess::GetGCHeapInformation(COR_HEAPINFO *pHeapInfo)
     return hr;
 }
 
+namespace
+{
+    struct HeapSegmentAccumulator
+    {
+        CQuickArrayList<COR_SEGMENT> segments;
+        HRESULT                      hrError;
+    };
+
+    void HeapSegmentCallback(
+        CORDB_ADDRESS rangeStart,
+        CORDB_ADDRESS rangeEnd,
+        int generation,
+        ULONG heap,
+        CALLBACK_DATA pUserData)
+    {
+        HeapSegmentAccumulator *acc =
+            reinterpret_cast<HeapSegmentAccumulator*>(pUserData);
+
+        if (FAILED(acc->hrError))
+            return;
+
+        COR_SEGMENT s;
+        s.start = rangeStart;
+        s.end = rangeEnd;
+        s.type = (CorDebugGenerationTypes)generation;
+        s.heap = heap;
+        HRESULT hr = S_OK;
+        EX_TRY
+        {
+            acc->segments.Push(s);
+        }
+        EX_CATCH_HRESULT(hr);
+        if (FAILED(hr))
+            acc->hrError = hr;
+    }
+}
+
 HRESULT CordbProcess::EnumerateHeapRegions(ICorDebugHeapSegmentEnum **ppRegions)
 {
     if (!ppRegions)
@@ -2199,14 +2236,18 @@ HRESULT CordbProcess::EnumerateHeapRegions(ICorDebugHeapSegmentEnum **ppRegions)
 
     EX_TRY
     {
-        DacDbiArrayList<COR_SEGMENT> segments;
-        hr = GetDAC()->GetHeapSegments(&segments);
+        HeapSegmentAccumulator acc;
+        acc.hrError = S_OK;
+
+        hr = GetDAC()->EnumerateHeapSegments(&HeapSegmentCallback, &acc);
+        if (SUCCEEDED(hr) && FAILED(acc.hrError))
+            hr = acc.hrError;
 
         if (SUCCEEDED(hr))
         {
-            if (!segments.IsEmpty())
+            if (acc.segments.Size() != 0)
             {
-                CordbHeapSegmentEnumerator *segEnum = new CordbHeapSegmentEnumerator(this, &segments[0], (DWORD)segments.Count());
+                CordbHeapSegmentEnumerator *segEnum = new CordbHeapSegmentEnumerator(this, acc.segments.Ptr(), (DWORD)acc.segments.Size());
                 GetContinueNeuterList()->Add(this, segEnum);
                 hr = segEnum->QueryInterface(__uuidof(ICorDebugHeapSegmentEnum), (void**)ppRegions);
             }

src/coreclr/debug/inc/dacdbiinterface.h

@@ -1984,7 +1984,23 @@ IDacDbiInterface : public IUnknown
                      OUT COR_HEAPOBJECT * objects,
                      OUT ULONG * pFetched) = 0;
 
-    virtual HRESULT STDMETHODCALLTYPE GetHeapSegments(OUT DacDbiArrayList<COR_SEGMENT> * pSegments) = 0;
+    // Callback invoked for each GC heap segment.
+    //
+    // Arguments:
+    //    rangeStart - start address of the segment (inclusive).
+    //    rangeEnd   - end address of the segment (exclusive).
+    //    generation - CorDebugGenerationTypes value identifying the generation/kind of the segment.
+    //    heap       - index of the heap the segment belongs to (0 for workstation GC).
+    //    pUserData  - user data passed to EnumerateHeapSegments.
+    typedef void (*FP_HEAPSEGMENT_CALLBACK)(CORDB_ADDRESS rangeStart, CORDB_ADDRESS rangeEnd, int generation, ULONG heap, CALLBACK_DATA pUserData);
+
+    // Enumerate the GC heap segments.
+    //
+    // The callback is invoked once per segment and must not throw. To accumulate segments, callers
+    // typically stash a buffer (and any failure flag) in pUserData. The walker runs to completion
+    // regardless of any per-segment failure the callback decides to record; the caller surfaces the
+    // recorded failure after EnumerateHeapSegments returns.
+    virtual HRESULT STDMETHODCALLTYPE EnumerateHeapSegments(FP_HEAPSEGMENT_CALLBACK fpCallback, CALLBACK_DATA pUserData) = 0;
 
     virtual HRESULT STDMETHODCALLTYPE IsValidObject(CORDB_ADDRESS obj, OUT BOOL * pResult) = 0;
 

src/coreclr/inc/dacdbi.idl

@@ -143,6 +143,7 @@ typedef void (*FP_ASSEMBLY_ENUMERATION_CALLBACK)(VMPTR_Assembly vmAssembly, CALL
 typedef void (*FP_MODULE_ENUMERATION_CALLBACK)(VMPTR_Assembly vmAssembly, CALLBACK_DATA pUserData);
 typedef void (*FP_THREAD_ENUMERATION_CALLBACK)(VMPTR_Thread vmThread, CALLBACK_DATA pUserData);
 typedef BOOL (*FP_INTERNAL_FRAME_ENUMERATION_CALLBACK)(FramePointer fpFrame, CALLBACK_DATA pUserData);
+typedef void (*FP_HEAPSEGMENT_CALLBACK)(CORDB_ADDRESS rangeStart, CORDB_ADDRESS rangeEnd, int generation, ULONG heap, CALLBACK_DATA pUserData);
 
 
 //
@@ -378,7 +379,7 @@ interface IDacDbiInterface : IUnknown
     HRESULT CreateHeapWalk([out] HeapWalkHandle * pHandle);
     HRESULT DeleteHeapWalk([in] HeapWalkHandle handle);
     HRESULT WalkHeap([in] HeapWalkHandle handle, [in] ULONG count, [out] COR_HEAPOBJECT * objects, [out] ULONG * pFetched);
-    HRESULT GetHeapSegments([out] DacDbiArrayList_COR_SEGMENT * pSegments);
+    HRESULT EnumerateHeapSegments([in] FP_HEAPSEGMENT_CALLBACK fpCallback, [in] CALLBACK_DATA pUserData);
     HRESULT IsValidObject([in] CORDB_ADDRESS obj, [out] BOOL * pResult);
 
     // Reference Walking