plugins/org.eclipse.mat.ui.help/concepts/gcroots.dita

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Copyright (c) 2008, 2023 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 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 - updates for validation
 -->
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA 1.1 Concept//EN" "concept.dtd" >
<concept id="concept_gcroots" xml:lang="en-us">
	<title>Garbage Collection Roots</title>
	<prolog>
		<copyright>
			<copyryear year=""></copyryear>
			<copyrholder>
				Copyright (c) 2008, 2023 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 2.0
			    which accompanies this distribution, and is available at
			    https://www.eclipse.org/legal/epl-2.0/
			</copyrholder>
		</copyright>
	</prolog>
	
	<conbody>
		<p> A garbage collection root is an object that is accessible from
			outside the heap. The following reasons make an object a GC root:</p>
		<dl>
			<dlentry>
			<dt>System Class</dt><dd>Class loaded by bootstrap/system class loader. For
				example, everything from the rt.jar like
				<cmdname>java.util.*</cmdname>
				.
			</dd>
			</dlentry>
			<dlentry>
			<dt>JNI Local</dt><dd>Local variable in native code, such as user defined
				JNI code or JVM internal code.</dd>
			</dlentry>
			<dlentry>
			<dt> JNI Global</dt><dd>Global variable in native code, such as user
				defined JNI code or JVM internal code.</dd>
			</dlentry>
			<dlentry>
			<dt>Thread Block</dt><dd>Object referred to from a currently active thread block.</dd>
			</dlentry>
			<dlentry>
			<dt>Thread</dt><dd>A started, but not stopped, thread.</dd>
			</dlentry>
			<dlentry>
			<dt>Busy Monitor</dt><dd>Everything that has called
				<cmdname>wait()</cmdname>
				or
				<cmdname>notify()</cmdname>
				or that is synchronized. For example, by calling
				<cmdname>synchronized(Object)</cmdname>
				or by entering a synchronized method. Static method means class,
				non-static method means object.
			</dd>
			</dlentry>
			<dlentry>
			<dt>Java Local</dt><dd>Local variable. For example, input parameters or
				locally created objects of methods that are still in the stack of a
				thread.</dd>
			</dlentry>
			<dlentry>
			<dt>Native Stack</dt><dd>In or out parameters in native code, such as user
				defined JNI code or JVM internal code. This is often the case as
				many methods have native parts and the objects handled as method
				parameters become GC roots. For example, parameters used for
				file/network I/O methods or reflection.</dd>
			</dlentry>
			<dlentry>
			<dt>Finalizable</dt><dd>An object which is in a queue awaiting its finalizer to be run.
			</dd>
			</dlentry>
			<dlentry>
			<dt>Unfinalized</dt><dd>An object which has a finalize method, but has not been finalized and
			is not yet on the finalizer queue.
			</dd>
			</dlentry>
			<dlentry>
			<dt>Unreachable</dt><dd>An object which is unreachable from any other root, but has been 
			marked as a root by MAT to retain objects which otherwise would not
			be included in the analysis.
			</dd>
			</dlentry>
			<dlentry>
			<dt>Java Stack Frame</dt><dd>A Java stack frame, holding local variables. Only generated when the
			dump is parsed with the preference set to treat Java stack frames as objects.
			</dd>
			</dlentry>
			<dlentry>
			<dt>Unknown</dt><dd>An object of unknown root type. Some dumps, such as IBM Portable Heap Dump files,
			do not have root information. For these dumps the MAT parser marks objects which are have
			no inbound references or are unreachable from any other root as roots of this type. 
			This ensures that MAT retains all the objects in the dump.
			</dd>
			</dlentry>
		</dl>
	</conbody>
</concept>