<?php

declare(strict_types=1);

namespace Apexl\Io\Jobs\Interfaces;

/**
 * Opt-in extension of {@see QueueTaskHandlerInterface} for handlers that can tell, without
 * running, that now is not the time.
 *
 * Without this the only way to decline is to throw, and that is expensive: the runner has
 * already locked the job, so declining costs four writes — lock, attempts, run_after,
 * unlock — plus a log line, per job, per pass. A handler deliberately holding a large
 * backlog back therefore spends most of the queue's capacity refusing to do work.
 *
 * Asked before the job is locked. Returning false costs one write: the job is deferred by
 * {@see skipDelaySeconds()} and left otherwise untouched — no attempt is recorded, because
 * nothing was attempted, and the job keeps its place in sequence order.
 *
 * The deferral matters. Skipping without it would leave the job due, occupying a slot in
 * every future batch and starving the handlers behind it — which is the outcome this is
 * meant to avoid.
 */
interface SkippableTaskHandlerInterface extends QueueTaskHandlerInterface
{
    /** False to stand this job down without running or failing it. */
    public function shouldRun(): bool;

    /** How long to stand down for, when shouldRun() says no. */
    public function skipDelaySeconds(): int;
}
