Edit

Share via

ICorProfilerCallback::ObjectReferences Method

  • Article

Notifies the profiler about objects in memory that are being referenced by the specified object.

Syntax

HRESULT ObjectReferences(  
    [in]  ObjectID objectId,  
    [in]  ClassID  classId,  
    [in]  ULONG    cObjectRefs,  
    [in, size_is(cObjectRefs)] ObjectID objectRefIds[] );

Parameters

objectId
[in] The ID of the object that is referencing objects.

classId
[in] The ID of the class that the specified object is an instance of.

cObjectRefs
[in] The number of objects referenced by the specified object (that is, the number of elements in the objectRefIds array).

objectRefIds
[in] An array of IDs of objects that are being referenced by objectId.

Remarks

The ObjectReferences method is called for each object remaining in the heap after a garbage collection has completed. If the profiler returns an error from this callback, the profiling services will discontinue invoking this callback until the next garbage collection.

The ObjectReferences callback can be used in conjunction with the ICorProfilerCallback::RootReferences callback to create a complete object reference graph for the runtime. The common language runtime (CLR) ensures that each object reference is reported only once by the ObjectReferences method.

The object IDs returned by ObjectReferences are not valid during the callback itself, because the garbage collection might be in the middle of moving objects. Therefore, profilers must not attempt to inspect objects during an ObjectReferences call. When ICorProfilerCallback2::GarbageCollectionFinished is called, the garbage collection is complete and inspection can be safely done.

A null ClassId indicates that objectId has a type that is unloading.

Requirements

Platforms: See System Requirements.

Header: CorProf.idl, CorProf.h

Library: CorGuids.lib

.NET Framework Versions: Available since 2.0

See also