ICorProfilerCallback2::RootReferences2 Method

  • Article

Notifies the profiler about root references after a garbage collection has occurred. This method is an extension of the ICorProfilerCallback::RootReferences Method method.

HRESULT RootReferences2(
    [in]                     ULONG    cRootRefs,
    [in, size_is(cRootRefs)] ObjectID rootRefIds[],
    [in, size_is(cRootRefs)] COR_PRF_GC_ROOT_KIND rootKinds[],
    [in, size_is(cRootRefs)] COR_PRF_GC_ROOT_FLAGS rootFlags[],
    [in, size_is(cRootRefs)] UINT_PTR rootIds[]);

Parameters

Parameter Description

cRootRefs

[in] The number of elements in the rootRefIds, rootKinds, rootFlags, and rootIds arrays.

rootRefIds

[in] An array of object IDs, each of which references either a static object or an object on the stack. Elements in the rootKinds array provide information to classify corresponding elements in the rootRefIds array.

rootKinds

[in] An array of COR_PRF_GC_ROOT_KIND Enumeration values that indicate the type of the garbage-collection root.

rootFlags

[in] An array of COR_PRF_GC_ROOT_FLAGS Enumeration values that describe the properties of a garbage-collection root.

rootIds

[in] An array of UINT_PTR values that point to an integer containing additional information about the garbage-collection root, depending on the value of the rootKinds parameter.

If the type of the root is a stack, the root ID is for the function containing the variable. If that root ID is 0, the function is an unnamed function internal to the CLR. If the type of the root is a handle, the root ID is for the garbage-collection handle. For the other root kinds, the ID is an opaque value and should be ignored.

Remarks

The rootRefIds, rootKinds, rootFlags, and rootIds, arrays are parallel arrays. That is, rootRefIds[i], rootKinds[i], rootFlags[i], and rootIds[i], all concern the same root.

Both ICorProfilerCallback::RootReferences Method and RootReferences2 are called to notify the profiler. Profilers will normally implement one or the other, but not both, because the information passed in RootReferences2 is a superset of that passed in ICorProfilerCallback::RootReferences Method.

It is possible for entries in rootRefIds to be zero, which implies that the corresponding root reference is NULL and does not refer to an object on the managed heap.

The object IDs returned by RootReferences2 are not valid during the callback itself, because the garbage collection might be in the middle of moving objects from old addresses to new addresses. Therefore, profilers should not attempt to inspect objects during a RootReferences2 call. When ICorProfilerCallback2::GarbageCollectionFinished Method is called, all objects have been moved to their new locations and can be safely inspected.

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