Microsoft SDK for Java

IHeapInfoCallback::
ObjectReferences

The ObjectReferences method of the IHeapInfoCallBack interface is called by the Microsoft VM to notify the memory profiler of object references after a garbage collection has occurred during a heap dump. The Microsoft VM passes in the ObjectID for the object, a bitmask of JVM_OBJECT_FLAGS for the object, an array of other references (ObjectIDs) within this object, the number of object references being reported, and a bitmask of JVM_OBJECT_FLAGS for each other reference.

Syntax

HRESULT ObjectReferences(ObjectID object_id, DWORD flags, const ObjectID *prefs, unsigned nrefs, const DWORD *pflags);

Parameters

[in] object_id The ObjectID that is being reported.
[in] flags The JVM_OBJECT_FLAGS for this object.
[in] *prefs A pointer to an array of ObjectID references within this object.
[in] nrefs The number of ObjectID references within this object.
[in] *pflags A pointer to a parallel array of JVM_OBJECT_FLAGS, one flag for each ObjectID reference within this object.

Remarks

The heap dump 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 ObjectReferences method reports an object and the object's memory references. When calling the ObjectReferences method, each memory reference will be traversed depth-first. A parallel array indicates objects that have been seen before will not be traversed. There are two possible object flags from the JVM_OBJECT_FLAGS enumeration that might be reported for these objects by the VM: JVM_OBJ_ALREADY_REPORTED or JVM_OBJ_ALREADY_VISITED. If the VM passes the JVM_OBJ_ALREADY_REPORTED flag in the object flags of an ObjectID, the VM has already reported the existence of this memory object during the heap dump. This process identifies recursive structures and objects with multiple references to the same objects.

For example, a stack frame might have two local variables pointing to the same object. JVM_OBJ_ALREADY_REPORTED will be set for the reference for the second variable. If the JVM_OBJ_ALREADY_VISITED flag is set for a reference, an ObjectReferences call has already been made for the references object and another call will not be made. If an object has a reference to itself, the reference will be reported as visited.

All references in an object will be reported before descending. If all references cannot be reported in a single call, the JVM_OBJ_MORE_REFERENCES flag will be set for the object flag. If this flag is clear, no further ObjectReferences calls will be received for that object.

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.

The profiler might return S_POSTPONE_REFERENCES from the last ObjectReferences call for an object to indicate that the references from this object should not be descended. Note that these referenced objects that have been skipped might still be reported and visited through references from different objects. Any objects that were not visited during root traversal are reported later within the heap container type (C_HEAP).

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

If S_OK is returned, the heap dump will proceed normally.

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