--- /dev/null 2016-03-29 09:06:22.243762170 +0200 +++ new/src/java.base/share/classes/jdk/internal/ref/ExtendedCleaner.java 2016-04-01 16:47:29.028837038 +0200 @@ -0,0 +1,51 @@ +package jdk.internal.ref; + +import java.lang.ref.Cleaner; +import java.util.Objects; +import java.util.concurrent.ThreadFactory; +import java.util.function.BooleanSupplier; + +/** + * An extension of public {@link Cleaner} with operations that can only be + * invoked from within {@code java.base} module or selected modules to + * which {@code jdk.internal.ref} package is exported. + */ +public interface ExtendedCleaner extends Cleaner { + + /** + * @return new ExtendedCleaner with default ThreadFactory. + */ + static ExtendedCleaner create() { + return new CleanerImpl.ExtendedImpl(null); + } + + /** + * @return new ExtendedCleaner with given ThreadFactory. + */ + static ExtendedCleaner create(ThreadFactory threadFactory) { + Objects.requireNonNull(threadFactory, "threadFactory"); + return new CleanerImpl.ExtendedImpl(threadFactory); + } + + /** + * Retries given {@code retriableAction} while helping execute cleaning + * actions of pending Cleanable(s) registered by this ExtendedCleaner + * until the action returns {@code true} or there are no more pending + * Cleanable(s) to clean. + *

+ * The purpose of this method is to coordinate allocation or reservation of + * some limited resource with cleanup actions that deallocate or unreserve + * the same resource. The method attempts to expedite cleanup actions if + * the retrial(s) are unsuccessful by employing the calling thread to help + * with executing them and returns {@code false} only after all available + * attempts have been made to execute pending cleanup actions but + * given {@code retriableAction} still hasn't returned {@code true}. + * + * @param retriableAction the allocation or reservation action to retry + * while helping with cleanup actions. + * @return {@code true} if the retriable action succeeded by returning + * {@code true} or {@code false} when the action did not succeed before + * all pending Cleanable(s) have been executed. + */ + boolean retryWhileHelpingClean(BooleanSupplier retriableAction); +}