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.
     * <p>
     * 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);
}