Package io.deephaven.util.reference

Class CleanupReferenceProcessor

java.lang.Object
io.deephaven.util.reference.CleanupReferenceProcessor
public class CleanupReferenceProcessor extends Object
Utility for draining a reference queue of CleanupReferences and invoking their cleanup methods.

  • Constructor Details

    • CleanupReferenceProcessor

      public CleanupReferenceProcessor(@NotNull @NotNull String name, long shutdownCheckDelayMillis, @NotNull @NotNull CleanupReferenceProcessor.ExceptionHandler exceptionHandler)
      Construct a new CleanupReferenceProcessor.
      Parameters:
      name - The name of the processor, used for naming threads
      shutdownCheckDelayMillis - The frequency with which to check for shutdown
      exceptionHandler - Callback for exception handling

  • Method Details

    • getDefault

      @NotNull public static @NotNull CleanupReferenceProcessor getDefault()

    • getReferenceQueue

      public <RT> ReferenceQueue<RT> getReferenceQueue()

      Get the reference queue for this cleaner.

      On the first call after construction or resetForUnitTests(), this method initializes the instance as a side effect. Initialization entails:

      1. Constructing a ReferenceQueue.
      2. Starting a daemon thread that will drain the reference queue and invoke CleanupReference.cleanup() on any CleanupReference dequeued.
      Returns:
      The ReferenceQueue constructed in the most recent initialization of this CleanupReferenceProcessor instance

    • registerPhantom

      public <T> CleanupReference<T> registerPhantom(T referent, Runnable action)
      Registers a referent and a cleaning action to run when the referent becomes phantom reachable.

      The most efficient use is to explicitly invoke the cleanup method when the referent is closed or no longer needed. Otherwise, the cleaning action will be invoked when referent has become phantom reachable. The action will not be invoked more than once.

      The cleaning action must not refer to the referent being registered. If so, the referent will never become phantom reachable and the cleaning action will never be invoked automatically.

      Note: while the caller is encouraged to hold onto the cleanup reference to allow for explicit cleanup invocation, they are not required to as this cleanup reference processor will hold onto the reference.

      Parameters:
      referent - the object to monitor
      action - a Runnable to invoke when the referent becomes phantom reachable
      Returns:
      a cleanup reference instance

    • registerWeak

      public <T> CleanupReference<T> registerWeak(T referent, Runnable action)
      Registers a referent and a cleaning action to run when the referent becomes weakly reachable.

      The most efficient use is to explicitly invoke the cleanup method when the referent is closed or no longer needed. Otherwise, the cleaning action will be invoked when referent has become weakly reachable. The action will not be invoked more than once.

      The cleaning action must not refer to the referent being registered. If so, the referent will never become weakly reachable and the cleaning action will never be invoked automatically.

      Note: while the caller is encouraged to hold onto the cleanup reference to allow for explicit cleanup invocation, they are not required to as this cleanup reference processor will hold onto the reference.

      Parameters:
      referent - the object to monitor
      action - a Runnable to invoke when the referent becomes weakly reachable
      Returns:
      a cleanup reference instance

    • registerSoft

      public <T> CleanupReference<T> registerSoft(T referent, Runnable action)
      Registers a referent and a cleaning action to run when the referent becomes softly reachable.

      The most efficient use is to explicitly invoke the cleanup method when the referent is closed or no longer needed. Otherwise, the cleaning action will be invoked when referent has become softly reachable. The action will not be invoked more than once.

      The cleaning action must not refer to the referent being registered. If so, the referent will never become softly reachable and the cleaning action will never be invoked automatically.

      Note: while the caller is encouraged to hold onto the cleanup reference to allow for explicit cleanup invocation, they are not required to as this cleanup reference processor will hold onto the reference.

      Parameters:
      referent - the object to monitor
      action - a Runnable to invoke when the referent becomes softly reachable
      Returns:
      a cleanup reference instance

    • resetForUnitTests

      @TestUseOnly public final void resetForUnitTests()
      Reset this instance so that the next call to getReferenceQueue() will re-initialize it and provide a new queue. Results in the prompt termination of the daemon thread that may have been draining the existing queue.