ICorProfilerCallback2::SurvivingReferences Method

Called to report the layout of objects in the heap as a result of a non-compacting garbage collection.

HRESULT SurvivingReferences(
    [in]                                    ULONG    cSurvivingObjectIDRanges,
    [in, size_is(cSurvivingObjectIDRanges)] ObjectID objectIDRangeStart[] ,
    [in, size_is(cSurvivingObjectIDRanges)] ULONG    cObjectIDRangeLength[] );

Parameters

Parameter	Description
cSurvivingObjectIDRanges	[in] The number of blocks of contiguous objects that survived as the result of the non-compacting garbage collection. That is, the value of cSurvivingObjectIDRanges is the size of the objectIDRangeStart and cObjectIDRangeLength arrays, which store an ObjectID and a length, respectively, for each block of objects. The next two arguments of SurvivingReferences are parallel arrays. In other words, objectIDRangeStart and cObjectIDRangeLength concern the same block of contiguous objects.
objectIDRangeStart	[in] An array of ObjectID values, each of which is the 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 surviving block of contiguous objects in memory. A size is specified for each block that is referenced in the objectIDRangeStart array.

Remarks

The elements of the objectIDRangeStart and cObjectIDRangeLength arrays should be interpreted as follows to determine whether an object survived the garbage collection. If an ObjectID value lies within the range such that:

objectIDRangeStart[i] <= ObjectID value < objectIDRangeStart[i] +

cObjectIDRangeLength[i]

for any value of i such that:

0 <= i < cSurvivingObjectIDRanges,

then the object has survived the garbage collection.

A non-compacting garbage collection reclaims the memory occupied by "dead" objects, but does not compact that freed space. As a result, memory is returned to the heap, but no "live" objects are moved.

The common language runtime calls SurvivingReferences for non-compacting garbage collections. For compacting garbage collections, ICorProfilerCallback::MovedReferences Method is called instead. A single garbage collection can be compacting for one generation and non-compacting for another. For a garbage collection on any particular generation, the profiler will receive either a SurvivingReferences callback or a MovedReferences callback, but not both.

Multiple SurvivingReferences callbacks might be received during a particular garbage collection, due to limited internal buffering, multiple threads reporting in the case of server garbage collection, and other reasons. In the case of multiple callbacks during a garbage collection, the information is cumulative — all references that are reported in any SurvivingReferences callback survive the garbage collection.

Requirements

Platforms: Windows 2000, Windows XP, Windows Server 2003 family

Header: CorProf.idl

Library: CorGuids.lib

.NET Framework Version: 2.0

See Also

Reference

ICorProfilerCallback Interface
ICorProfilerCallback2 Interface