3 import static org.testng.Assert.assertNotNull;
4 import static org.testng.Assert.assertTrue;
7 import java.awt.event.MouseEvent;
9 import java.io.IOException;
10 import java.io.PrintStream;
12 import org.testng.annotations.BeforeClass;
13 import org.testng.annotations.Test;
15 import jalview.analysis.AlignmentGenerator;
16 import jalview.bin.Cache;
17 import jalview.bin.Jalview;
18 import jalview.datamodel.AlignmentI;
19 import jalview.datamodel.SequenceGroup;
20 import jalview.io.DataSourceType;
21 import jalview.io.FileLoader;
22 import junit.extensions.PA;
25 * Provides a simple test that memory is released when all windows are closed.
27 * <li>generates a reasonably large alignment and loads it</li>
28 * <li>performs various operations on the alignment</li>
29 * <li>closes all windows</li>
30 * <li>requests garbage collection</li>
31 * <li>asserts that the remaining memory footprint (heap usage) is 'not large'
34 * If the test fails, this means that reference(s) to large object(s) have
35 * failed to be garbage collected. In this case:
37 * <li>set a breakpoint just before the test assertion in
38 * {@code checkUsedMemory}</li>
39 * <li>if the test fails intermittently, make this breakpoint conditional on
40 * {@code usedMemory > expectedMax}</li>
41 * <li>run the test to this point (and check that it is about to fail i.e.
42 * {@code usedMemory > expectedMax})</li>
43 * <li>use <a href="https://visualvm.github.io/">visualvm</a> to obtain a heap
44 * dump from the suspended process (and kill the test or let it fail)</li>
45 * <li>inspect the heap dump using visualvm for large objects and their
49 * <li>Perform GC from the Monitor view in visualvm before requesting the heap
50 * dump - test failure might be simply a delay to GC</li>
51 * <li>View 'Objects' and filter classes to {@code jalview}. Sort columns by
52 * Count, or Size, and look for anything suspicious. For example, if the object
53 * count for {@code Sequence} is non-zero (it shouldn't be), pick any instance,
54 * and follow the chain of {@code references} to find which class(es) still hold
55 * references to sequence objects</li>
56 * <li>If this chain is impracticably long, re-run the test with a smaller
57 * alignment (set width=100, height=10 in {@code generateAlignment()}), to
58 * capture a heap which is qualitatively the same, but much smaller, so easier
59 * to analyse; note this requires an unconditional breakpoint</li>
63 * <h2>Fixing memory leaks</h2>
65 * Experience shows that often a reference is retained (directly or indirectly)
66 * by a Swing (or related) component (for example a {@code MouseListener} or
67 * {@code ActionListener}). There are two possible approaches to fixing:
69 * <li>Purist: ensure that all listeners and similar objects are removed when no
70 * longer needed. May be difficult, to achieve and to maintain as code
72 * <li>Pragmatic: null references to potentially large objects from Jalview
73 * application classes when no longer needed, typically when a panel is closed.
74 * This ensures that even if the JVM keeps a reference to a panel or viewport,
75 * it does not retain a large heap footprint. This is the approach taken in, for
76 * example, {@code AlignmentPanel.closePanel()} and
77 * {@code AnnotationPanel.dispose()}.</li>
78 * <li>Adjust code if necessary; for example an {@code ActionListener} should
79 * act on {@code av.getAlignment()} and not directly on {@code alignment}, as
80 * the latter pattern could leave persistent references to the alignment</li>
82 * Add code to 'null unused large object references' until the test passes. For
83 * a final sanity check, capture the heap dump for a passing test, and satisfy
84 * yourself that only 'small' or 'harmless' {@code jalview} object instances
85 * (such as enums or singletons) are left in the heap.
87 public class FreeUpMemoryTest
89 private static final int ONE_MB = 1000 * 1000;
92 * maximum retained heap usage (in MB) for a passing test
94 private static int MAX_RESIDUAL_HEAP = 45;
96 * Configure (read-only) Jalview property settings for test
98 @BeforeClass(alwaysRun = true)
103 { "-nonews", "-props", "test/jalview/testProps.jvprops" });
104 String True = Boolean.TRUE.toString();
105 Cache.setPropertyNoSave("SHOW_ANNOTATIONS", True);
106 Cache.setPropertyNoSave("SHOW_QUALITY", True);
107 Cache.setPropertyNoSave("SHOW_CONSERVATION", True);
108 Cache.setPropertyNoSave("SHOW_OCCUPANCY", True);
109 Cache.setPropertyNoSave("SHOW_IDENTITY", True);
113 * A simple test that memory is released when all windows are closed.
115 * <li>generates a reasonably large alignment and loads it</li>
116 * <li>performs various operations on the alignment</li>
117 * <li>closes all windows</li>
118 * <li>requests garbage collection</li>
119 * <li>asserts that the remaining memory footprint (heap usage) is 'not large'
122 * If the test fails, this suggests that a reference to some large object
123 * (perhaps the alignment data, or some annotation / Tree / PCA data) has
124 * failed to be garbage collected. If this is the case, the heap will need to
125 * be inspected manually (suggest using jvisualvm) in order to track down
126 * where large objects are still referenced. The code (for example
127 * AlignmentViewport.dispose()) should then be updated to ensure references to
128 * large objects are set to null when they are no longer required.
130 * @throws IOException
132 @Test(groups = "Memory")
133 public void testFreeMemoryOnClose() throws IOException
135 File f = generateAlignment();
138 long expectedMin = MAX_RESIDUAL_HEAP;
139 long usedMemoryAtStart=getUsedMemory();
140 if (usedMemoryAtStart>expectedMin)
142 System.err.println("used memory before test is "+usedMemoryAtStart+" > "+expectedMin+"MB .. adjusting minimum.");
143 expectedMin = usedMemoryAtStart;
147 Desktop.getInstance().closeAll_actionPerformed(null);
149 checkUsedMemory(expectedMin);
153 * Returns the current total used memory (available memory - free memory),
154 * rounded down to the nearest MB
158 private static int getUsedMemory()
160 long availableMemory = Runtime.getRuntime().totalMemory();
161 long freeMemory = Runtime.getRuntime().freeMemory();
162 long usedMemory = availableMemory - freeMemory;
163 return (int) (usedMemory / ONE_MB);
166 * Requests garbage collection and then checks whether remaining memory in use
167 * is less than the expected value (in Megabytes)
171 protected void checkUsedMemory(int expectedMax)
174 * request garbage collection and wait for it to run (up to 3 times);
175 * NB there is no guarantee when, or whether, it will do so
177 long usedMemory = 0L;
178 Long minUsedMemory = null;
185 usedMemory = getUsedMemory();
186 if (minUsedMemory == null || usedMemory < minUsedMemory)
188 minUsedMemory = usedMemory;
190 if (usedMemory < expectedMax)
197 * if this assertion fails (reproducibly!)
198 * - set a breakpoint here, conditional on (usedMemory > expectedMax)
199 * - run VisualVM to inspect the heap usage, and run GC from VisualVM to check
200 * it is not simply delayed garbage collection causing the test failure
201 * - take a heap dump and identify large objects in the heap and their referers
202 * - fix code as necessary to null the references on close
204 System.out.println("(Minimum) Used memory after " + gcCount
205 + " call(s) to gc() = " + minUsedMemory + "MB (should be <="
206 + expectedMax + ")");
207 assertTrue(usedMemory <= expectedMax, String.format(
208 "Used memory %d should be less than %d (Recommend running test manually to verify)",
209 usedMemory, expectedMax));
213 * Loads an alignment from file and exercises various operations in Jalview
217 protected void doStuffInJalview(File f)
220 * load alignment, wait for consensus and other threads to complete
222 AlignFrame af = new FileLoader().LoadFileWaitTillLoaded(f.getPath(),
223 DataSourceType.FILE);
224 while (af.getViewport().isCalcInProgress())
230 * open an Overview window
232 af.overviewMenuItem_actionPerformed(null);
233 assertNotNull(af.alignPanel.overviewPanel);
236 * exercise the pop-up menu in the Overview Panel (JAL-2864)
238 Object[] args = new Object[] {
239 new MouseEvent(af, 0, 0, 0, 0, 0, 1, true) };
240 PA.invokeMethod(af.alignPanel.overviewPanel,
241 "showPopupMenu(java.awt.event.MouseEvent)", args);
244 * set a selection group - potential memory leak if it retains
245 * a reference to the alignment
247 SequenceGroup sg = new SequenceGroup();
250 AlignmentI al = af.viewport.getAlignment();
251 for (int i = 0; i < al.getHeight(); i++)
253 sg.addSequence(al.getSequenceAt(i), false);
255 af.viewport.setSelectionGroup(sg);
258 * compute Tree and PCA (on all sequences, 100 columns)
260 af.openTreePcaDialog();
261 CalculationChooser dialog = af.alignPanel.getCalculationDialog();
262 dialog.openPcaPanel("BLOSUM62", dialog.getSimilarityParameters(true));
263 dialog.openTreePanel("BLOSUM62", dialog.getSimilarityParameters(false));
266 * wait until Tree and PCA have been computed
268 while (af.viewport.getCurrentTree() == null
269 || dialog.getPcaPanel().isWorking())
275 * give Swing time to add the PCA panel (?!?)
281 * Wait for waitMs miliseconds
285 protected void waitFor(int waitMs)
289 Thread.sleep(waitMs);
290 } catch (InterruptedException e)
296 * Generates an alignment and saves it in a temporary file, to be loaded by
297 * Jalview. We use a peptide alignment (so Conservation and Quality are
298 * calculated), which is wide enough to ensure Consensus, Conservation and
299 * Occupancy have a significant memory footprint (if not removed from the
303 * @throws IOException
305 private File generateAlignment() throws IOException
307 File f = File.createTempFile("MemoryTest", "fa");
308 PrintStream ps = new PrintStream(f);
309 AlignmentGenerator ag = new AlignmentGenerator(false, ps);
312 ag.generate(width, height, 0, 10, 15);