1 package jdk.internal.ref;
   2 
   3 import java.lang.ref.Cleaner;
   4 import java.util.Objects;
   5 import java.util.concurrent.ThreadFactory;
   6 import java.util.function.BooleanSupplier;
   7 import java.util.function.Supplier;
   8 
   9 /**
  10  * An extension of public {@link Cleaner} with operations that can only be
  11  * invoked from within {@code java.base} module or selected modules to
  12  * which {@code jdk.internal.ref} package is exported.
  13  */
  14 public interface ExtendedCleaner extends Cleaner {
  15 
  16     /**
  17      * @return new ExtendedCleaner with default ThreadFactory.
  18      */
  19     static ExtendedCleaner create() {
  20         return new CleanerImpl.ExtendedImpl(null);
  21     }
  22 
  23     /**
  24      * @return new ExtendedCleaner with given ThreadFactory.
  25      */
  26     static ExtendedCleaner create(ThreadFactory threadFactory) {
  27         Objects.requireNonNull(threadFactory, "threadFactory");
  28         return new CleanerImpl.ExtendedImpl(threadFactory);
  29     }
  30 
  31     /**
  32      * Retries given {@code retriableAction} while helping execute cleaning
  33      * actions of pending Cleanable(s) registered by this ExtendedCleaner
  34      * until the action returns a non-null result or there are no more pending
  35      * Cleanable(s) to clean.
  36      * <p>
  37      * The purpose of this method is to coordinate allocation or reservation of
  38      * some limited resource with cleanup actions that deallocate or unreserve
  39      * the same resource. The method attempts to expedite cleanup actions if
  40      * the retrial(s) are unsuccessful by employing the calling thread to help
  41      * with executing them and returns {@code null} only after all available
  42      * attempts have been made to execute pending cleanup actions but
  43      * given {@code retriableAction} still hasn't returned a non-null result.
  44      *
  45      * @param retriableAction the allocation or reservation action to retry
  46      *                        while helping with cleanup actions.
  47      * @return the non-null result of retriable action if there was one or
  48      * {@code null} when the action did not return a non-null result before
  49      * all pending Cleanable(s) have been executed.
  50      */
  51     <T> T retryWhileHelpingClean(Supplier<T> retriableAction);
  52 }