<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

/**
 * Resolves effective queue scheduling from persisted queue metadata.
 *
 * @internal Runtime service, not part of the supported contrib extension API.
 */
interface QueueSchedulingServiceInterface {

  /**
   * Determines whether a queue item is currently paused.
   *
   * @param string|int $itemId
   *   Queue item ID, or a legacy media ID.
   *
   * @return bool
   *   TRUE when paused in persisted queue metadata.
   */
  #[\NoDiscard]
  public function isPaused(string|int $itemId): bool;

  /**
   * Gets runnable queue item IDs in effective processing order for a queue.
   *
   * Processing order applies:
   * - explicit manual order (ascending),
   * - then priority (descending),
   * - then native queue insertion order.
   *
   * Paused items are excluded.
   *
   * @param string $queueName
   *   Queue plugin ID / queue name.
   *
   * @return array<int, string>
   *   Runnable queue item IDs in processing order.
   */
  #[\NoDiscard]
  public function getRunnableItemIds(string $queueName): array;

  /**
   * Gets runnable media IDs in effective processing order for a queue.
   *
   * Backward-compatible wrapper around item-level scheduling that collapses
   * multiple field-scoped items to unique media IDs.
   *
   * @param string $queueName
   *   Queue plugin ID / queue name.
   *
   * @return array<int, int>
   *   Runnable media IDs in processing order.
   */
  #[\NoDiscard]
  public function getRunnableMediaIds(string $queueName): array;

  /**
   * Checks if the given queue item may be processed now.
   *
   * @param string|int $itemId
   *   Queue item ID, or a legacy media ID.
   * @param string $queueName
   *   Queue plugin ID / queue name.
   *
   * @return bool
   *   TRUE only when this queue item is currently the next runnable item.
   */
  #[\NoDiscard]
  public function isProcessable(string|int $itemId, string $queueName): bool;

  /**
   * Pauses all queue processing globally.
   *
   * When paused, no items will be processed from any queue until
   * resumeQueue() is called.
   */
  public function pauseQueue(): void;

  /**
   * Resumes queue processing after a global pause.
   */
  public function resumeQueue(): void;

  /**
   * Checks whether queue processing is globally paused.
   *
   * @return bool
   *   TRUE if the queue is globally paused.
   */
  #[\NoDiscard]
  public function isGloballyPaused(): bool;

  /**
   * Resets derived scheduling state.
   *
   * The current implementation reads live metadata on every scheduling
   * decision, so this is retained as a backwards-compatible no-op.
   */
  public function resetCache(): void;

}
