[551214] Add documentation about post-processed J9 JVM finalizer roots
Change-Id: I0029e2f5d5906b4824cd3218268f494cc50bc251
diff --git a/plugins/org.eclipse.mat.api/src/org/eclipse/mat/inspections/finalizer/annotations.properties b/plugins/org.eclipse.mat.api/src/org/eclipse/mat/inspections/finalizer/annotations.properties
index 161faa3..b11ca80 100644
--- a/plugins/org.eclipse.mat.api/src/org/eclipse/mat/inspections/finalizer/annotations.properties
+++ b/plugins/org.eclipse.mat.api/src/org/eclipse/mat/inspections/finalizer/annotations.properties
@@ -29,7 +29,12 @@
avoid finalizers. Long running tasks in the finalizer can block garbage \
collection, because the memory can only be freed after the finalize method finished.\
This query shows the the finalizer currently processed, the finalizer queue, \
-the demon finalizer thread or threads and the thread local variables.
+the demon finalizer thread or threads and the thread local variables.\n\n\
+Note: On J9 JVM-based dumps (e.g. IBM Java, OpenJ9), the Finalizer Queue 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.).
FinalizerQueueQuery.name = Finalizer Queue
FinalizerQueueQuery.help = Extract objects in the Finalizer Queue.\n\n\
@@ -41,7 +46,12 @@
Be aware that there could be many reasons for a full finalizer queue: \
the currently processed object could be blocking or long running \
(please use our finalizer in processing query to check) or the application \
-made use of too many objects with finalize() which are queueing up in memory.
+made use of too many objects with finalize() which are queueing up in memory.\n\n\
+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.).
FinalizerQueueQuery.mode.help = Whether to display the objects as a list, histogram or both.
FinalizerThreadLocalsQuery.name = Finalizer Thread Locals
diff --git a/plugins/org.eclipse.mat.ui.help/tasks/analyzingfinalizer.dita b/plugins/org.eclipse.mat.ui.help/tasks/analyzingfinalizer.dita
index 0c84902..e67ced1 100644
--- a/plugins/org.eclipse.mat.ui.help/tasks/analyzingfinalizer.dita
+++ b/plugins/org.eclipse.mat.ui.help/tasks/analyzingfinalizer.dita
@@ -53,7 +53,7 @@
<ul>
<li>it is blocking</li>
<li>it is long running</li>
- <li> it the finalizer queue was or is still full.</li>
+ <li>the finalizer queue was or is still full.</li>
</ul>
<p> Use the finalizer queue query to check the queue.</p>
</entry>
@@ -72,6 +72,13 @@
<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>
diff --git a/plugins/org.eclipse.mat.ui.help/tasks/analyzingfinalizer.html b/plugins/org.eclipse.mat.ui.help/tasks/analyzingfinalizer.html
index 88381f1..7d091e5 100644
--- a/plugins/org.eclipse.mat.ui.help/tasks/analyzingfinalizer.html
+++ b/plugins/org.eclipse.mat.ui.help/tasks/analyzingfinalizer.html
@@ -53,7 +53,7 @@
<li class="li">it is long running</li>
- <li class="li"> it the finalizer queue was or is still full.</li>
+ <li class="li">the finalizer queue was or is still full.</li>
</ul>
@@ -82,6 +82,14 @@
</ul>
+ <p class="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 class="p"> Additionally a class-level summary of the objects is provided</p>
</td>
