<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

/**
 * Interface for managing concurrent conversion locks.
 *
 * @internal Runtime service, not part of the supported contrib extension API.
 */
interface LockManagerInterface {

  /**
   * Default maximum concurrent conversions.
   */
  public const int DEFAULT_MAX_CONCURRENT = 2;

  /**
   * Default lock timeout in seconds.
   */
  public const int DEFAULT_LOCK_TIMEOUT = 7200;

  /**
   * Acquires a lock for a media conversion.
   *
   * @param int $mediaId
   *   The media entity ID.
   *
   * @return bool
   *   TRUE if lock was acquired, FALSE if already locked.
   *
   * @throws \Drupal\ffmpeg_media\Exception\ConcurrentLimitException
   *   When maximum concurrent conversions limit is reached.
   */
  public function acquireLock(int $mediaId): bool;

  /**
   * Releases a lock for a media conversion.
   *
   * @param int $mediaId
   *   The media entity ID.
   */
  public function releaseLock(int $mediaId): void;

  /**
   * Checks if a media entity has an active lock.
   *
   * @param int $mediaId
   *   The media entity ID.
   *
   * @return bool
   *   TRUE if locked.
   */
  #[\NoDiscard]
  public function hasLock(int $mediaId): bool;

  /**
   * Gets the count of active locks.
   *
   * @return int
   *   Number of active conversion locks.
   */
  #[\NoDiscard]
  public function getActiveLockCount(): int;

  /**
   * Gets all active locks.
   *
   * @return array<int, array{media_id: int, worker_id: string, acquired_at: int, expires_at: int}>
   *   Array of active lock information.
   */
  #[\NoDiscard]
  public function getActiveLocks(): array;

  /**
   * Checks if the concurrent limit has been reached.
   *
   * @return bool
   *   TRUE if limit is reached.
   */
  #[\NoDiscard]
  public function isLimitReached(): bool;

  /**
   * Gets the maximum concurrent conversions limit.
   *
   * @return int
   *   Maximum allowed concurrent conversions.
   */
  #[\NoDiscard]
  public function getMaxConcurrent(): int;

  /**
   * Cleans up expired and orphaned locks.
   *
   * @return int
   *   Number of locks cleaned up.
   */
  public function cleanupExpiredLocks(): int;

  /**
   * Extends a lock's expiration time.
   *
   * @param int $mediaId
   *   The media entity ID.
   * @param int|null $additionalSeconds
   *   Additional seconds to extend, or NULL for default timeout.
   *
   * @return bool
   *   TRUE if lock was extended, FALSE if lock not found.
   */
  public function extendLock(int $mediaId, ?int $additionalSeconds = NULL): bool;

}
