The RootReferences method of the IHeapInfoCallBack interface is called by the Microsoft VM to notify the memory profiler of root references after a garbage collection has occurred during a heap dump. The Microsoft VM passes in an array of references within this root, the number of root references being reported, and a bitmask of JVM_OBJECT_FLAGS for each reference.
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.
HRESULT RootReferences(const ObjectID *prefs, unsigned nrefs, const DWORD *pflags);
[in] *prefs | A pointer to an array of ObjectID references in this root. |
[in] nrefs | The number of references in this root. |
[in] *pflags | A pointer to a parallel array of JVM_OBJECT_FLAGS, one flag for each ObjectID reference in this root. |
The heap dumping process associates an object flag with each object (ObjectID). The JVM_OBJECT_FLAGS can be a combination of the first three enumeration constants or the predefined combination listed as the last enumeration constant.
Constant | Value | Description |
JVM_OBJ_ALREADY_REPORTED | 0x00001 | The Java object has already been reported as a reference. |
JVM_OBJ_ALREADY_VISITED | 0x00002 | The Java object has already been visited and will not be traversed. |
JVM_OBJ_MORE_REFERENCES | 0x10000 | Additional references from the same Java object will be reported in subsequent calls. |
ALL_JVM_OBJECT_FLAGS | 0x10003 | A combination of the previous enumeration constants (JVM_OBJ_ALREADY_REPORTED, JVM_OBJ_ALREADY_VISITED, and JVM_OBJ_MORE_REFERENCES). |
Each reference corresponds to a field in the same order obtained from the GetClassFields method, so null object references are reported. Note that only fields with the JVM_FIELD_OBJECTREF access modifier and without the JVM_FIELD_STATIC access modifier are relevant. For some objects (java.lang.String objects, for example), the number of references reported might not match the number of fields (JVM_CLS_VARIABLE_SIZE is set for the class properties).
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_OK is returned from this method, the heap dump will proceed normally.