plugins/org.eclipse.mat.ui.help/reference/querymatrix.dita

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Copyright (c) 2008, 2023 SAP AG.
    All rights reserved. This program and the accompanying materials
    are made available under the terms of the Eclipse Public License 2.0
    which accompanies this distribution, and is available at
    https://www.eclipse.org/legal/epl-2.0/
    
    SPDX-License-Identifier: EPL-2.0
   
    Contributors:
        SAP AG - initial API and implementation
 -->
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd" >
<reference id="ref_querymatrix" xml:lang="en-us">
	<title>Query Matrix</title>
	<shortdesc>
		There is no exact algorithm for memory analysis. The following
		table divides existing heap dump queries by the usage
		categories.
	</shortdesc>
	<prolog>
		<copyright>
			<copyryear year=""></copyryear>
			<copyrholder>
				Copyright (c) 2008, 2023 SAP AG and others.
			    All rights reserved. This program and the accompanying materials
			    are made available under the terms of the Eclipse Public License 2.0
			    which accompanies this distribution, and is available at
			    https://www.eclipse.org/legal/epl-2.0/
			</copyrholder>
		</copyright>
	</prolog>


	<refbody>
		<section>
			<title>Overview</title>

			<simpletable relcolwidth="2* 3*" id="querymatrixoverview">

				<strow id="histogram">
					<stentry>Histogram</stentry>
					<stentry>
						Class histogram is a list of all the objects in
						the heap dump. You see the number of objects,
						shallow and retained sizes for every class. The
						sorting order of the list can be changed by
						clicking the column header. Histogram gives you
						a good starting point for further analysis.
						Histogram can be opened by pressing the toolbar
						button
						<image href="../mimes/i-histogram.png">
							<alt>
								Histogram toolbar button with three vertical bars.
							</alt>
						</image>
						or by activating the action link on the Overview
						pane. See the <xref href="../gettingstarted/basictutorial.dita#task_basictutorial/histogram">Basic Tutorial</xref>
						for more information.
					</stentry>
				</strow>
				<strow>
					<stentry id="top_consumers">Top Consumers</stentry>
					<stentry>
						Top Consumers query returns information about
						the biggest objects grouped by class, class
						loader, and package as HTML page. The total heap
						is included in the analysis.
					</stentry>
				</strow>
				<strow id="heap_dump_overview">
					<stentry>Heap Dump Overview</stentry>
					<stentry>
						<p>
							When a heap dump is opened the Overview
							editor already provides a first analysis on
							the heap dump:
						</p>
						<ul>
							<li>
								Check the size of the heap dump, how
								many object, classes, class loaders it
								has.
							</li>
							<li>Look at the biggest objects.</li>
						</ul>
						<p>
							The Heap Dump Overview report can be opened
							via the toolbar:
						</p>
						<image href="../mimes/6f9c3893.png">
							<alt>
								Heap Dump Overview menu item from Run Expert System Test drop-down menu.
							</alt>
						</image>
						<p>Overview report contains a histogram and a top consumers overview.</p>
					</stentry>
				</strow>
				<strow id="list_objects">
					<stentry>List Objects</stentry>
					<stentry>
						<p>
						This shows the selected objects in a tree view.
						With each object the class specific name of the referenced object is
						also shown, if it is a known type such as <codeph>java.lang.String</codeph>,
						<codeph>byte[]</codeph> etc.
						The suffix field shows whether the object is 
						a <xref href="../concepts/gcroots.dita">garbage collection root</xref>.
						</p>
						<p>
						The <xref href="iconassist.dita">icon</xref> shows whether the object is a
						<dl>
						<dlentry>
						<dt>
							<xref href="iconassist.dita">
							<image href="../mimes/i-arrayobject.png">
								<alt>
									Icon for an array using brackets
								</alt>
							</image>
							</xref>
						</dt>
						<dd>an array object</dd>
						</dlentry>
						<dlentry>
						<dt>
							<xref href="iconassist.dita">
							<image href="../mimes/i-classloaderobject.png">
								<alt>
									Icon for a class loader showing a jar container.
								</alt>
							</image>
							</xref>
						</dt>
						<dd>a class loader object</dd>
						</dlentry>
						<dlentry>
						<dt>
							<xref href="iconassist.dita">
							<image href="../mimes/i-classobject.png">
								<alt>
									Icon for a class object showing a letter 'C'.
								</alt>
							</image>
							</xref>
						</dt>
						<dd>a class object</dd>
						</dlentry>
						<dlentry>
						<dt>
							<xref href="iconassist.dita">
							<image href="../mimes/i-otherobject.png">
								<alt>
									An icon for a standard object as a blank
									piece of paper.
								</alt>
							</image>
							</xref>
						</dt>
						<dd>a standard object</dd>
						</dlentry>
						</dl>
						</p>
						<p>
						With the standard mode then expanding an object
						shows the outbound references in rows below
						and to the right of the object,
						indicated by
						the field name or array index as a prefix in <b>bold</b>.
						The <xref href="iconassist.dita">icons</xref> have an arrow which points down and to the right
							<xref href="iconassist.dita"> 
							<image href="../mimes/i-horefbelow.png">
								<alt>
									Icon of a piece of paper
									with an arrow at the bottom right pointing down and to the right.
								</alt>
							</image>
							</xref>
							.
						</p>
						<p>
						In inbound mode the query shows which objects point to the
						expanded object. In this mode the arrows on the <xref href="iconassist.dita">icons</xref>
						point up and to the left
							<xref href="iconassist.dita"> 
							<image href="../mimes/i-horefabove.png">
								<alt>
									Icon of a piece of paper
									with an arrow at the top left pointing up and to the left.
								</alt>
							</image>.
							</xref>
						</p>
					</stentry>
				</strow>
				<strow id="show_objects_by_class">
					<stentry>Show Objects by Class</stentry>
					<stentry>
					This works rather like the <cmdname>List objects</cmdname>
					query except that it groups objects of the same class at
					the same level into one row.
					The inspector view shows the actual class; the context menu
					allows operations on all the objects of that class in that row.
					<p>The color of the class <xref href="iconassist.dita">icon</xref> shows if all the objects in that
					row are new or not. If the <xref href="iconassist.dita">icon</xref> is 
					<xref href="iconassist.dita">
					<image href="../mimes/i-class.png">
						<alt>
							Green circle icon with a letter 'C'.
						</alt>
					</image>
					</xref>
					green
					then none of the objects have been shown further up the tree.
					If the <xref href="iconassist.dita">icon</xref> is
					<xref href="iconassist.dita">
					<image href="../mimes/i-class_old.png">
						<alt>
							Gray circle icon with a letter 'C'.
						</alt>
					</image>
					</xref>
					gray
					then all of the objects have been shown further up the tree.
					If the <xref href="iconassist.dita">icon</xref> is
					<xref href="iconassist.dita">
					<image href="../mimes/i-class_mixed.png">
						<alt>
							Circle icon with a letter 'C',
							green on the top half and gray at the bottom.
						</alt>
					</image>
					</xref>
					green and gray
					then some of the objects have been shown further up the tree.
					This can be useful when expanding the tree to see whether you
					are still finding new objects or whether they link back to
					objects you have already seen.
					</p>
					<p>This query can also operate in <parmname>inbound</parmname> mode.</p>
					</stentry>
				</strow>
			</simpletable>
		</section>
	</refbody>
</reference>