using System;
using System.Threading;
using System.Threading.Tasks;

namespace Aging.Infrastructure.Contracts
{
    /// <summary>
    /// 资源冲突异常。
    /// 当尝试预约已被其他所有者占用的资源时抛出。
    /// </summary>
    public sealed class ResourceConflictException : Exception
    {
        /// <summary>
        /// 初始化资源冲突异常实例
        /// </summary>
        /// <param name="message">冲突描述信息</param>
        public ResourceConflictException(string message) : base(message)
        {
        }

        /// <summary>
        /// 初始化资源冲突异常实例
        /// </summary>
        /// <param name="message">冲突描述信息</param>
        /// <param name="innerException">内部异常</param>
        public ResourceConflictException(string message, Exception innerException) : base(message, innerException)
        {
        }
    }

    /// <summary>
    /// 资源管理接口。
    /// 提供硬件资源的预约、租约获取和释放功能，确保资源不被多个会话同时占用。
    /// </summary>
    public interface IResourceManager
    {
        /// <summary>
        /// 异步预约资源。
        /// 创建长期预约，阻止其他所有者使用该资源。
        /// </summary>
        /// <param name="owner">所有者令牌</param>
        /// <param name="resource">资源键</param>
        /// <param name="ct">取消令牌</param>
        /// <returns>资源预约实体</returns>
        /// <exception cref="ResourceConflictException">资源已被其他所有者预约时抛出</exception>
        Task<ResourceReservation> ReserveAsync(ResourceOwnerToken owner, ResourceKey resource, CancellationToken ct);

        /// <summary>
        /// 异步获取操作租约。
        /// 在执行具体硬件操作前调用，确保操作期间资源不被抢占。
        /// </summary>
        /// <param name="owner">所有者令牌</param>
        /// <param name="resource">资源键</param>
        /// <param name="ct">取消令牌</param>
        /// <returns>操作租约</returns>
        /// <exception cref="InvalidOperationException">资源未预约或所有者不匹配时抛出</exception>
        Task<IOperationLease> AcquireOperationAsync(ResourceOwnerToken owner, ResourceKey resource, CancellationToken ct);

        /// <summary>
        /// 异步释放资源预约。
        /// 取消对资源的占用，允许其他所有者预约。
        /// </summary>
        /// <param name="owner">所有者令牌</param>
        /// <param name="resource">资源键</param>
        /// <param name="ct">取消令牌</param>
        Task ReleaseReservationAsync(ResourceOwnerToken owner, ResourceKey resource, CancellationToken ct);

        /// <summary>
        /// 检查资源是否已被预约
        /// </summary>
        /// <param name="resource">资源键</param>
        /// <param name="reservation">输出预约实体（如果已预约）</param>
        /// <returns>资源是否已被预约</returns>
        bool IsReserved(ResourceKey resource, out ResourceReservation? reservation);

        /// <summary>
        /// 验证所有者令牌是否匹配指定资源的预约
        /// </summary>
        /// <param name="owner">所有者令牌</param>
        /// <param name="resource">资源键</param>
        /// <returns>所有者是否匹配</returns>
        bool ValidateOwner(ResourceOwnerToken owner, ResourceKey resource);
    }
}