JVMTI IterateOverReachableObjects and very poor documentation.

As part of my daily work I’ve been working with Steve to write a heap parser so that our tests can find any memory leaks without the need to attach a profiler and hunt though the results.

We created a jvmti agent which could tag an object on the heap then find out if the object was reachable via any GC roots.

This worked well and we had no problems for over a year but recently we started to get some strange array index out of bounds.

The cause was the very poor documentation of the jvmtiObjectReferenceCallback call where the field information was being calculated.

The documentation was wrong in 1.5 but even in 1.6 it simply does not provide enough information to write a heap walker which can print the field names.

I.e for the JVMTI_REFERENCE_FIELD reference kind it says the following:

Reference from an object to the value of one of its instance fields. For references of this kind the referrer_index parameter to the jvmtiObjectReferenceCallback is the index of the the instance field. The index is based on the order of all the object’s fields. This includes all fields of the directly declared static and instance fields in the class, and includes all fields (both public and private) fields declared in superclasses and superinterfaces. The index is thus calculated by summing the index of field in the directly declared class (see GetClassFields), with the total number of fields (both public and private) declared in all superclasses and superinterfaces. The index starts at zero.

This may seem ok but how do you parse the super classes and super interfaces?  The documentation states nothing about the order of the fields so do you scan all interfaces first or last, do you walk the super classes once for classes and once for interfaces?

Being very vague (even google didnt know much) it was difficult to get the output, when a leak was detected, to show the correct field.

It would randomly output fields which were the wrong type and many other issues.

After days of trial and error I was about to give up, then I found hprof_reference.c via google, and then found the rest of the hprof source as part of the JDK directory.

After looking though this code it was possible to figure out exactly how the class and interface heirachy should be processed.

How are we expected to use the JVMTI when its so poorly documented?

One Response to “JVMTI IterateOverReachableObjects and very poor documentation.”

  1. Maarten Nieber Says:


    I’m new to Java and really soon I too wanted to add a check in my test code that no instances of a certain class were still alive after running the test (it seems such a reasonable request!)
    Would there be any chance of releasing your tool to the public?


Leave a Reply