ICorProfilerCallback5::ConditionalWeakTableElementReferences Method

Article
07/20/2022

Identifies the transitive closure of objects referenced by those roots through both direct member field references and through ConditionalWeakTable dependencies.

Syntax

HRESULT ConditionalWeakTableElementReferences(
     [in]                     ULONG    cRootRefs,
     [in, size_is(cRootRefs)] ObjectID keyRefIds[],
     [in, size_is(cRootRefs)] ObjectID valueRefIds[],
     [in, size_is(cRootRefs)] GCHandleID rootIds[]
);

Parameters

cRootRefs
[in] The number of elements in the keyRefIds, valueRefIds, and rootIds arrays.

keyRefIds
[in] An array of object IDs, each of which contains the ObjectID for the primary element in the dependent handle pair.

valueRefIds
[in] An array of object IDs, each of which contains the ObjectID for the secondary element in the dependent handle pair. (keyRefIds[i] keeps valueRefIds[i] alive.)

rootIds
[in] An array of GCHandleID values that point to an integer that contains additional information about the garbage collection root.

None of the ObjectID values returned by the ConditionalWeakTableElementReferences method are valid during the callback itself, because the garbage collector may be in the process of moving objects from old to new locations. Therefore, profilers should not attempt to inspect objects during a ConditionalWeakTableElementReferences call. At GarbageCollectionFinished, all objects have been moved to their new locations, and inspection may be done.

Example

The following code example demonstrates how to implement ICorProfilerCallback5 and use this method.

HRESULT Callback5Impl::ConditionalWeakTableElementReferences(
    ULONG      cRootRefs,
    ObjectID   keyRefIds[],
    ObjectID   valueRefIds[],
    GCHandleID rootIds[])
{
    printf("Callback5Impl::ConditionalWeakTableElementReferences called\n");
    for (unsigned int i = 0; i < cRootRefs; ++i)
    {
        // Save dependency to XML for later retrieval
        PersistDependencyToXml(rootIds[i], keyRefIds[i], valueRefIds[i]);
        // or store dependency to an internal map
        m_cwt_deps->add_dep(rootIds[i], keyRefIds[i], valueRefIds[i]);
        // or add arc to object graph
        m_obj_graph->add_arc(keyRefIds[i], valueRefIds[i], rootIds[i]);
    }
    return S_OK;
}

Remarks

A profiler for the .NET Framework 4.5 or later versions implements the ICorProfilerCallback5 interface and records the dependencies specified by the ConditionalWeakTableElementReferences method. ICorProfilerCallback5 provides the complete set of dependencies among live objects represented by ConditionalWeakTable entries. These dependencies and the member field references specified by the ICorProfilerCallback::ObjectReferences method enable a managed profiler to generate the full object graph of live objects.

Requirements

Platforms: See System Requirements.

Header: CorProf.idl, CorProf.h

.NET Framework Versions: Available since 4.5

Share via