1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 package org.apache.commons.lang3.builder;
19
20 import static org.junit.jupiter.api.Assertions.assertEquals;
21 import static org.junit.jupiter.api.Assertions.assertTrue;
22
23 import java.io.File;
24 import java.nio.charset.StandardCharsets;
25 import java.nio.file.Files;
26 import java.nio.file.Path;
27 import java.nio.file.Paths;
28 import java.util.concurrent.TimeUnit;
29
30 import org.apache.commons.lang3.AbstractLangTest;
31 import org.apache.commons.lang3.SystemUtils;
32 import org.junit.jupiter.api.Test;
33 import org.junit.jupiter.api.io.TempDir;
34
35 /**
36 * Tests that abandoned direct outputs remain collectable when a visited object refers back to their output buffer.
37 *
38 * <p>
39 * Direct style calls retain traversal state between {@code appendStart()} and {@code appendEnd()} using weak buffer keys. Weak keys alone cannot release an
40 * abandoned buffer if the associated traversal strongly retains a visited object that points back to that buffer. Weak visited references must break this
41 * retention path even when the caller never invokes {@code appendEnd()}.
42 * </p>
43 *
44 * <p>
45 * A child JVM allocates more buffer capacity than its bounded heap can retain. Successful completion demonstrates that abandoned outputs can be collected under
46 * allocation pressure, without depending on explicit garbage collection or risking the main test runner's heap.
47 * </p>
48 */
49 class ToStringBuilderTraversalMemoryTest extends AbstractLangTest {
50
51 /**
52 * Supplies a standalone entry point for the child JVM's allocation workload.
53 *
54 * <p>
55 * All workload helpers are nested here so the child needs only the project's main and test classes, without invoking JUnit. The parent test provides the
56 * heap limit and checks both the exit status and a completion marker.
57 * </p>
58 */
59 public static final class MemoryProbe {
60
61 /**
62 * Supplies a reflectively visited field that strongly references the output buffer.
63 *
64 * <p>
65 * Retaining this object in a traversal's visited set would also retain the buffer used as the direct traversal map's weak key.
66 * </p>
67 */
68 private static final class BufferLink {
69
70 @SuppressWarnings("unused")
71 private final StringBuffer buffer;
72
73 /**
74 * Creates the back reference that exposes strong retention by a visited set.
75 *
76 * @param buffer the output buffer that must become collectable after the iteration.
77 */
78 private BufferLink(final StringBuffer buffer) {
79 this.buffer = buffer;
80 }
81 }
82
83 /**
84 * Renders the back reference while isolating traversal retention from root registration and JDK implementation fields.
85 */
86 private static final class DirectStyle extends RecursiveToStringStyle {
87
88 private static final long serialVersionUID = 1L;
89
90 /**
91 * Disables the prefixes that register the root, so an omitted {@code appendEnd()} tests only abandoned traversal state.
92 */
93 private DirectStyle() {
94 // Avoid registering an abandoned root: this test concerns visited objects, not the older root registry behavior.
95 setUseClassName(false);
96 setUseIdentityHashCode(false);
97 }
98
99 /**
100 * Excludes buffer internals from reflection while allowing {@link BufferLink} to be visited.
101 *
102 * <p>
103 * The buffer is rendered using its own {@code toString()}, avoiding reflective access to JDK implementation fields. The link still holds the strong
104 * back reference needed to expose a retention regression.
105 * </p>
106 *
107 * @param type the class considered for recursive reflection.
108 * @return {@code false} for {@link StringBuffer}, otherwise the superclass decision.
109 */
110 @Override
111 protected boolean accept(final Class<?> type) {
112 return type != StringBuffer.class && super.accept(type);
113 }
114 }
115
116 /**
117 * Creates 20,000 abandoned outputs whose total buffer capacity exceeds the child JVM's 32 MB heap.
118 *
119 * <p>
120 * Every iteration opens a direct traversal, visits an object that points back to its buffer, and deliberately omits {@code appendEnd()}. The root
121 * registry must remain empty so it cannot explain retained buffers. With weak visited references, allocation pressure allows old outputs to be
122 * collected and the workload prints its completion marker; strong retention exhausts the bounded heap before completion.
123 * </p>
124 *
125 * @param args unused.
126 */
127 public static void main(final String[] args) {
128 final DirectStyle style = new DirectStyle();
129 for (int i = 0; i < 20_000; i++) {
130 final StringBuffer buffer = new StringBuffer(4096);
131 style.appendStart(buffer, new Object());
132 style.append(buffer, "link", new BufferLink(buffer), Boolean.TRUE);
133 // Deliberately omit appendEnd(). A visited object refers back to the weakly registered output buffer.
134 if (!ToStringStyle.getRegistry().isEmpty()) {
135 throw new AssertionError("The root registry must not retain these outputs");
136 }
137 }
138 System.out.println("Completed 20000 abandoned outputs");
139 }
140 }
141
142 /**
143 * Tests that abandoned buffer back references do not prevent the allocation workload from completing within a 32 MB heap.
144 *
145 * <p>
146 * The child uses the current Java runtime and the main and test class locations. Exit status zero and the completion marker establish that the entire
147 * workload ran successfully. A timeout and forced cleanup bound failures, and captured child output makes memory exhaustion diagnosable.
148 * </p>
149 *
150 * @param tempDir the directory for the child's combined standard output and error log.
151 * @throws Exception if class locations cannot be resolved, the process or log cannot be accessed, or waiting is interrupted.
152 */
153 @Test
154 void testAbandonedOutputWithBufferBackReferenceIsCollectable(@TempDir final Path tempDir) throws Exception {
155 final Path java = Paths.get(System.getProperty("java.home"), "bin", SystemUtils.IS_OS_WINDOWS ? "java.exe" : "java");
156 final String classPath = Paths.get(MemoryProbe.class.getProtectionDomain().getCodeSource().getLocation().toURI()) + File.pathSeparator
157 + Paths.get(ToStringBuilder.class.getProtectionDomain().getCodeSource().getLocation().toURI());
158 final Path log = tempDir.resolve("memory-probe.log");
159 final Process process = new ProcessBuilder(java.toString(), "-Xmx32m", "-cp", classPath, MemoryProbe.class.getName()).redirectErrorStream(true)
160 .redirectOutput(log.toFile()).start();
161 try {
162 assertTrue(process.waitFor(60, TimeUnit.SECONDS), "The memory probe must finish within its time limit");
163 final String output = new String(Files.readAllBytes(log), StandardCharsets.UTF_8);
164 assertEquals(0, process.exitValue(), output);
165 assertTrue(output.contains("Completed 20000 abandoned outputs"), output);
166 } finally {
167 process.destroyForcibly();
168 assertTrue(process.waitFor(10, TimeUnit.SECONDS), "The child JVM must terminate even if the test fails");
169 }
170 }
171 }