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 retriableOperation} while helping execute cleaning
     * functions of pending Cleanable(s) registered by this ExtendedCleaner
     * until the operation returns {@code true} or there are no more pending
     * Cleanable(s) to clean.
     *
     * @param retriableOperation the operation to retry while helping with cleanup.
     * @return {@code true} if the operation succeeded by returning {@code true} or
     * {@code false} when the operation did not succeed before all pending
     * Cleanable(s) have been executed.
     */
    boolean retryWhileHelpingClean(BooleanSupplier retriableOperation);
}