package de.gecheckt.pdf.umbenenner.application.port.in;

/**
 * Inbound cooperative cancellation token for a running batch.
 * <p>
 * The application layer consults the token at safe points between candidates to decide
 * whether the run should stop before starting the next candidate. The current candidate
 * is always processed to completion before the token is honoured (soft-stop semantics).
 * <p>
 * Implementations are typically shared between an inbound adapter (which sets the
 * cancellation request) and the use case (which polls it). They must be safe to read from
 * the batch thread while being written concurrently by the adapter thread.
 *
 * <h2>Default implementation</h2>
 * <p>
 * Callers that do not need cancellation (e.g. the headless batch entry point) supply
 * {@link #neverCancelled()} as the token.
 */
public interface BatchRunCancellationToken {

    /**
     * Returns {@code true} if a cancellation has been requested and the batch should
     * stop before starting the next candidate.
     * <p>
     * Must be cheap to call; may be polled repeatedly during a run.
     *
     * @return {@code true} if the run should stop as soon as practical, {@code false}
     *         otherwise
     */
    boolean isCancellationRequested();

    /**
     * Returns a singleton token that never reports a cancellation request.
     *
     * @return a non-null token that always returns {@code false}
     */
    static BatchRunCancellationToken neverCancelled() {
        return NeverCancelledBatchRunCancellationToken.INSTANCE;
    }
}
