finalizer-doc.java

/**
 * Invoked when the garbage collector has detected that this instance is no longer reachable.
 * The default implementation does nothing, but this method can be overridden to free resources.
 *
 * <p>Note that objects that override {@code finalize} are significantly more expensive than
 * objects that don't. Finalizers may be run a long time after the object is no longer
 * reachable, depending on memory pressure, so it's a bad idea to rely on them for cleanup.
 * Note also that finalizers are run on a single VM-wide finalizer thread,
 * so doing blocking work in a finalizer is a bad idea. A finalizer is usually only necessary
 * for a class that has a native peer and needs to call a native method to destroy that peer.
 * Even then, it's better to provide an explicit {@code close} method (and implement
 * {@link java.io.Closeable}), and insist that callers manually dispose of instances. This
 * works well for something like files, but less well for something like a {@code BigInteger}
 * where typical calling code would have to deal with lots of temporaries. Unfortunately,
 * code that creates lots of temporaries is the worst kind of code from the point of view of
 * the single finalizer thread.
 *
 * <p>If you <i>must</i> use finalizers, consider at least providing your own
 * {@link java.lang.ref.ReferenceQueue} and having your own thread process that queue.
 *
 * <p>Unlike constructors, finalizers are not automatically chained. You are responsible for
 * calling {@code super.finalize()} yourself.
 *
 * <p>Uncaught exceptions thrown by finalizers are ignored and do not terminate the finalizer
 * thread.
 *
 * See <i>Effective Java</i> Item 7, "Avoid finalizers" for more.
 */