namespace SKMC.Api.Process.Control
{
    /// <summary>
    /// <para>流程锁</para>
    /// <para>适用于多个执行单元需要互锁的场景</para>
    /// </summary>
    public interface IProcessLocker
    {

        /// <summary>
        /// <para>尝试获取流程锁, 如果锁已被占用则会持续阻塞</para>
        /// <para>如果返回true表示获取锁成功, 可继续执行后续代码</para>
        /// <para>如果返回false表示获取锁失败, 可能是有线程执行了ExitLock让该锁失效</para>
        /// <para>注意：如果获取锁失败, 同样也会执行后续代码可能导致锁定失败! 需要对该返回值进行判断处理</para>
        /// </summary>
        /// <param name="handler">尝试获取锁的对象Id, 如果不传对象Id默认为-1表示公共对象</param>
        /// <returns>true: 成功获取锁, false: 锁已失效</returns>
        bool StartLock(int handler = -1);

        /// <summary>
        /// <para>归还/重置流程锁, 任何线程均可执行</para>
        /// <para>如果尝试释放锁的对象Id不为当前占用锁的对象Id则释放无效</para>
        /// </summary>
        /// <param name="handler">尝试释放锁的对象Id, 如果不传对象Id默认为-1表示公共对象</param>
        void EndLock(int handler = -1);

        /// <summary>
        /// <para>退出锁并让所有执行了StartLock正在阻塞的线程都释放并返回获取锁结果为false</para>
        /// <param name="handler">尝试释放锁的对象Id, 如果不传对象Id默认为-1表示公共对象</param>
        /// </summary>
        void ExitLock(int handler = -1);

        /// <summary>
        /// 强制退出锁(忽略锁的占用对象)并重置锁状态
        /// </summary>
        void ResetLock();
    }
}