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
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.
To compile and use the sample
nmake CFG=release
regsvr32 release\heapmon.dll
on
(The batch file On.bat can be used to set the appropriate value to enable event monitoring.)
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.
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:
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).
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.
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.
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.
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
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. |