Class Cleaner

java.lang.Object
java.lang.ref.Cleaner
public final class Cleaner extends Object
Cleaner manages a set of object references and corresponding cleaning actions.

Cleaning actions are registered to run after the cleaner is notified that the object has become phantom reachable. The cleaner uses PhantomReference and ReferenceQueue to be notified when the reachability changes.

Each cleaner operates independently, managing the pending cleaning actions and handling threading and termination when the cleaner is no longer in use. Registering an object reference and corresponding cleaning action returns a Cleanable. The most efficient use is to explicitly invoke the clean method when the object is closed or no longer needed. The cleaning action is a Runnable to be invoked at most once when the object has become phantom reachable unless it has already been explicitly cleaned. Note that the cleaning action must not refer to the object being registered. If so, the object will not become phantom reachable and the cleaning action will not be invoked automatically.

The execution of the cleaning action is performed by a thread associated with the cleaner. All exceptions thrown by the cleaning action are ignored. The cleaner and other cleaning actions are not affected by exceptions in a cleaning action. The thread runs until all registered cleaning actions have completed and the cleaner itself is reclaimed by the garbage collector.

The behavior of cleaners during System.exit is implementation specific. No guarantees are made relating to whether cleaning actions are invoked or not.

Unless otherwise noted, passing a null argument to a constructor or method in this class will cause a NullPointerException to be thrown.

Since:
9

  • Method Details

    • create

      public static Cleaner create()
      Returns a new Cleaner.

      The cleaner creates a daemon thread to process the phantom reachable objects and to invoke cleaning actions. The context class loader of the thread is set to the system class loader.

      The cleaner terminates when it is phantom reachable and all of the registered cleaning actions are complete.

      Returns:
      a new Cleaner

    • create

      public static Cleaner create(ThreadFactory threadFactory)
      Returns a new Cleaner using a Thread from the ThreadFactory.

      A thread from the thread factory's newThread method is set to be a daemon thread and started to process phantom reachable objects and invoke cleaning actions. On each call the thread factory must provide a Thread that is suitable for performing the cleaning actions.

      The cleaner terminates when it is phantom reachable and all of the registered cleaning actions are complete.

      Parameters:
      threadFactory - a ThreadFactory to return a new Thread to process cleaning actions
      Returns:
      a new Cleaner
      Throws:
      IllegalThreadStateException - if the thread from the thread factory was not a new thread.

    • register

      public Cleaner.Cleanable register(Object obj, Runnable action)
      Registers an object and a cleaning action to run when the object becomes phantom reachable. Refer to the API Note above for cautions about the behavior of cleaning actions.

      The given object is kept strongly reachable (and therefore not eligible for cleaning) during the register() method.

      Memory consistency effects: Actions in a thread prior to calling Cleaner.register() happen-before the cleaning action is run by the Cleaner's thread.

      Parameters:
      obj - the object to monitor
      action - a Runnable to invoke when the object becomes phantom reachable
      Returns:
      a Cleanable instance