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