ICorProfilerCallback::MovedReferences Method
Called to report the new layout of objects in the heap as a result of a compacting garbage collection.
HRESULT MovedReferences(
[in] ULONG cMovedObjectIDRanges,
[in, size_is(cMovedObjectIDRanges)] ObjectID oldObjectIDRangeStart[] ,
[in, size_is(cMovedObjectIDRanges)] ObjectID newObjectIDRangeStart[] ,
[in, size_is(cMovedObjectIDRanges)] ULONG cObjectIDRangeLength[] );
Parameters
| Parameter | Description |
|---|---|
cMovedObjectIDRanges |
[in] The number of blocks of contiguous objects that moved as the result of the compacting garbage collection. That is, the value of cMovedObjectIDRanges is the size of the oldObjectIDRangeStart, newObjectIDRangeStart, and cObjectIDRangeLength arrays. The next three arguments of MovedReferences are parallel arrays. In other words, oldObjectIDRangeStart[i], newObjectIDRangeStart[i], and cObjectIDRangeLength[i] all concern a single block of contiguous objects. |
oldObjectIDRangeStart |
[in] An array of ObjectID values, each of which is the old (pre-garbage collection) starting address of a block of contiguous, live objects in memory. |
newObjectIDRangeStart |
[in] An array of ObjectID values, each of which is the new (post-garbage collection) starting address of a block of contiguous, live objects in memory. |
cObjectIDRangeLength |
[in] An array of integers, each of which is the size of a block of contiguous objects in memory. A size is specified for each block that is referenced in the oldObjectIDRangeStart and newObjectIDRangeStart arrays. |
Remarks
The elements of the oldObjectIDRangeStart, newObjectIDRangeStart, and cObjectIDRangeLength arrays should be interpreted as follows to determine whether an object has moved. If an ObjectID value lies within the range such that:
oldObjectIDRangeStart[i] <= ObjectID value < oldObjectIDRangeStart[i] +
cObjectIDRangeLength[i]
for any value of i, such that:
0 <= i < cMovedObjectIDRanges,
then the ObjectID value has changed to:
ObjectID value - oldObjectIDRangeStart[i] + newObjectIDRangeStart[i].
A compacting garbage collection reclaims the memory occupied by "dead" objects and compacts that freed space. As a result, "live" objects might be moved within the heap, and thus ObjectID values handed out by previous notifications can change. The internal state of an object itself does not change (other than its references to other objects), just its location in memory, and therefore its ObjectID.
The MovedReferences notification lets a profiler update its internal tables that are tracking info by ObjectID. (This method's name is somewhat misleading, because it is issued even for objects that were not moved.)
The number of objects in the heap can number thousands or millions. With such large numbers, it is impractical to report their movement by providing a before-and-after ID for each object. However, the garbage collector tends to move a run of contiguous, live objects as a group, so that they end up at new locations in the heap, but are still contiguous. The MovedReferences notification reports the "before" and "after" ObjectID values for each block of contiguous objects.
None of the ObjectID values passed by MovedReferences are valid during the callback itself, as the garbage collection might be in the middle of moving objects from old locations to new locations. Therefore, profilers should not attempt to inspect objects during a MovedReferences call. When the profiler receives a ICorProfilerCallback2::GarbageCollectionFinished Method callback, all objects have been moved to their new locations and inspection can be performed.
Requirements
Platforms: Windows 2000, Windows XP, Windows Server 2003 family
Header: CorProf.idl
Library: CorGuids.lib
.NET Framework Version: 2.0