Java example source code file (GcFinalization.java)

This example Java source code file (GcFinalization.java) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

beta, countdownlatch, finalizationpredicate, gcfinalization, gwtincompatible, interruptedexception, j2objcincompatible, object, override, runtimeexception, seconds, threading, threads, timeoutexception, unexpected, util, weakreference

The GcFinalization.java Java example source code

/*
 * Copyright (C) 2011 The Guava Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.google.common.testing;

import static java.util.concurrent.TimeUnit.SECONDS;

import com.google.common.annotations.Beta;
import com.google.common.annotations.GwtIncompatible;
import com.google.j2objc.annotations.J2ObjCIncompatible;

import java.lang.ref.WeakReference;
import java.util.Locale;
import java.util.concurrent.CancellationException;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import java.util.concurrent.TimeoutException;

/**
 * Testing utilities relating to garbage collection finalization.
 *
 * <p>Use this class to test code triggered by finalization, that is, one of the
 * following actions taken by the java garbage collection system:
 *
 * <ul>
 * <li>invoking the {@code finalize} methods of unreachable objects
 * <li>clearing weak references to unreachable referents
 * <li>enqueuing weak references to unreachable referents in their reference queue
 * </ul>
 *
 * <p>This class uses (possibly repeated) invocations of {@link java.lang.System#gc()} to cause
 * finalization to happen.  However, a call to {@code System.gc()} is specified to be no more
 * than a hint, so this technique may fail at the whim of the JDK implementation, for example if
 * a user specified the JVM flag {@code -XX:+DisableExplicitGC}.  But in practice, it works very
 * well for ordinary tests.
 *
 * <p>Failure of the expected event to occur within an implementation-defined "reasonable" time
 * period or an interrupt while waiting for the expected event will result in a {@link
 * RuntimeException}.
 *
 * <p>Here's an example that tests a {@code finalize} method:
 *
 * <pre>   {@code
 *   final CountDownLatch latch = new CountDownLatch(1);
 *   Object x = new MyClass() {
 *     ...
 *     protected void finalize() { latch.countDown(); ... }
 *   };
 *   x = null;  // Hint to the JIT that x is stack-unreachable
 *   GcFinalization.await(latch);}</pre>
 *
 * <p>Here's an example that uses a user-defined finalization predicate:
 *
 * <pre>   {@code
 *   final WeakHashMap<Object, Object> map = new WeakHashMap();
 *   map.put(new Object(), Boolean.TRUE);
 *   GcFinalization.awaitDone(new FinalizationPredicate() {
 *     public boolean isDone() {
 *       return map.isEmpty();
 *     }
 *   });}</pre>
 *
 * <p>Even if your non-test code does not use finalization, you can
 * use this class to test for leaks, by ensuring that objects are no
 * longer strongly referenced:
 *
 * <pre> {@code
 * // Helper function keeps victim stack-unreachable.
 * private WeakReference<Foo> fooWeakRef() {
 *   Foo x = ....;
 *   WeakReference<Foo> weakRef = new WeakReference(x);
 *   // ... use x ...
 *   x = null;  // Hint to the JIT that x is stack-unreachable
 *   return weakRef;
 * }
 * public void testFooLeak() {
 *   GcFinalization.awaitClear(fooWeakRef());
 * }}</pre>
 *
 * <p>This class cannot currently be used to test soft references, since this class does not try to
 * create the memory pressure required to cause soft references to be cleared.
 *
 * <p>This class only provides testing utilities.  It is not designed for direct use in production
 * or for benchmarking.
 *
 * @author mike nonemacher
 * @author Martin Buchholz
 * @since 11.0
 */
@Beta
@GwtIncompatible
@J2ObjCIncompatible // gc
public final class GcFinalization {
  private GcFinalization() {}

  /**
   * 10 seconds ought to be long enough for any object to be GC'ed and finalized.  Unless we have a
   * gigantic heap, in which case we scale by heap size.
   */
  private static long timeoutSeconds() {
    // This class can make no hard guarantees.  The methods in this class are inherently flaky, but
    // we try hard to make them robust in practice.  We could additionally try to add in a system
    // load timeout multiplier.  Or we could try to use a CPU time bound instead of wall clock time
    // bound.  But these ideas are harder to implement.  We do not try to detect or handle a
    // user-specified -XX:+DisableExplicitGC.
    //
    // TODO(user): Consider using
    // java/lang/management/OperatingSystemMXBean.html#getSystemLoadAverage()
    //
    // TODO(user): Consider scaling by number of mutator threads,
    // e.g. using Thread#activeCount()
    return Math.max(10L, Runtime.getRuntime().totalMemory() / (32L * 1024L * 1024L));
  }

