com.google.common.testing
Class GcFinalization

java.lang.Object
  com.google.common.testing.GcFinalization

@Beta
public final class GcFinalization
extends Object

Testing utilities relating to garbage collection finalization.

Use this class to test code triggered by finalization, that is, one of the following actions taken by the java garbage collection system:

• invoking the finalize methods of unreachable objects
• clearing weak references to unreachable referents
• enqueuing weak references to unreachable referents in their reference queue

This class uses (possibly repeated) invocations of System.gc() to cause finalization to happen. However, a call to 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 -XX:+DisableExplicitGC. But in practice, it works very well for ordinary tests.

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 RuntimeException.

Here's an example that tests a finalize method:

   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);
 

Here's an example that uses a user-defined finalization predicate:

   final WeakHashMap<Object, Object> map = new WeakHashMap<Object, Object>();
   map.put(new Object(), Boolean.TRUE);
   GcFinalization.awaitDone(new FinalizationPredicate() {
     public boolean isDone() {
       return map.isEmpty();
     }
   });
 

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:

 // Helper function keeps victim stack-unreachable.
 private WeakReference<Foo> fooWeakRef() {
   Foo x = ....;
   WeakReference<Foo> weakRef = new WeakReference<Foo>(x);
   // ... use x ...
   x = null;  // Hint to the JIT that x is stack-unreachable
   return weakRef;
 }
 public void testFooLeak() {
   GcFinalization.awaitClear(fooWeakRef());
 }

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.

This class only provides testing utilities. It is not designed for direct use in production or for benchmarking.

Since:

11.0

Author:

mike nonemacher, Martin Buchholz

Nested Class Summary

static interface

GcFinalization.FinalizationPredicate A predicate that is expected to return true subsequent to finalization, that is, one of the following actions taken by the garbage collector when performing a full collection in response to System.gc(): invoking the finalize methods of unreachable objects clearing weak references to unreachable referents enqueuing weak references to unreachable referents in their reference queue

Method Summary

static void	await(CountDownLatch latch) Waits until the given latch has counted down to zero, invoking the garbage collector as necessary to try to ensure that this will happen.
static void	awaitClear(WeakReference<?> ref) Waits until the given weak reference is cleared, invoking the garbage collector as necessary to try to ensure that this will happen.
static void	awaitDone(Future<?> future) Waits until the given future is done, invoking the garbage collector as necessary to try to ensure that this will happen.
static void	awaitDone(GcFinalization.FinalizationPredicate predicate) Waits until the given predicate returns true, invoking the garbage collector as necessary to try to ensure that this will happen.
static void	awaitFullGc() Tries to perform a "full" garbage collection cycle (including processing of weak references and invocation of finalize methods) and waits for it to complete.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

awaitDone

public static void awaitDone(Future<?> future)

Waits until the given future 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

await

public static void await(CountDownLatch latch)

Waits until the given latch has 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

awaitDone

public static void awaitDone(GcFinalization.FinalizationPredicate predicate)

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

awaitClear

public static void awaitClear(WeakReference<?> ref)

Waits until the given weak reference is cleared, invoking the garbage collector as necessary to try to ensure that this will happen.

This is a convenience method, equivalent to:

   awaitDone(new FinalizationPredicate() {
     public boolean isDone() {
       return ref.get() == null;
     }
   });
 

Throws:

RuntimeException - if timed out or interrupted while waiting

awaitFullGc

public static void awaitFullGc()

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 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.

In contrast, a plain call to System.gc() does not ensure finalization processing and may run concurrently, for example, if the JVM flag -XX:+ExplicitGCInvokesConcurrent is used.

Whenever possible, it is preferable to test directly for some observable change resulting from GC, as with awaitClear(java.lang.ref.WeakReference). 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.

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