Heap Monitor Sample

This sample is located in \Samples\Profiler\HeapMon.

Note   To use this sample, it is recommended that you have Microsoft® Visual C++® version 5.0 or higher installed.

Description
Using the Sample
Key Project Files
Technologies Demonstrated

Description

This sample shows how to use the heap monitor interfaces to create tools for finding memory leaks and inspect the application’s state.

Note   This sample is atypical of a real-world heap monitor because the user interface (UI) is implemented inproc and the UI is presented as an effect of executing the profilee. Normally, the UI is already executing and profilers will execute the profilee outproc. By implementing the UI inproc, this sample also shows how to properly serialize heap dumping with various other heap-related profiler activities on other threads. In a normal profiler, this other thread might be responsible for communicating with the outproc UI. There are some miscellaneous notes at the beginning of the Hpmonmgr.cpp file that document some of these synchronization problems and how the sample handles them.

Using the Sample

To compile and use the sample

  1. Change to the %SDKDIR%\Samples\Profiler\HeapMon directory from the MS-DOS® Command Prompt window.

  2. Type the following command:

    nmake CFG=release

  3. In the same directory, type the following command to register Heapmon.dll as a COM component and a Microsoft virtual machine (Microsoft VM) event monitor:

    regsvr32 release\heapmon.dll

  4. Type the following command to enable event monitoring:

    on

    (The batch file On.bat can be used to set the appropriate value to enable event monitoring.)

  5. Run some of your Java code. A magnifying glass icon will appear in the taskbar notification area.

  6. Click the magnifying glass icon to display the main window. This displays two menu items in the main window: Stop and Window.

Stop Menu

The Stop menu will stop the Heap Monitor code the next time garbage collection occurs. When garbage collection occurs, all information in the windows will be updated.

Note   Creating new windows while the Heap Monitor is stopped may not issue complete information. The Heap Monitor only collects information needed to update windows that were already created when garbage collection started.

When the Heap Monitor is stopped, Stop will change to Go. To resume Heap Monitor execution, click Go.

Windows Menu

The Window menu contains commands to create windows that display information about objects in the Microsoft VM.

There are five types of windows that you can create from the Window menu:

Heap Viewer

To navigate through objects, use the tree control in the left pane. The right pane displays details about selected tree items. (For example, if you select a string object in the tree, the string’s character contents are displayed in the right pane.)

To display a context menu, right-click items in the tree control. You can choose among four options: Track (this tracks the object during garbage collection), Tag (tags the object), Listing Option1 (lists references to the selected object in a new window), and Listing Option2 for classes (lists all the instances of the class).

Class List Viewer

Displays a list of classes. The information about the classes is shown in columns. To sort the information in a column, click the column.

The columns display the following information:

Total instances

Number of instances created since the process started.

Bytes of objects

Sum of the object-sizes in the heap.

Live size

Sum of the sizes of each instance that was not collected during the last garbage collection.

Average age

Average number of garbage collections survived by the instances that survived the last garbage collection.

Garbage Collection Status Viewer

Displays a list of all past garbage collections for which any information was collected. The information is displayed in columns and is as follows:

Objects

Total number of objects in heap.

Bytes of Objects

Sum of the object-sizes in the heap.

Objects with multiple references

Number of objects referenced by more than one object or root, including self-references.

Object out-edges

Number of references to objects from other objects, including self-references.

Roots

Number of roots.

Root edges

Number of references to objects from roots.

Monitors

Number of monitors in use.

Tracked Object Viewer

Displays a list of objects that are tracked. Object identifiers may change between garbage collections. It is helpful to follow an object until it is garbage-collected. To track an object, right-click it and select Track.

Tagged Object Viewer

Displays a list of objects that are tagged. To tag an object, click (or right-click) the object’s text, select Tag, and then enter the new description.

To uninstall the sample

In the %SDKDIR%\Samples\Profiler\HeapMon directory type the following command:

regsvr32 /u release\heapmon.dll

Key Project Files

The following table has overviews of the most important files and what is demonstrated in each.

File Technology
Hpmonmgr.* Implements HeapMonitorManager, which is a both a regular event monitor and a heap monitor, and also the main window.

HeapMonitorManager collects miscellaneous information from selected events and also receives the initial heap dump. In this sample, the initial heap dump is only interested in identifying objects with multiple references. Additional heap dumps are requested as needed to perform searches.

Ids.hpp Defines IDWrapper and its derivatives. IDWrappers are proxies to UniqueIDs that are obtained from the Microsoft VM to cache information (such as class names, lists of member FieldIDs, class statistics, and so on).
Hpmnclnt.hpp Defines IHeapMonitorClient, the interface through which HeapMonitorManager multiplexes Microsoft VM events.
Baseview.* Implements BasicClient, a simple MDI client of HeapMonitorManager that implements IheapMonitorClient.
Objview.* Implements ObjectViewer, which extends BasicClient to display a split-pane view of the heap.
Heapview.* Implements HeapViewer, which extends ObjectViewer to allow navigation of the heap. The tree is initially populated with the heap roots.
Clsview.* Implements ClassViewer, which extends BasicClient to display per-class information. This information is accumulated by HeapMonitorManager as classes are loaded.
Objlist.* Implements ObjectListViewer, which extends BasicClient to display a list of objects
Instview.* Implements ClassInstancesViewer, which extends ObjectListViewer to display instances of a specific class.
Refsview.* Implements ObjectReferencesViewer, which extends ObjectListViewer to display references of a specific object.
Gcinfo.hpp Defines PerGCInformation, which is information saved by HeapMonitorManager about past garbage collections.
Gcview.* Implements GCHistoryViewer, which extends BasicClient to display information about past garbage collections.
Obsearch.* Implements SearchHeapInfoCallback, which implements IHeapInfoCallback for use with IjavaHeapMonitor2:WalkHeap. This callback is used to search for references to one or more objects or to find instances of classes.
Main.cpp Contains DLL exports that are required by COM, and associated code for registration and class factory.
Ansibuf.hpp, Utils.*, Utf8.* Contains UTF8/ANSI/Unicode conversions and the hash table implementation.
On.bat, On.reg, Off.bat, Off.reg Batch files and regedit files that turn event monitoring on and off.

Technologies Demonstrated

Heap Monitor/Profiler

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