<?php
/**
 * Target lock contract.
 *
 * @package ScheduledChanges
 */

namespace ScheduledChanges\Lock;

/**
 * Extension/testing port for expiring durable locks outside object cache.
 * Production uses wpdb while deterministic tests use memory locks. Contention
 * throws `LockContentionException`; storage failures throw `RuntimeException`.
 */
interface LockManager {
	/**
	 * @param string[] $target_references Stable target references.
	 * @throws LockContentionException When another owner holds a target lock.
	 * @throws \RuntimeException When durable lock storage is unavailable.
	 */
	public function acquire( array $target_references, string $owner_token, int $ttl_seconds ): void;

	/**
	 * @param string[] $target_references Stable target references.
	 * @throws \RuntimeException When durable lock storage is unavailable.
	 */
	public function renew( array $target_references, string $owner_token, int $ttl_seconds ): void;

	/**
	 * @param string[] $target_references Stable target references.
	 * @throws \RuntimeException When durable lock storage is unavailable.
	 */
	public function release( array $target_references, string $owner_token ): void;

	public function staleCount(): int;
}
