-
Notifications
You must be signed in to change notification settings - Fork 3
/
merge_shortest_paths.dita
215 lines (212 loc) · 6.59 KB
/
merge_shortest_paths.dita
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2020, 2023 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:
IBM Corporation - initial implementation
-->
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd" >
<reference id="ref_inspections_path_to_gc_roots"
xml:lang="en-us">
<title>Merge Shortest Paths</title>
<shortdesc>Find out who is keeping alive a set of objects.
</shortdesc>
<prolog>
<copyright>
<copyryear year=""></copyryear>
<copyrholder>
Copyright (c) 2020, 2023 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/
</copyrholder>
</copyright>
</prolog>
<refbody>
<section>
<title>Motivation</title>
<p>Having found an expensive object it is then important to find all
the reasons it is kept alive.
</p>
</section>
<section>
<title>Explanation</title>
<p>
Unlike the
<xref href="path_to_gc_roots.dita">Path to GC roots</xref>
query, this query
can operate on multiple objects.
However, it only
finds the shortest path to GC roots; there may
be other paths, but
this query does not show them.
As it operates on multiple objects
there are multiple paths,
and the query has the option to merge
objects on a path by
class.
Seeing a common path can be useful in
understanding why a
set of objects is being kept alive.
</p>
</section>
<section>
<title>Arguments</title>
<simpletable>
<sthead>
<stentry>Argument</stentry>
<stentry>Description</stentry>
</sthead>
<strow>
<stentry>objects</stentry>
<stentry>Objects for which paths to garbage collection roots should
be
found.
</stentry>
</strow>
<strow>
<stentry>
<parmname>-excludes</parmname>
</stentry>
<stentry>
Fields of certain classes which should be ignored when finding
paths. For example this allows paths through Weak or Soft
Reference referents to be ignored.
This is of the format
<varname>class name pattern</varname>
[:
<varname>field name</varname>
[,
<varname>field name</varname>
]*].
Subclasses of the class are also included.
If no field names
are specified for the class then all fields are
excluded.
</stentry>
</strow>
<strow>
<stentry>
<parmname>-groupby</parmname>
</stentry>
<stentry>
Whether to show:
<ul>
<li>
<parmname>Merge Paths from GC Roots</parmname>
merged paths from garbage collection roots to the objects
</li>
<li>
<parmname>Merge Paths from GC Roots on Class</parmname>
merged paths from garbage collection roots to the objects
grouped by class, so all objects of the same class are shown as
one
</li>
<li>
<parmname>Merge to GC Roots on Class</parmname>
merged paths from the objects to garbage collection roots
grouped
by class, so all objects of the same class are shown as
one
</li>
</ul>
</stentry>
</strow>
</simpletable>
</section>
<section id="result">
<title>Result</title>
<p>
The tree shows objects or sets of objects grouped by class on a path
to or from GC roots.
The
<wintitle>Referenced Objects</wintitle>
column shows how many
of the objects supplied to this query are on a path through this
row.
</p>
<p>The context menu allows the objects on this segment of the path,
or the referenced objects through this path to be separately
examined with other queries.
</p>
<wintitle>Merge shortest paths from GC roots</wintitle>
<image href="../../mimes/merge_shortest_paths1.png" scale="75">
<alt>
Result of a merge shortest paths query, showing a
tree view starting from GC roots.
</alt>
</image>
<note>
With
<parmname>Merge Paths from GC Roots</parmname>
and
<parmname>Merge from GC Roots on Class</parmname>
the arrows in each
<xref href="../../reference/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>
icon
</xref>
points down and to the right, showing
that the objects or objects of
a line refer via the field in
<b>bold</b>
to the following object or objects in
the tree view which is down and
to the right.
The
<parmname>Merge from GC Roots on Class</parmname>
does
not show field names as different objects may refer to
the
following objects by different fields.
</note>
<wintitle>Merge shortest paths from GC roots on class</wintitle>
<image href="../../mimes/merge_shortest_paths2.png" scale="75">
<alt>
Result of a merge shortest paths query, showing a
tree view starting from GC roots, but merged on classes.
</alt>
</image>
<note>See the menu option to switch between the different <parmname>groupby</parmname>
options.</note>
<wintitle>Merge shortest paths to GC roots on class</wintitle>
<image href="../../mimes/merge_shortest_paths3.png" scale="75">
<alt>
Result of a merge shortest paths query, showing a
tree view starting from the objects, merged on classes,
going to GC roots.
</alt>
</image>
<note>
With
<parmname>Merge to GC Roots on Class</parmname>
the arrows in each
<xref href="../../reference/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>
icon
</xref>
points up and to the left, showing
that the object or objects of a
line actually refer
to the preceding objects in
the tree view which is
up and to the left.
</note>
</section>
</refbody>
</reference>