Microsoft SDK for Java

IHeapInfoCallback::
RootReferences

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.

Syntax

HRESULT RootReferences(const ObjectID *prefs, unsigned nrefs, const DWORD *pflags);

Parameters

[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.

Remarks

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.

JVM_OBJECT_FLAGS

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.

© 1999 Microsoft Corporation. All rights reserved. Terms of use.