The BeginContainer method of the IHeapInfoCallBack interface is called by the Microsoft VM to notify the memory profiler when a garbage collection has occurred and to dump the heap. The Microsoft VM passes in the container type and two other IDs. The interpretation of these two other IDs is dependent on the container type.
The beginning and end of a heap dump are indicated by passing in special container types (C_BEGIN and C_END).
HRESULT BeginContainer(CONTAINER_TYPE type, UniqueID id1, UniqueID id2);
[in] type | The type of the container (CONTAINER_TYPE). |
[in] id1 | A unique value identifying the container, except for the C_BEGIN, C_END and C_HEAP container types. |
[in] id2 | A UniqueID whose meaning depends on the container type. |
The heap dump process uses the concept of a container type for representing the hierarchy of memory objects on the heap.
The container types are defined as CONTAINER_TYPE enumeration constants.
Constant | Value | Description |
C_BEGIN | 1 | A "dummy" container noting the start of the heap dump. UniqueID id1 and id2 are undefined. (These parameters are not used.) |
C_RT_THREAD | 2 | Root containers for threads. UniqueID id1 contains the ThreadID for this thread container. UniqueID id2 is undefined. (This parameter is not used.) |
C_RT_JIT | 3 | A JIT-compiled method frame. UniqueID id1 contains the StackID for this container. UniqueID id2 contains the MethodID for this container. |
C_RT_NATIVE | 4 | A native Win32 method frame. UniqueID id1 contains the StackID for this container. UniqueID id2 contains the MethodID for this container. |
C_RT_NATIVEGC | 5 | A native garbage collection frame. UniqueID id1 contains the StackID for this container. UniqueID id2 is undefined. (This parameter is not used.) |
C_RT_COM | 6 | A COM method frame. UniqueID id1 contains the StackID for this container. UniqueID id2 contains the MethodID for this container. |
C_RT_INTERPRETED | 7 | An interpreted method frame. UniqueID id1 contains the StackID for this container. UniqueID id2 contains the MethodID for this container. |
C_RT_FASTINTERPRETED | 8 | A fast-interpreted method frame. UniqueID id1 contains the StackID for this container. UniqueID id2 contains the MethodID for this container. |
C_RT_INTERNALFRAME | 9 | An internal VM frame. UniqueID id1 contains the StackID for this container. UniqueID id2 is undefined. (This parameter is not used.) |
C_RT_INTERNALVM | 10 | An internal VM object. UniqueIDs id1 and id2 are undefined. (These parameters are not used.) |
C_RT_CLASS | 11 | Static class references. UniqueID id1 contains the ClassID for this container. UniqueID id2 is undefined. (This parameter is not used.) |
C_RT_ROOTTABLE | 12 | Miscellaneous root references. UniqueIDs id1 and id2 are undefined (these parameters are not used). |
C_RT_STRONGPTR | 13 | A strong pointer. UniqueIDs id1 and id2 are undefined. (These parameters are not used.) |
C_RT_FINALIZED | 14 | Objects awaiting finalization. UniqueIDs id1 and id2 are undefined. (These parameters are not used.) |
C_HEAP | 15 | The remaining portions of the heap not reported elsewhere. UniqueIDs id1 and id2 are undefined. (These parameters are not used.) |
C_END | 16 | A dummy container noting the end of the heap dump. UniqueIDs id1 and id2 are undefined. (These parameters are not used.) |
Execution of the Java process is suspended during the entire process of a heap dump after garbage collection has occurred. The profiler receives notification of the beginning of a heap dump when it receives a call to BeginContainer with a container type of C_BEGIN.
The profiler will then get a BeginContainer method call followed by zero (0) or more RootReferences and ObjectReferences method calls. This process will repeat any number of times (hundreds or thousands of times, for example) until the profiler receives a BeginContainer notification with a container type of C_END, signifying the end of the heap dump. When this last BeginContainer call returns from the profiler, execution of the Java process resumes.
The various container types will be heap dumped to the profiler in any order, with two exceptions: The container type C_RT_THREAD will always be dumped before any of the associated thread's stack frame roots. The container type C_HEAP will always be dumped last. Multiple BeginContainer calls may be received for the same container, with any number of intervening BeginContainer calls for different ids. That is, the same value of id1 is passed to both BeginContainer calls, and the calls may or may not be successive.
The RootReferences method reports root memory references from the current container. The heap container (container type C_HEAP) is a special container that won't generate any RootReferences method calls. The ObjectReferences method reports an object and the object's memory references. When calling the ObjectReferences method, each memory reference will be traversed depth-first.
The profiler can return E_FAIL to abort the heap dump. The profiler will receive no further callbacks during this garbage collection, with the one exception of a C_END container notification. A C_END notification will always be sent, even if the heap dump is aborted. After the C_END notification is sent, execution resumes.
If S_POSTPONE_REFERENCES is returned from the ObjectReferences method, the heap dump will not descend references from the current object, but will report these memory references either from other as-yet unvisited objects or in the heap container (C_HEAP container type). A profiler can obtain a flat list of objects by always returning this value from the ObjectReferences method.
If S_OK is returned, the heap dump will proceed normally.