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.Supplier; 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 a non-null result 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 null} only after all available 41 * attempts have been made to execute pending cleanup actions but 42 * given {@code retriableAction} still hasn't returned a non-null result. 43 * 44 * @param retriableAction the allocation or reservation action to retry 45 * while helping with cleanup actions. 46 * @return the non-null result of retriable action if there was one or 47 * {@code null} when the action did not return a non-null result before 48 * all pending Cleanable(s) have been executed. 49 */ 50 <T> T retryWhileHelpingClean(Supplier<T> retriableAction); 51 }