  /**
   * Waits until the given future {@linkplain Future#isDone is done}, invoking the garbage
   * collector as necessary to try to ensure that this will happen.
   *
   * @throws RuntimeException if timed out or interrupted while waiting
   */
  public static void awaitDone(Future<?> future) {
    if (future.isDone()) {
      return;
    }
    final long timeoutSeconds = timeoutSeconds();
    final long deadline = System.nanoTime() + SECONDS.toNanos(timeoutSeconds);
    do {
      System.runFinalization();
      if (future.isDone()) {
        return;
      }
      System.gc();
      try {
        future.get(1L, SECONDS);
        return;
      } catch (CancellationException ok) {
        return;
      } catch (ExecutionException ok) {
        return;
      } catch (InterruptedException ie) {
        throw new RuntimeException("Unexpected interrupt while waiting for future", ie);
      } catch (TimeoutException tryHarder) {
        /* OK */
      }
    } while (System.nanoTime() - deadline < 0);
    throw formatRuntimeException("Future not done within %d second timeout", timeoutSeconds);
  }

  /**
   * Waits until the given latch has {@linkplain CountDownLatch#countDown counted down} to zero,
   * invoking the garbage collector as necessary to try to ensure that this will happen.
   *
   * @throws RuntimeException if timed out or interrupted while waiting
   */
  public static void await(CountDownLatch latch) {
    if (latch.getCount() == 0) {
      return;
    }
    final long timeoutSeconds = timeoutSeconds();
    final long deadline = System.nanoTime() + SECONDS.toNanos(timeoutSeconds);
    do {
      System.runFinalization();
      if (latch.getCount() == 0) {
        return;
      }
      System.gc();
      try {
        if (latch.await(1L, SECONDS)) {
          return;
        }
      } catch (InterruptedException ie) {
        throw new RuntimeException("Unexpected interrupt while waiting for latch", ie);
      }
    } while (System.nanoTime() - deadline < 0);
    throw formatRuntimeException(
        "Latch failed to count down within %d second timeout", timeoutSeconds);
  }

  /**
   * Creates a garbage object that counts down the latch in its finalizer.  Sequestered into a
   * separate method to make it somewhat more likely to be unreachable.
   */
  private static void createUnreachableLatchFinalizer(final CountDownLatch latch) {
    new Object() { @Override protected void finalize() { latch.countDown(); }};
  }

  /**
   * A predicate that is expected to return true subsequent to <em>finalization, that is, one
   * of the following actions taken by the garbage collector when performing a full collection in
   * response to {@link System#gc()}:
   *
   * <ul>
   * <li>invoking the {@code finalize} methods of unreachable objects
   * <li>clearing weak references to unreachable referents
   * <li>enqueuing weak references to unreachable referents in their reference queue
   * </ul>
   */
  public interface FinalizationPredicate {
    boolean isDone();
  }

  /**
   * Waits until the given predicate returns true, invoking the garbage collector as necessary to
   * try to ensure that this will happen.
   *
   * @throws RuntimeException if timed out or interrupted while waiting
   */
  public static void awaitDone(FinalizationPredicate predicate) {
    if (predicate.isDone()) {
      return;
    }
    final long timeoutSeconds = timeoutSeconds();
    final long deadline = System.nanoTime() + SECONDS.toNanos(timeoutSeconds);
    do {
      System.runFinalization();
      if (predicate.isDone()) {
        return;
      }
      CountDownLatch done = new CountDownLatch(1);
      createUnreachableLatchFinalizer(done);
      await(done);
      if (predicate.isDone()) {
        return;
      }
    } while (System.nanoTime() - deadline < 0);
    throw formatRuntimeException(
        "Predicate did not become true within %d second timeout", timeoutSeconds);
  }

  /**
   * Waits until the given weak reference is cleared, invoking the garbage collector as necessary
   * to try to ensure that this will happen.
   *
   * <p>This is a convenience method, equivalent to:
   * <pre>   {@code
   *   awaitDone(new FinalizationPredicate() {
   *     public boolean isDone() {
   *       return ref.get() == null;
   *     }
   *   });}</pre>
   *
   * @throws RuntimeException if timed out or interrupted while waiting
   */
  public static void awaitClear(final WeakReference<?> ref) {
    awaitDone(new FinalizationPredicate() {
      public boolean isDone() {
        return ref.get() == null;
      }
    });
  }

  /**
   * Tries to perform a "full" garbage collection cycle (including processing of weak references
   * and invocation of finalize methods) and waits for it to complete.  Ensures that at least one
   * weak reference has been cleared and one {@code finalize} method has been run before this
   * method returns.  This method may be useful when testing the garbage collection mechanism
   * itself, or inhibiting a spontaneous GC initiation in subsequent code.
   *
   * <p>In contrast, a plain call to {@link java.lang.System#gc()} does not ensure finalization
   * processing and may run concurrently, for example, if the JVM flag {@code
   * -XX:+ExplicitGCInvokesConcurrent} is used.
   *
   * <p>Whenever possible, it is preferable to test directly for some observable change resulting
   * from GC, as with {@link #awaitClear}.  Because there are no guarantees for the order of GC
   * finalization processing, there may still be some unfinished work for the GC to do after this
   * method returns.
   *
   * <p>This method does not create any memory pressure as would be required to cause soft
   * references to be processed.
   *
   * @throws RuntimeException if timed out or interrupted while waiting
   * @since 12.0
   */
  public static void awaitFullGc() {
    final CountDownLatch finalizerRan = new CountDownLatch(1);
    WeakReference<Object> ref = new WeakReference