View Javadoc
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 }