plugins/org.eclipse.mat.ui.help/tasks/configure_mat.dita - mat/org.eclipse.mat - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!--
     Copyright (c) 2008, 2023 SAP AG and IBM Corporation.
     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
         IBM Corporation - preference page and OQL
  -->
 <!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd" >
 <task id="task_configure_mat" xml:lang="en-us">
 	<title>Memory Analyzer Configuration</title>
 	<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>

 	<taskbody>
 		<context>
 			<p>
 				Well, analyzing big heap dumps can also require more heap space.
 				Give it
 				some more memory (possible by running on a 64-bit machine):
 			</p>

 			<codeph>MemoryAnalyzer.exe -vmargs -Xmx4g</codeph>

 			<p>Alternatively, edit the MemoryAnalyzer.ini to
 				contain:</p>

 			<p>
 				<codeblock>-vmargs
 -Xmx4g</codeblock>
 			</p>

 			<p>
 				For more details, check out the section
 				<xref format="html" scope="peer"
 					href="http://help.eclipse.org/topic/org.eclipse.platform.doc.user/tasks/running_eclipse.htm">Running Eclipse</xref>
 				in the Help Center. It also contains more details if you are running
 				on Mac OS X.
 			</p>

 			<p>If you are running the Memory Analyzer inside your Eclipse SDK,
 				you need to edit the eclipse.ini file.</p>

 			<p>The memory intensive parts are the parsing of the dump and building
 				of the dominator tree. Try parsing the heap
 				dump from the command line, perhaps on a bigger machine. The dumps
 				and index files can then be copied to a more convenient machine.
 				Once the dump has been parsed, it usually can
 				be opened with less memory in the GUI.
 				As a rough estimate if the number of objects is N and the number of
 				classes C, it might take at least T bytes to parse and build the dominator tree
 				where:
 				<codeph>T &#8776; N * 28.25 + C * 1000 + P</codeph>
 				P is the space used by the DTFJ or HPROF parsers. For a PHD file, the space could be:
 				<codeph>P &#8776; C * 1000</codeph>
 				Memory Analyzer uses additional memory for caching index files, so
 				performance will be better if there is more memory available than the minimum
 				required to parse a dump.
 				</p>
 				<p>Memory Analyzer has an architectural limit of 2<sup>31</sup> - 3 objects,
 				a current limit of 2<sup>31</sup> - 9 = 2,147,483,639 objects, but has not been
 				tested with that many objects. The current record is a heap dump file of 159Gbytes
 				containing 2,041,300,061 objects, which was opened with Memory Analyzer running
 				with a 172Gbyte heap.
 				Exceeding the limit can result in an exception such as
 				<systemoutput>java.lang.OutOfMemoryError: Requested length of new long[2,147,483,640] exceeds limit of 2,147,483,639</systemoutput>.
 				See <xref format="dita" href="#task_configure_mat/discard">enable discard</xref>
 				for options to work around this limit.</p>

 			<p>The preference page is opened via a menu option.
 				<menucascade>
 					<uicontrol>Window</uicontrol>
 					<uicontrol>Preferences</uicontrol>
 				</menucascade>
 			</p>
 			<p id="preferences">The preferences page allows various aspects of Memory Analyzer to be controlled.
 			Use the <xref format="html" scope="peer" href="javascript:executeCommand(%22org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.mat.ui.Preferences)%22)">
 			<b>Preferences</b></xref> dialog pages to set how you want Eclipse Memory Analyzer to operate. The menu path is
 				<menucascade>
 					<uicontrol>Window</uicontrol>
 					<uicontrol>Preferences</uicontrol>
 				</menucascade>
 			on Windows and Linux -
 			on macOS the Preferences can be found in the "App" menu.
 			Some of the preferences can also be controlled from the command line in
 			<xref type="task" href="batch.dita">batch mode</xref>.
 			<image href="../mimes/preferences.png">
 				<alt>preferences page showing general options with DTFJ subpage</alt>
 			</image>
 			<dl>
 			<dlentry>
 				<dt>Keep unreachable objects</dt>
 				<dd>Objects that appear unreachable from GC roots are not discarded in an early stage of
 				Memory Analyzer processing, but are retained for further analysis.</dd>
 			</dlentry>
 			<dlentry>
 				<dt>Hide the getting started wizard</dt>
 				<dd>Controls whether to display a wizard for leak suspects, top components after opening
 				a snapshot.</dd>
 			</dlentry>
 			<dlentry>
 				<dt>Hide popup query help</dt>
 				<dd>Do not display the help panel underneath the query wizard, unless F1 or the help button
 				is pressed.</dd>
 			</dlentry>
 			<dlentry>
 				<dt>Hide the Welcome screen on launch</dt>
 				<dd>The welcome page has the 'Overview' and 'Tutorials' tabs and the 'Workbench' button.
 				The welcome page is closed by going to the workbench.
 				Selecting this option means that when Memory Analyzer is started the workbench is displayed
 				first.
 				The welcome page can be reopened from the workbench by:
 					<menucascade>
 						<uicontrol>Help</uicontrol>
 						<uicontrol>Welcome</uicontrol>
 					</menucascade>
 				</dd>
 			</dlentry>
 			<dlentry>
 				<dt>Bytes Display</dt>
 				<dd>
 					<p>
 						There is a option (from MAT 1.5 onwards) to display bytes in B, KB, MB, GB, or Smart formats.
 						The default is to always display in Bytes format to match the previous MAT behavior and not cause any confusion.
 						The option can be changed in the Eclipse preference dialog or using <option>-Dbytes_display=(bytes|kilobytes|megabytes|gigabytes|smart)</option>.
 					</p>
 					<image href="../mimes/size_units_cfg.png">
 						<alt>Preferences dialog to configure size units</alt>
 					</image>
 					<dl>
 						<dlentry>
 							<dt>Bytes (B)</dt>
 							<dd>Memory counted in single bytes</dd>
 						</dlentry>
 						<dlentry>
 							<dt>Kilobytes (KB)</dt>
 							<dd>Memory counted in units of 1,024 bytes</dd>
 						</dlentry>
 						<dlentry>
 							<dt>Megabytes (MB)</dt>
 							<dd>Memory counted in units of 1,048,576 bytes</dd>
 						</dlentry>
 						<dlentry>
 							<dt>Gigabytes (GB)</dt>
 							<dd>Memory counted in units of 1,073,741,824‬ bytes</dd>
 						</dlentry>
 						<dlentry>
 							<dt>Smart</dt>
 							<dd>In Smart mode, if the value is a gigabyte or more, display in gigabytes; similarly for megabytes and kilobytes; otherwise, display in bytes.
 								<image href="../mimes/size_units_sample.png">
 									<alt>A histogram showing entries with different size units</alt>
 								</image>
 							</dd>
 						</dlentry>
 					</dl>
 				</dd>
 			</dlentry>
 			<dlentry>
 				<dt>Expanded entries in tables and trees</dt>
 				<dd>There can be many rows in the tables and trees produced by queries.
 				This controls the number of new entries displayed after a double click
 				on the totals row, or for the <menucascade><uicontrol>Next <option>N</option>n</uicontrol></menucascade> menu item
 				or for expanding a tree entry
 				or for the number of rows for a table or tree in a report,
 				if not set by the <xref format="html" scope="peer" href="../doc/org/eclipse/mat/report/Params.Rendering.html#LIMIT"><parmname>limit</parmname></xref>.
 				</dd>
 			</dlentry>
 			<dlentry id="discard">
 				<dt>Enable discard (experimental)</dt>
 				<dd>
 					<p>
 					Sometimes a heap dump is generated with more objects than Memory Analyzer
 					can handle, either from lack of heap to run Memory Analyzer itself, or because the number
 					exceeds the Memory Analyzer limit of 2,147,483,639 objects.
 					This option controls some experimental settings to help analyze
 					such huge dumps, by purposely discarding objects in the original
 					heap dump.
 					</p>
 					<p>The discarded objects are counted in the
 					<xref format="dita" href="../reference/inspections/unreachable_objects.dita">
 					unreachable objects histogram</xref> together with any unreachable objects
 					discarded by Memory Analyzer after parsing but before building the dominator tree.
 					</p>
 					<p>The discarded objects are not indexed, so are not part of the dominator tree
 					nor are they counted as part of the retained size. As they are not indexed they
 					will not appear in the <xref format="dita" href="../reference/querymatrix.dita#ref_querymatrix/list_objects">list objects</xref>
 					query.
 					Most other queries will not operate on unindexed (discarded) objects.
 					Sometimes it is possible to view them. The inspector view can display
 					unindexed objects in the attributes and statics tabs.
 					It is possible to 'Go Into' an unindexed object from the inspector view, and
 					'Go Back' to the previous object.
 					Unindexed objects do not have GC root information, so in that
 					position in the inspector view is displayed a
 					<image href="../mimes/message_warning.png">
 						<alt>yellow warning triangle icon</alt>
 					</image>
 					warning triangle
 					and the message <msgph>Unindexed</msgph>.
 					Names resolvers can use the values of unindexed objects to find a displayable
 					name for an object. This will be displayed after the object address
 					in the inspector view and in the
 					<xref format="dita" href="../reference/tipsandtricks.dita#ref_tips/value_tab">Inspector View value tab</xref>.
 					</p>
 					<p>Some trial and error may be required to find suitable values of the options.
 					<ol>
 					<li>If an OutOfMemoryError still occurs on a parse then more objects need to be
 					discarded, either by increasing the discard percentage or by increasing the
 					number of types of discarded objects by changing the pattern.</li>
 					<li>If the leak is
 					not apparent from the snapshot with many discarded objects then examine
 					the unreachable objects histogram to see if any key objects have been discarded
 					and modify the discard pattern. Ideally only primitive arrays or objects which
 					just have primitive fields or refer to primitive arrays should be discarded.
 					This avoids disrupting the object graph too much.</li>
 					<li>If the types of the discarded objects look reasonable then try changing
 					which objects have been discarded, either by varying the offset (if the
 					discard percentage is not <userinput>100</userinput>) or the discard seed.</li>
 					<li>If the available heap to run Memory Analyzer is very small then try
 					discarding all of the ordinary objects by choosing <userinput>100</userinput>
 					for the discard percentage and <userinput>.*</userinput> to match all
 					object types. The resulting snapshot will not be useful for finding leaks,
 					but the unreachable object histogram will show the types of the objects
 					taking most of the heap space, and might give a hint as to the problem.</li>
 					</ol>
 					See <xref format="dita" href="batch.dita#task_batch/discard">
 					batch mode discard options</xref> for controlling discard in batch
 					mode.
 					See <xref format="dita" href="../reference/oqlsyntaxfrom.dita#ref_oqlsyntaxfrom/unindexed">
 					OQL FROM clauses</xref> for how to use OQL with unindexed objects.
 					</p>
 					<note>This feature is experimental and is subject to change
 					or removal. Please respond on the
 					<xref format="html" scope="peer"
 						href="http://www.eclipse.org/forums/index.php/f/186/">
 					Memory Analyzer forum</xref> if you try it and
 					find it useful or have suggestions.</note>
 			<dl>
 			<dlentry>
 				<dt>Discard percentage</dt>
 				<dd>
 					A number between <userinput>0</userinput> and <userinput>100</userinput>, treated as a percentage.
 					Approximately this percentage of ordinary objects
 					matching the discard pattern will be
 					discarded by the HPROF or DTFJ parsers.
 				</dd>
 			</dlentry>
 			<dlentry>
 				<dt>Discard pattern</dt>
 				<dd>
 					Only objects with a class name matching this regular expression
 					will be discarded. It is best to chose objects of a type which
 					does not link to other objects, such as primitive arrays, or
 					objects which just link to other such objects. This avoids breaking
 					the object graph too much, and gives a hope that the leak
 					analysis will find the problem.
 					The default pattern of
 					<userinput>char\[\]|java\.lang\.String</userinput> discards
 					character arrays and Strings. For Java 9 heap dumps with
 					compact strings based on byte arrays then
 					<userinput>byte\[\]|java\.lang\.String</userinput> may be
 					more appropriate.
 				</dd>
 			</dlentry>
 			<dlentry>
 				<dt>Discard offset</dt>
 				<dd>
 					A number between <userinput>0</userinput> and <userinput>99</userinput>.
 					This allows different objects to be discarded from two different
 					parses of the same heap dump. This might be useful to allow objects
 					which have been discarded from one snapshot to be found in the
 					others. For example with a discard percentage of <userinput>25</userinput>, then offsets
 					chosen from <userinput>0</userinput>,<userinput>25</userinput>,<userinput>50</userinput>,<userinput>75</userinput> in successive parses will discard
 					4 distinct sets of objects.
 					With a discard percentage of <userinput>80</userinput>, and offsets of
 					<userinput>0</userinput>,
 					<userinput>20</userinput>,
 					<userinput>40</userinput>,
 					<userinput>60</userinput>,
 					<userinput>80</userinput>
 					in successive parses, will have each object present in one of
 					those five snapshots.
 				</dd>
 			</dlentry>
 			<dlentry>
 				<dt>Discard seed</dt>
 				<dd>
 					This controls the starting point of the random number generator
 					used to decide whether to discard particular objects. If after
 					discarding objects the leak cannot be found then rerunning the
 					parse with a different seed would discard some different objects
 					and might show the leak better.
 				</dd>
 			</dlentry>
 			</dl>
 				</dd>
 			</dlentry>
 			<dlentry id="dtfj_preferences">
 				<dt>
 					<menucascade>
 						<uicontrol>Memory Analyzer</uicontrol>
 						<uicontrol>DTFJ Parser</uicontrol>
 						<uicontrol>Stack frames</uicontrol>
 					</menucascade>
 				</dt>
 				<dd>
 					Normally stack frames are just shown in the Thread overview and stacks query.
 					This option allows stack frames to be treated as objects which are then visible like any other Java object in a Memory Analyzer view.
 					<dl>
 					<dlentry>
 					<dt>Normal
 					</dt>
 					<dd>Stack frames are just shown in the Thread overview and stacks query.
 					</dd>
 					</dlentry>
 					<dlentry>
 					<dt>Only stack frames as pseudo-objects
 					</dt>
 					<dd>
 					Stack frames are of type <codeph>&lt;stack frame&gt;</codeph>, size 0, with method names and source file
 and line numbers via fields and a name resolver.
 					<p>This is useful when looking at paths to and from objects via local variables as the stack frames are visible in
 					the paths to GC roots queries.</p>
 					</dd>
 					</dlentry>
 					<dlentry>
 					<dt>Stack frames as pseudo-objects and running methods as pseudo-classes
 					</dt>
 					<dd>Stack frames of are of type <codeph>packageName.className.methodName(Signature)ReturnType</codeph> extending <codeph>&lt;method&gt;</codeph> representing the method being executed,
 of size the stack frame size, with source file and line number via fields and a name resolver,
 and those methods are pseudo-classes of type <codeph>&lt;method type&gt;</codeph> of size 0.
 					<p>This can be useful to find out which methods are currently running and how much stack space they take up.
 					To examine running methods then take the histogram view, filter by '\(', then sort by instances or instance size.
 					</p>
 					</dd>
 					</dlentry>
 					<dlentry>
 					<dt>Stack frames as pseudo-objects and all methods as pseudo-classes
 					</dt>
 					<dd>Stack frames of are of type <codeph>packageName.className.methodName(Signature)ReturnType</codeph> extending <codeph>&lt;method&gt;</codeph>codeph> representing the method being executed,
 of size the stack frame size, with source file and line number via fields and a name resolver,
 and all methods are pseudo-classes of type <codeph>&lt;method type&gt;</codeph> of size based on the JITted and byte code sizes. The method sizes are then not part of the class size.
 					<p>This can be useful to find out which methods have large JITted or byte code sizes. They can be viewed by going to the histogram view,
 					then selecting <codeph>&lt;method type&gt;</codeph> and listing objects.
 					</p>
 					</dd>
 					</dlentry>
 					</dl>

 				</dd>
 			</dlentry>
 			<dlentry>
 				<dt>
 					<menucascade>
 						<uicontrol>Memory Analyzer</uicontrol>
 						<uicontrol>DTFJ Parser</uicontrol>
 						<uicontrol>Suppress Class native memory size calculations (IBM system dumps)</uicontrol>
 					</menucascade>
 				</dt>
 				<dd>
 					By default, when MAT parses IBM system dumps, the size of classes includes some of the amount of native memory in the Java process (but outside of the Java heap) which is related to those classes such as native memory for bytecode and JIT compiled code for the class methods. Check this option to disable this calculation and only report Java heap usage.
 				</dd>
 			</dlentry>
 					<dlentry id="hprof_preferences">
 						<dt>
 							<menucascade>
 								<uicontrol>Memory Analyzer</uicontrol>
 								<uicontrol>HPROF Parser</uicontrol>
 								<uicontrol>Parser Strictness</uicontrol>
 							</menucascade>
 						</dt>
 						<dd>
 							By default, the HPROF parser runs in strict mode. This means that
 							any deviation in the file from the
 							<xref format="html" scope="external"
 								href="http://java.net/downloads/heap-snapshot/hprof-binary-format.html">HPROF specification</xref>
 							is treated as a severe error, an exception is thrown, and dump
 							processing stops. There is one exception to this rule which is
 							that we can reliably workaround the observed issue in
 							<xref format="html" scope="external"
 								href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=404679">bug #404679</xref>
 							.

 							<p>This
 								is a change in behavior from previous
 								releases when a
 								warning
 								was
 								shown in the error log and processing
 								continued. This
 								default
 								change was made to alert the user to a
 								potential problem
 								either
 								with the file itself or a bug in the JVM
 								or in MAT. You may
 								choose
 								to change the strictness of the parser:</p>
 							<dl>
 								<dlentry>
 									<dt>Strict
 									</dt>
 									<dd>Default. Any deviation from the HPROF specification causes
 										an exception to be thrown and processing to stop (with the
 										exception of
 										<xref format="html" scope="external"
 								href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=404679">bug #404679</xref>
 										.) This option may be specified on the
 										command line with -DhprofStrictnessStop=true
 									</dd>
 								</dlentry>
 								<dlentry>
 									<dt>Warning
 									</dt>
 									<dd>
 										Choose this option to revert to the old behavior where a
 										warning is printed to the error log and processing continues.
 										This option is not recommended because the warning is probably
 										a sign of a problem. Please open a bug report instead. This
 										option may be specified on the
 										command line with
 										-DhprofStrictnessWarning=true
 									</dd>
 								</dlentry>
 							</dl>

 						</dd>
 					</dlentry>
 			<dlentry>
 				<dt>
 					<menucascade>
 						<uicontrol>Memory Analyzer</uicontrol>
 						<uicontrol>HPROF Parser</uicontrol>
 						<uicontrol>Include additional references from class objects
 						found in a HPROF file.</uicontrol>
 					</menucascade>
 				</dt>
 				<dd>
 					Class objects have hidden references to the other objects.
 					These include the signers and the protection domain.
 					Memory Analyzer can include them via pseudo-fields named
 					<parmname>&lt;signers&gt;</parmname> and <parmname>&lt;protectionDomain&gt;</parmname>.
 					Sometimes it might be useful to see these references, and this
 					option allows that.
 				</dd>
 			</dlentry>
 			<dlentry>
 				<dt>
 					<menucascade>
 						<uicontrol>General</uicontrol>
 						<uicontrol>Appearance</uicontrol>
 						<uicontrol>Colors and Fonts</uicontrol>
 						<uicontrol>Memory Analyzer</uicontrol>
 						<uicontrol>OQL comment color</uicontrol>
 					</menucascade>
 				</dt>
 				<dd>Modify the color of comments in the Object Query Language (OQL) studio.</dd>
 			</dlentry>
 			<dlentry>
 				<dt>
 					<menucascade>
 						<uicontrol>General</uicontrol>
 						<uicontrol>Appearance</uicontrol>
 						<uicontrol>Colors and Fonts</uicontrol>
 						<uicontrol>Memory Analyzer</uicontrol>
 						<uicontrol>OQL keyword color</uicontrol>
 					</menucascade>
 				</dt>
 				<dd>Modify the color of keywords in the Object Query Language (OQL) studio.</dd>
 			</dlentry>
 			</dl>
 			</p>
 		</context>
 	</taskbody>
 </task>
	<?xml version="1.0" encoding="UTF-8"?>
	<!--
	Copyright (c) 2008, 2023 SAP AG and IBM Corporation.
	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
	IBM Corporation - preference page and OQL
	-->
	<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd" >
	<task id="task_configure_mat" xml:lang="en-us">
	<title>Memory Analyzer Configuration</title>
	<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>

	<taskbody>
	<context>
	<p>
	Well, analyzing big heap dumps can also require more heap space.
	Give it
	some more memory (possible by running on a 64-bit machine):
	</p>

	<codeph>MemoryAnalyzer.exe -vmargs -Xmx4g</codeph>

	<p>Alternatively, edit the MemoryAnalyzer.ini to
	contain:</p>

	<p>
	<codeblock>-vmargs
	-Xmx4g</codeblock>
	</p>

	<p>
	For more details, check out the section
	<xref format="html" scope="peer"
	href="http://help.eclipse.org/topic/org.eclipse.platform.doc.user/tasks/running_eclipse.htm">Running Eclipse</xref>
	in the Help Center. It also contains more details if you are running
	on Mac OS X.
	</p>

	<p>If you are running the Memory Analyzer inside your Eclipse SDK,
	you need to edit the eclipse.ini file.</p>

	<p>The memory intensive parts are the parsing of the dump and building
	of the dominator tree. Try parsing the heap
	dump from the command line, perhaps on a bigger machine. The dumps
	and index files can then be copied to a more convenient machine.
	Once the dump has been parsed, it usually can
	be opened with less memory in the GUI.
	As a rough estimate if the number of objects is N and the number of
	classes C, it might take at least T bytes to parse and build the dominator tree
	where:
	<codeph>T ≈ N * 28.25 + C * 1000 + P</codeph>
	P is the space used by the DTFJ or HPROF parsers. For a PHD file, the space could be:
	<codeph>P ≈ C * 1000</codeph>
	Memory Analyzer uses additional memory for caching index files, so
	performance will be better if there is more memory available than the minimum
	required to parse a dump.
	</p>
	<p>Memory Analyzer has an architectural limit of 2<sup>31</sup> - 3 objects,
	a current limit of 2<sup>31</sup> - 9 = 2,147,483,639 objects, but has not been
	tested with that many objects. The current record is a heap dump file of 159Gbytes
	containing 2,041,300,061 objects, which was opened with Memory Analyzer running
	with a 172Gbyte heap.
	Exceeding the limit can result in an exception such as
	<systemoutput>java.lang.OutOfMemoryError: Requested length of new long[2,147,483,640] exceeds limit of 2,147,483,639</systemoutput>.
	See <xref format="dita" href="#task_configure_mat/discard">enable discard</xref>
	for options to work around this limit.</p>

	<p>The preference page is opened via a menu option.
	<menucascade>
	<uicontrol>Window</uicontrol>
	<uicontrol>Preferences</uicontrol>
	</menucascade>
	</p>
	<p id="preferences">The preferences page allows various aspects of Memory Analyzer to be controlled.
	Use the <xref format="html" scope="peer" href="javascript:executeCommand(%22org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.mat.ui.Preferences)%22)">
	<b>Preferences</b></xref> dialog pages to set how you want Eclipse Memory Analyzer to operate. The menu path is
	<menucascade>
	<uicontrol>Window</uicontrol>
	<uicontrol>Preferences</uicontrol>
	</menucascade>
	on Windows and Linux -
	on macOS the Preferences can be found in the "App" menu.
	Some of the preferences can also be controlled from the command line in
	<xref type="task" href="batch.dita">batch mode</xref>.
	<image href="../mimes/preferences.png">
	<alt>preferences page showing general options with DTFJ subpage</alt>
	</image>
	<dl>
	<dlentry>
	<dt>Keep unreachable objects</dt>
	<dd>Objects that appear unreachable from GC roots are not discarded in an early stage of
	Memory Analyzer processing, but are retained for further analysis.</dd>
	</dlentry>
	<dlentry>
	<dt>Hide the getting started wizard</dt>
	<dd>Controls whether to display a wizard for leak suspects, top components after opening
	a snapshot.</dd>
	</dlentry>
	<dlentry>
	<dt>Hide popup query help</dt>
	<dd>Do not display the help panel underneath the query wizard, unless F1 or the help button
	is pressed.</dd>
	</dlentry>
	<dlentry>
	<dt>Hide the Welcome screen on launch</dt>
	<dd>The welcome page has the 'Overview' and 'Tutorials' tabs and the 'Workbench' button.
	The welcome page is closed by going to the workbench.
	Selecting this option means that when Memory Analyzer is started the workbench is displayed
	first.
	The welcome page can be reopened from the workbench by:
	<menucascade>
	<uicontrol>Help</uicontrol>
	<uicontrol>Welcome</uicontrol>
	</menucascade>
	</dd>
	</dlentry>
	<dlentry>
	<dt>Bytes Display</dt>
	<dd>
	<p>
	There is a option (from MAT 1.5 onwards) to display bytes in B, KB, MB, GB, or Smart formats.
	The default is to always display in Bytes format to match the previous MAT behavior and not cause any confusion.
	The option can be changed in the Eclipse preference dialog or using <option>-Dbytes_display=(bytes\|kilobytes\|megabytes\|gigabytes\|smart)</option>.
	</p>
	<image href="../mimes/size_units_cfg.png">
	<alt>Preferences dialog to configure size units</alt>
	</image>
	<dl>
	<dlentry>
	<dt>Bytes (B)</dt>
	<dd>Memory counted in single bytes</dd>
	</dlentry>
	<dlentry>
	<dt>Kilobytes (KB)</dt>
	<dd>Memory counted in units of 1,024 bytes</dd>
	</dlentry>
	<dlentry>
	<dt>Megabytes (MB)</dt>
	<dd>Memory counted in units of 1,048,576 bytes</dd>
	</dlentry>
	<dlentry>
	<dt>Gigabytes (GB)</dt>
	<dd>Memory counted in units of 1,073,741,824‬ bytes</dd>
	</dlentry>
	<dlentry>
	<dt>Smart</dt>
	<dd>In Smart mode, if the value is a gigabyte or more, display in gigabytes; similarly for megabytes and kilobytes; otherwise, display in bytes.
	<image href="../mimes/size_units_sample.png">
	<alt>A histogram showing entries with different size units</alt>
	</image>
	</dd>
	</dlentry>
	</dl>
	</dd>
	</dlentry>
	<dlentry>
	<dt>Expanded entries in tables and trees</dt>
	<dd>There can be many rows in the tables and trees produced by queries.
	This controls the number of new entries displayed after a double click
	on the totals row, or for the <menucascade><uicontrol>Next <option>N</option>n</uicontrol></menucascade> menu item
	or for expanding a tree entry
	or for the number of rows for a table or tree in a report,
	if not set by the <xref format="html" scope="peer" href="../doc/org/eclipse/mat/report/Params.Rendering.html#LIMIT"><parmname>limit</parmname></xref>.
	</dd>
	</dlentry>
	<dlentry id="discard">
	<dt>Enable discard (experimental)</dt>
	<dd>
	<p>
	Sometimes a heap dump is generated with more objects than Memory Analyzer
	can handle, either from lack of heap to run Memory Analyzer itself, or because the number
	exceeds the Memory Analyzer limit of 2,147,483,639 objects.
	This option controls some experimental settings to help analyze
	such huge dumps, by purposely discarding objects in the original
	heap dump.
	</p>
	<p>The discarded objects are counted in the
	<xref format="dita" href="../reference/inspections/unreachable_objects.dita">
	unreachable objects histogram</xref> together with any unreachable objects
	discarded by Memory Analyzer after parsing but before building the dominator tree.
	</p>
	<p>The discarded objects are not indexed, so are not part of the dominator tree
	nor are they counted as part of the retained size. As they are not indexed they
	will not appear in the <xref format="dita" href="../reference/querymatrix.dita#ref_querymatrix/list_objects">list objects</xref>
	query.
	Most other queries will not operate on unindexed (discarded) objects.
	Sometimes it is possible to view them. The inspector view can display
	unindexed objects in the attributes and statics tabs.
	It is possible to 'Go Into' an unindexed object from the inspector view, and
	'Go Back' to the previous object.
	Unindexed objects do not have GC root information, so in that
	position in the inspector view is displayed a
	<image href="../mimes/message_warning.png">
	<alt>yellow warning triangle icon</alt>
	</image>
	warning triangle
	and the message <msgph>Unindexed</msgph>.
	Names resolvers can use the values of unindexed objects to find a displayable
	name for an object. This will be displayed after the object address
	in the inspector view and in the
	<xref format="dita" href="../reference/tipsandtricks.dita#ref_tips/value_tab">Inspector View value tab</xref>.
	</p>
	<p>Some trial and error may be required to find suitable values of the options.
	<ol>
	<li>If an OutOfMemoryError still occurs on a parse then more objects need to be
	discarded, either by increasing the discard percentage or by increasing the
	number of types of discarded objects by changing the pattern.</li>
	<li>If the leak is
	not apparent from the snapshot with many discarded objects then examine
	the unreachable objects histogram to see if any key objects have been discarded
	and modify the discard pattern. Ideally only primitive arrays or objects which
	just have primitive fields or refer to primitive arrays should be discarded.
	This avoids disrupting the object graph too much.</li>
	<li>If the types of the discarded objects look reasonable then try changing
	which objects have been discarded, either by varying the offset (if the
	discard percentage is not <userinput>100</userinput>) or the discard seed.</li>
	<li>If the available heap to run Memory Analyzer is very small then try
	discarding all of the ordinary objects by choosing <userinput>100</userinput>
	for the discard percentage and <userinput>.*</userinput> to match all
	object types. The resulting snapshot will not be useful for finding leaks,
	but the unreachable object histogram will show the types of the objects
	taking most of the heap space, and might give a hint as to the problem.</li>
	</ol>
	See <xref format="dita" href="batch.dita#task_batch/discard">
	batch mode discard options</xref> for controlling discard in batch
	mode.
	See <xref format="dita" href="../reference/oqlsyntaxfrom.dita#ref_oqlsyntaxfrom/unindexed">
	OQL FROM clauses</xref> for how to use OQL with unindexed objects.
	</p>
	<note>This feature is experimental and is subject to change
	or removal. Please respond on the
	<xref format="html" scope="peer"
	href="http://www.eclipse.org/forums/index.php/f/186/">
	Memory Analyzer forum</xref> if you try it and
	find it useful or have suggestions.</note>
	<dl>
	<dlentry>
	<dt>Discard percentage</dt>
	<dd>
	A number between <userinput>0</userinput> and <userinput>100</userinput>, treated as a percentage.
	Approximately this percentage of ordinary objects
	matching the discard pattern will be
	discarded by the HPROF or DTFJ parsers.
	</dd>
	</dlentry>
	<dlentry>
	<dt>Discard pattern</dt>
	<dd>
	Only objects with a class name matching this regular expression
	will be discarded. It is best to chose objects of a type which
	does not link to other objects, such as primitive arrays, or
	objects which just link to other such objects. This avoids breaking
	the object graph too much, and gives a hope that the leak
	analysis will find the problem.
	The default pattern of
	<userinput>char\[\]\|java\.lang\.String</userinput> discards
	character arrays and Strings. For Java 9 heap dumps with
	compact strings based on byte arrays then
	<userinput>byte\[\]\|java\.lang\.String</userinput> may be
	more appropriate.
	</dd>
	</dlentry>
	<dlentry>
	<dt>Discard offset</dt>
	<dd>
	A number between <userinput>0</userinput> and <userinput>99</userinput>.
	This allows different objects to be discarded from two different
	parses of the same heap dump. This might be useful to allow objects
	which have been discarded from one snapshot to be found in the
	others. For example with a discard percentage of <userinput>25</userinput>, then offsets
	chosen from <userinput>0</userinput>,<userinput>25</userinput>,<userinput>50</userinput>,<userinput>75</userinput> in successive parses will discard
	4 distinct sets of objects.
	With a discard percentage of <userinput>80</userinput>, and offsets of
	<userinput>0</userinput>,
	<userinput>20</userinput>,
	<userinput>40</userinput>,
	<userinput>60</userinput>,
	<userinput>80</userinput>
	in successive parses, will have each object present in one of
	those five snapshots.
	</dd>
	</dlentry>
	<dlentry>
	<dt>Discard seed</dt>
	<dd>
	This controls the starting point of the random number generator
	used to decide whether to discard particular objects. If after
	discarding objects the leak cannot be found then rerunning the
	parse with a different seed would discard some different objects
	and might show the leak better.
	</dd>
	</dlentry>
	</dl>
	</dd>
	</dlentry>
	<dlentry id="dtfj_preferences">
	<dt>
	<menucascade>
	<uicontrol>Memory Analyzer</uicontrol>
	<uicontrol>DTFJ Parser</uicontrol>
	<uicontrol>Stack frames</uicontrol>
	</menucascade>
	</dt>
	<dd>
	Normally stack frames are just shown in the Thread overview and stacks query.
	This option allows stack frames to be treated as objects which are then visible like any other Java object in a Memory Analyzer view.
	<dl>
	<dlentry>
	<dt>Normal
	</dt>
	<dd>Stack frames are just shown in the Thread overview and stacks query.
	</dd>
	</dlentry>
	<dlentry>
	<dt>Only stack frames as pseudo-objects
	</dt>
	<dd>
	Stack frames are of type <codeph><stack frame></codeph>, size 0, with method names and source file
	and line numbers via fields and a name resolver.
	<p>This is useful when looking at paths to and from objects via local variables as the stack frames are visible in
	the paths to GC roots queries.</p>
	</dd>
	</dlentry>
	<dlentry>
	<dt>Stack frames as pseudo-objects and running methods as pseudo-classes
	</dt>
	<dd>Stack frames of are of type <codeph>packageName.className.methodName(Signature)ReturnType</codeph> extending <codeph><method></codeph> representing the method being executed,
	of size the stack frame size, with source file and line number via fields and a name resolver,
	and those methods are pseudo-classes of type <codeph><method type></codeph> of size 0.
	<p>This can be useful to find out which methods are currently running and how much stack space they take up.
	To examine running methods then take the histogram view, filter by '\(', then sort by instances or instance size.
	</p>
	</dd>
	</dlentry>
	<dlentry>
	<dt>Stack frames as pseudo-objects and all methods as pseudo-classes
	</dt>
	<dd>Stack frames of are of type <codeph>packageName.className.methodName(Signature)ReturnType</codeph> extending <codeph><method></codeph>codeph> representing the method being executed,
	of size the stack frame size, with source file and line number via fields and a name resolver,
	and all methods are pseudo-classes of type <codeph><method type></codeph> of size based on the JITted and byte code sizes. The method sizes are then not part of the class size.
	<p>This can be useful to find out which methods have large JITted or byte code sizes. They can be viewed by going to the histogram view,
	then selecting <codeph><method type></codeph> and listing objects.
	</p>
	</dd>
	</dlentry>
	</dl>

	</dd>
	</dlentry>
	<dlentry>
	<dt>
	<menucascade>
	<uicontrol>Memory Analyzer</uicontrol>
	<uicontrol>DTFJ Parser</uicontrol>
	<uicontrol>Suppress Class native memory size calculations (IBM system dumps)</uicontrol>
	</menucascade>
	</dt>
	<dd>
	By default, when MAT parses IBM system dumps, the size of classes includes some of the amount of native memory in the Java process (but outside of the Java heap) which is related to those classes such as native memory for bytecode and JIT compiled code for the class methods. Check this option to disable this calculation and only report Java heap usage.
	</dd>
	</dlentry>
	<dlentry id="hprof_preferences">
	<dt>
	<menucascade>
	<uicontrol>Memory Analyzer</uicontrol>
	<uicontrol>HPROF Parser</uicontrol>
	<uicontrol>Parser Strictness</uicontrol>
	</menucascade>
	</dt>
	<dd>
	By default, the HPROF parser runs in strict mode. This means that
	any deviation in the file from the
	<xref format="html" scope="external"
	href="http://java.net/downloads/heap-snapshot/hprof-binary-format.html">HPROF specification</xref>
	is treated as a severe error, an exception is thrown, and dump
	processing stops. There is one exception to this rule which is
	that we can reliably workaround the observed issue in
	<xref format="html" scope="external"
	href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=404679">bug #404679</xref>
	.

	<p>This
	is a change in behavior from previous
	releases when a
	warning
	was
	shown in the error log and processing
	continued. This
	default
	change was made to alert the user to a
	potential problem
	either
	with the file itself or a bug in the JVM
	or in MAT. You may
	choose
	to change the strictness of the parser:</p>
	<dl>
	<dlentry>
	<dt>Strict
	</dt>
	<dd>Default. Any deviation from the HPROF specification causes
	an exception to be thrown and processing to stop (with the
	exception of
	<xref format="html" scope="external"
	href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=404679">bug #404679</xref>
	.) This option may be specified on the
	command line with -DhprofStrictnessStop=true
	</dd>
	</dlentry>
	<dlentry>
	<dt>Warning
	</dt>
	<dd>
	Choose this option to revert to the old behavior where a
	warning is printed to the error log and processing continues.
	This option is not recommended because the warning is probably
	a sign of a problem. Please open a bug report instead. This
	option may be specified on the
	command line with
	-DhprofStrictnessWarning=true
	</dd>
	</dlentry>
	</dl>

	</dd>
	</dlentry>
	<dlentry>
	<dt>
	<menucascade>
	<uicontrol>Memory Analyzer</uicontrol>
	<uicontrol>HPROF Parser</uicontrol>
	<uicontrol>Include additional references from class objects
	found in a HPROF file.</uicontrol>
	</menucascade>
	</dt>
	<dd>
	Class objects have hidden references to the other objects.
	These include the signers and the protection domain.
	Memory Analyzer can include them via pseudo-fields named
	<parmname><signers></parmname> and <parmname><protectionDomain></parmname>.
	Sometimes it might be useful to see these references, and this
	option allows that.
	</dd>
	</dlentry>
	<dlentry>
	<dt>
	<menucascade>
	<uicontrol>General</uicontrol>
	<uicontrol>Appearance</uicontrol>
	<uicontrol>Colors and Fonts</uicontrol>
	<uicontrol>Memory Analyzer</uicontrol>
	<uicontrol>OQL comment color</uicontrol>
	</menucascade>
	</dt>
	<dd>Modify the color of comments in the Object Query Language (OQL) studio.</dd>
	</dlentry>
	<dlentry>
	<dt>
	<menucascade>
	<uicontrol>General</uicontrol>
	<uicontrol>Appearance</uicontrol>
	<uicontrol>Colors and Fonts</uicontrol>
	<uicontrol>Memory Analyzer</uicontrol>
	<uicontrol>OQL keyword color</uicontrol>
	</menucascade>
	</dt>
	<dd>Modify the color of keywords in the Object Query Language (OQL) studio.</dd>
	</dlentry>
	</dl>
	</p>
	</context>
	</taskbody>
	</task>