Share via

ICorProfilerCallback2 Interface

  • Article

Provides methods that are used by the common language runtime (CLR) to notify a code profiler when the events to which the profiler has subscribed occur. The ICorProfilerCallback2 interface is an extension of the ICorProfilerCallback interface. That is, it provides new callbacks introduced in the .NET Framework version 2.0.

NoteNote:

Each method implementation must return an HRESULT having a value of S_OK on success or E_FAIL on failure. Currently, the CLR ignores the HRESULT that is returned by each callback except ICorProfilerCallback::ObjectReferences.

 
interface ICorProfilerCallback2 : ICorProfilerCallback
{
    HRESULT ThreadNameChanged(
        [in] ThreadID threadId,
        [in] ULONG cchName,
        [in] WCHAR name[]);
    HRESULT GarbageCollectionStarted(
        [in] int cGenerations,
        [in, size_is(cGenerations), length_is(cGenerations)] BOOL generationCollected[],
        [in] COR_PRF_GC_REASON reason);
    HRESULT SurvivingReferences(
        [in]                                    ULONG    cSurvivingObjectIDRanges,
        [in, size_is(cSurvivingObjectIDRanges)] ObjectID objectIDRangeStart[] ,
        [in, size_is(cSurvivingObjectIDRanges)] ULONG    cObjectIDRangeLength[] );
    HRESULT GarbageCollectionFinished();
    HRESULT FinalizeableObjectQueued(
        [in] DWORD finalizerFlags,
        [in] ObjectID objectID);
    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[]);
    HRESULT HandleCreated(
        [in] GCHandleID handleId,
        [in] ObjectID initialObjectId);
    HRESULT HandleDestroyed(
        [in] GCHandleID handleId);
}

Methods

Method

Description

ICorProfilerCallback2::FinalizeableObjectQueued Method

Notifies the code profiler that an object with a finalizer has been queued to the finalizer thread for execution of its Finalize method.

ICorProfilerCallback2::GarbageCollectionFinished Method

Notifies the profiler that a garbage collection has completed and all garbage collection callbacks have been issued for it.

ICorProfilerCallback2::GarbageCollectionStarted Method

Notifies the code profiler that a garbage collection has started.

ICorProfilerCallback2::HandleCreated Method

Notifies the code profiler that a garbage collection handle has been created.

ICorProfilerCallback2::HandleDestroyed Method

Notifies the code profiler that a garbage collection handle has been destroyed.

ICorProfilerCallback2::RootReferences2 Method

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

ICorProfilerCallback2::SurvivingReferences Method

Notifies the profiler about object references that have survived a garbage collection.

ICorProfilerCallback2::ThreadNameChanged Method

Notifies the code profiler that the name of a thread has changed.

Remarks

The CLR calls a method in the ICorProfilerCallback (or ICorProfilerCallback2) interface to notify the profiler when an event, to which the profiler had subscribed, occurs. This is the primary callback interface through which the CLR communicates with the code profiler.

A code profiler must implement the methods of the ICorProfilerCallback interface. For the .NET Framework 2.0 and later versions, the profiler must also implement the ICorProfilerCallback2 methods. Each method implementation must return an HRESULT having a value of S_OK on success or E_FAIL on failure. Currently, the CLR ignores the HRESULT that is returned by each callback except ICorProfilerCallback::ObjectReferences.

A code profiler must register in the Microsoft Windows registry, its COM object that implements the ICorProfilerCallback and ICorProfilerCallback2 interfaces. A code profiler subscribes to the events for which it wants to receive notification by calling ICorProfilerInfo::SetEventMask. This is usually done in the profiler's implementation of ICorProfilerCallback::Initialize. The profiler is then able to receive notification from the runtime when an event is about to occur or has just occurred in an executing runtime process.

NoteNote:

The profiler registers a single COM object. If the profiler is targeting .NET Framework version 1.0 or 1.1, that COM object need only implement the methods of ICorProfilerCallback. If it is targeting .NET Framework version 2.0 and later, the COM object must also implement the methods of ICorProfilerCallback2.

Requirements

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

Header: CorProf.idl

Library: CorGuids.lib

.NET Framework Version: 2.0

See Also

Concepts

Profiling Interfaces

ICorProfilerCallback Interface