ICorProfilerCallback2 Interface
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 interface. That is, it provides new callbacks supported in the .NET Framework version 2.0.
Note
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 Method.
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 |
|---|---|
Notifies the code profiler that an object with a finalizer has been queued to the finalizer thread for execution of its Finalize method. |
|
Notifies the profiler that a garbage collection has completed and all garbage collection callbacks have been issued for it. |
|
Notifies the code profiler that a garbage collection has started. |
|
Notifies the code profiler that a garbage collection handle has been created. |
|
Notifies the code profiler that a garbage collection handle has been destroyed. |
|
Notifies the profiler about root references after a garbage collection has occurred. This method is an extension of the ICorProfilerCallback::RootReferences Method method. |
|
Notifies the profiler about object references that have survived a garbage collection. |
|
Notifies the code profiler that the name of a thread has changed. |
Remarks
The CLR calls a method in the ICorProfilerCallback (or ICorProfilerCallback2 Interface) 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, 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 Method.
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 Method. This is usually done in the profiler's implementation of ICorProfilerCallback::Initialize Method. 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.
Note
The profiler registers a single COM object. If the profiler is targeting .NET Framework version 1.x, that COM object need only implement the methods of ICorProfilerCallback. If it is targeting .NET Framework version 2.0, 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
Reference
ICorProfilerCallback Interface