Edit

ICorProfilerCallback4::MovedReferences2 Method

  • Article

Called to report the new layout of objects in the heap as a result of a compacting garbage collection. This method is called if the profiler has implemented the ICorProfilerCallback4 interface. This callback replaces the ICorProfilerCallback::MovedReferences method, because it can report larger ranges of objects whose lengths exceed what can be expressed in a ULONG.

Syntax

HRESULT MovedReferences2(  
    [in]  ULONG  cMovedObjectIDRanges,  
    [in, size_is(cMovedObjectIDRanges)] ObjectID oldObjectIDRangeStart[] ,  
    [in, size_is(cMovedObjectIDRanges)] ObjectID newObjectIDRangeStart[] ,  
    [in, size_is(cMovedObjectIDRanges)] SIZE_T    cObjectIDRangeLength[] );

Parameters

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 total size of the oldObjectIDRangeStart, newObjectIDRangeStart, and cObjectIDRangeLength arrays.

The next three arguments of MovedReferences2 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

A compacting garbage collector reclaims the memory occupied by dead objects and compacts that freed space. As a result, live objects might be moved within the heap, and ObjectID values distributed by previous notifications might change.

Assume that an existing ObjectID value (oldObjectID) lies within the following range:

oldObjectIDRangeStart[i] <= oldObjectID < oldObjectIDRangeStart[i] + cObjectIDRangeLength[i]

In this case, the offset from the start of the range to the start of the object is as follows:

oldObjectID - oldObjectRangeStart[i]

For any value of i that is in the following range:

0 <= i < cMovedObjectIDRanges

you can calculate the new ObjectID as follows:

newObjectID = newObjectIDRangeStart[i] + (oldObjectID – oldObjectIDRangeStart[i])

None of the ObjectID values passed by MovedReferences2 are valid during the callback itself, because the garbage collector might be in the middle of moving objects from old locations to new locations. Therefore, profilers should not attempt to inspect objects during a MovedReferences2 call. A ICorProfilerCallback2::GarbageCollectionFinished callback indicates that all objects have been moved to their new locations and inspection can be performed.

If the profiler implements both the ICorProfilerCallback and the ICorProfilerCallback4 interfaces, the MovedReferences2 method is called before the ICorProfilerCallback::MovedReferences method, but only if the MovedReferences2 method returns successfully. Profilers can return an HRESULT that indicates failure from the MovedReferences2 method, to avoid calling the second method.

Requirements

Platforms: See System Requirements.

Header: CorProf.idl, CorProf.h

Library: CorGuids.lib

.NET Framework Versions: Available since 4.5

See also