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

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:

[email protected] (mike nonemacher), [email protected] (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.

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