plugins/org.eclipse.mat.ui.help/tasks/analyzingfinalizer.dita

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Copyright (c) 2008, 2010 SAP AG.
    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
   
    Contributors:
        SAP AG - initial API and implementation
 -->
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd" >
<task id="task_analyzingfinalizer" xml:lang="en-us">
	<title>Analyzing Finalizer</title>
	<prolog>
		<copyright>
			<copyryear year=""></copyryear>
			<copyrholder>
				Copyright (c) 2008, 2010 SAP AG 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>

	<taskbody>
		<context>
			<p> Finalizers are executed when the internal garbage collection
				cleans up the objects. Since you have no control over the finalizer
				execution, it is recommended not to use them. Because the memory can
				only be released when the finalize method finished, long running
				tasks in the finalizer can block the garbage collection. To get the
				finalizers overview select Finalizer Overview Query from the query
				list:</p>
			<image href="../mimes/finalizers.png">
				<alt>Finalizer overview menu option and report</alt>
			</image>
			<p>This query includes the following subqueries:</p>
			<table>
				<tgroup cols="2">
					<tbody>
						<row>
							<entry>
								<b>Finalizer in Processing</b>
							</entry>
							<entry>
								<p> Extract object currently processed by Finalizer Thread. This
									query return the currently processed object by the Finalizer
									Thread if any. The returned object can be processed for one of
									the following reasons:</p>
								<ul>
									<li>it is blocking</li>
									<li>it is long running</li>
									<li>the finalizer queue was or is still full.</li>
								</ul>
								<p> Use the finalizer queue query to check the queue.</p>
							</entry>
						</row>
						<row>
							<entry>
								<b>Ready for Finalizer Thread</b>
							</entry>
							<entry>
								<p> This query shows the objects ready for finalization in their
									processing order. Following reasons can cause a full finalizer
									queue:</p>
								<ul>
									<li> The currently processed object is blocking or long running
										(please use our finalizer in processing query to check).</li>
									<li> The application made use of too many objects with
										finalize() which are queued up in memory.</li>
								</ul>
								<p>Note: On J9 JVM-based dumps (e.g. IBM Java, OpenJ9), this
								   list shows objects waiting to be finalized and those
								   which have already been finalized and are waiting to be
								   garbage collected. This query does not provide a way to
								   differentiate the two (because DTFJ doesn't), although you may 
								   be able to differentiate based on object fields
								   (e.g. a "closed" boolean field, etc.).</p>
								<p> Additionally a class-level summary of the objects is provided</p>
							</entry>
						</row>
						<row>
							<entry>
								<b>Finalizer Thread</b>
							</entry>
							<entry> This query shows the daemon thread which performs the
								object finalizations.</entry>
						</row>
						<row>
							<entry>
								<b>Finalizer Thread Locals</b>
							</entry>
							<entry>
								<p>
									This query shows the thread locals of the daemon thread that
									performs the object finalizations. If there are any, this
									indicates miss-use in at least one of the processed finalizers
									(
									<cmdname>finalize()</cmdname>
									implemented wrong) and might cause severe problems (e.g.
									unreclaimed memory permanently hold by the finalizer thread or
									finalizer processed under useless thread locals harming
									application logic)
								</p>
							</entry>
						</row>
					</tbody>
				</tgroup>
			</table>
		</context>
	</taskbody>
</task>