plugins/org.eclipse.mat.ui.help/reference/inspections/unreachable_objects.dita

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd" >
<reference id="ref_inspections_path_to_gc_roots" xml:lang="en-us">
	<title>Unreachable objects</title>
	<shortdesc>Find out more about objects that could or should be garbage collected.
	</shortdesc>
	<prolog>
		<copyright>
			<copyryear year="2018"></copyryear>
			<copyrholder>
				Copyright (c) 2008, 2018 SAP AG, IBM Corporation and others.
			    All rights reserved. This program and the accompanying materials
			    are made available under the terms of the Eclipse Public License v1.0
			    which accompanies this distribution, and is available at
			    http://www.eclipse.org/legal/epl-v10.html
			</copyrholder>
		</copyright>
	</prolog>
	
	<refbody>
		<section>
			<title>Motivation</title>
			<p>Sometimes a heap dump contains objects which would be removed at the next garbage collection.
			These are objects which are unreachable from the garbage collection roots.
			By default, Memory Analyzer removes these objects as part of the parse process as normally they are not
			important in determining a memory leak. If the heap dump is generated as a result of an <apiname>OutOfMemoryError</apiname>
			then the Java virtual machine will usually have performed a garbage collection operation to attempt to
			free space for the new object, so there will not be those objects in the heap dump file.
			There is a chance that the garbage collection was not performed, for example if the
			object to be allocated was so huge that it was obvious to the JVM that no amount of garbage collection
			could free enough space, or if the heap dump was triggered by another event.</p>
			<p>Sometimes however, it is interesting to investigate these unreachable objects. For example if the application
			is spending a lot of time garbage collecting then it may be allocating and discarding more objects
			than is sensible. The types of the objects which could be discarded at the next garbage collection
			gives a clue as to which temporary objects the application is causing to be allocated.
			When acquiring a heap dump for this purpose using the Memory Analyzer,
			do not use the <cmdname>live=true</cmdname> option as that would discard unreachable objects
			before the heap dump is generated.</p>
		</section>
		<section>
			<title>Arguments</title>
			<p>None</p>
			<p>Invoke using either:
			<ol>
			<li>From the link on the Overview page
			</li>
			<li>From the Query Browser via <menucascade><uicontrol>Java Basics</uicontrol><uicontrol> Unreachable Objects Histogram</uicontrol></menucascade></li></ol>
			</p>
		</section>
		<section id="result">
			<title>Result</title>
			The result is a histogram table showing the class names and number of object instances
			of the unreachable objects, together with their total sizes.
			This histogram has no object graph behind it (unreachable objects are removed during the parsing of the heap dump,
			only class names are stored). 
			Thus it is not possible to see e.g. a list of references for a particular unreachable object.
			<image href="unreachable_histogram.png">
					<alt>Table displaying the unreachable objects.</alt>
			</image>
		</section>
		<section>
			<title>Continued analysis</title>
			<p>If more information about the unreachable objects is required then the following steps
			can include the objects in the snapshot.</p>
			<ol>
			<li>Close the snapshot
			</li>
			<li>Select the heap dump using <menucascade><uicontrol>Window</uicontrol><uicontrol>Heap Dump History</uicontrol></menucascade>
			mouse button 2, <menucascade><uicontrol>Delete Index Files</uicontrol></menucascade>
			</li>
			<li>Select 'Keep unreachable objects' using <menucascade><uicontrol>Window</uicontrol><uicontrol>Preferences</uicontrol>
			<uicontrol>Memory Analyzer</uicontrol></menucascade></li>
			<li>Reopen the heap dump, which will reparse the heap dump.</li>
			<li>Select the <menucascade><uicontrol>Java Basics</uicontrol><uicontrol>GC Roots</uicontrol></menucascade>
			query.</li>
			<li>Select the 'Unreachable Objects' row.</li>
			<li>Run the 'Show Retained Set' query on that row.</li>
			</ol>
			This will show a histogram of all the objects which normally would be unreachable and would be garbage collected
			at the next opportunity. As these objects are now in the snapshot then they can be inspected in more detail.
		</section>
	</refbody>
	<related-links>
		<link href="../../concepts/reachability.dita" />
		<link href="../../concepts/gcroots.dita" />
		<link href="../../tasks/configure_mat.dita" />
		<link href="../../tasks/acquiringheapdump.dita" />
		<link href="../../reference/inspections/retained_set.dita" />
	</related-links>
</reference>