[增加]1. 增加任务执行超时的参数

Author: AlianBlank

GameFrameX.Core/Abstractions/IActor.cs

@@ -4,71 +4,83 @@ namespace GameFrameX.Core.Abstractions;
 
 /// <summary>
 /// IActor 接口定义
+/// 定义了一个Actor（参与者）的基本行为和属性，用于管理游戏中的实体对象
 /// </summary>
 public interface IActor : IWorker
 {
     /// <summary>
     /// 获取或设置 IActor 的唯一标识
+    /// 用于在系统中唯一标识一个Actor实例
     /// </summary>
     long Id { get; set; }
 
     /// <summary>
     /// 获取是否自动回收
+    /// 标识当前Actor是否可以被系统自动回收释放
     /// </summary>
     bool AutoRecycle { get; }
 
     /// <summary>
     /// 获取工作 Actor
+    /// 返回当前Actor的工作实例，用于处理具体的业务逻辑
     /// </summary>
     IWorkerActor WorkerActor { get; }
 
     /// <summary>
     /// 获取订阅的哈希列表
+    /// 存储当前Actor订阅的所有调度器ID
     /// </summary>
     HashSet<long> ScheduleIdSet { get; }
 
     /// <summary>
     /// 获取或设置 Actor 类型
+    /// 用于标识Actor的具体类型，便于系统进行分类管理
     /// </summary>
     ushort Type { get; set; }
 
     /// <summary>
     /// 清理全部代理
+    /// 清除当前Actor关联的所有组件代理实例
     /// </summary>
     void ClearAgent();
 
     /// <summary>
     /// 反激活所有组件
+    /// 使当前Actor的所有组件进入非激活状态，通常在Actor被回收前调用
     /// </summary>
     /// <returns>一个表示异步操作的任务</returns>
     Task Inactive();
 
     /// <summary>
     /// 根据组件类型获取对应的 IComponentAgent
+    /// 获取指定类型的组件代理实例，如果不存在且isNew为true则创建新实例
     /// </summary>
-    /// <param name="agentType">组件类型</param>
+    /// <param name="agentType">组件类型，指定要获取的组件的具体类型</param>
     /// <param name="isNew">是否当获取为空的时候默认创建，默认值为true</param>
     /// <returns>一个表示异步操作的任务，返回 IComponentAgent 实例</returns>
     Task<IComponentAgent> GetComponentAgent(Type agentType, bool isNew = true);
 
     /// <summary>
     /// 根据组件类型获取对应的 IComponentAgent
+    /// 泛型方法版本，用于获取指定类型的组件代理实例
     /// </summary>
-    /// <typeparam name="T">组件类型</typeparam>
+    /// <typeparam name="T">组件类型，必须实现IComponentAgent接口</typeparam>
     /// <param name="isNew">是否当获取为空的时候默认创建，默认值为true</param>
     /// <returns>一个表示异步操作的任务，返回指定类型的 IComponentAgent 实例</returns>
     Task<T> GetComponentAgent<T>(bool isNew = true) where T : IComponentAgent;
 
     /// <summary>
     /// 设置自动回收标记
+    /// 配置当前Actor是否允许被系统自动回收
     /// </summary>
-    /// <param name="autoRecycle">是否自动回收</param>
+    /// <param name="autoRecycle">是否自动回收，true表示允许自动回收，false表示禁止自动回收</param>
     void SetAutoRecycle(bool autoRecycle);
 
     /// <summary>
     /// Actor 跨天处理
+    /// 处理游戏服务器跨天时Actor需要执行的相关逻辑
     /// </summary>
-    /// <param name="serverDay">服务器运行天数</param>
+    /// <param name="serverDay">服务器运行天数，表示服务器运行的累计天数</param>
     /// <returns>一个表示异步操作的任务</returns>
     Task CrossDay(int serverDay);
 }

GameFrameX.Core/Abstractions/IWorker.cs

@@ -1,56 +1,69 @@
-namespace GameFrameX.Core.Abstractions;
-
-/// <summary>
-/// IWorker接口定义
-/// </summary>
-public interface IWorker
-{
-    /// <summary>
-    /// 发送无返回值的工作指令
-    /// </summary>
-    /// <param name="work">工作内容</param>
-    /// <param name="timeOut">超时时间，默认为int.MaxValue</param>
-    void Tell(Action work, int timeOut = int.MaxValue);
-
-    /// <summary>
-    /// 发送有返回值的工作指令
-    /// </summary>
-    /// <param name="work">工作内容</param>
-    /// <param name="timeOut">超时时间，默认为int.MaxValue</param>
-    void Tell(Func<Task> work, int timeOut = int.MaxValue);
-
-    /// <summary>
-    /// 异步发送无返回值的工作指令
-    /// </summary>
-    /// <param name="work">工作内容</param>
-    /// <param name="timeOut">超时时间，默认为int.MaxValue</param>
-    /// <returns>一个表示异步操作的任务</returns>
-    Task SendAsync(Action work, int timeOut = int.MaxValue);
-
-    /// <summary>
-    /// 异步发送有返回值的工作指令
-    /// </summary>
-    /// <param name="work">工作内容</param>
-    /// <param name="timeOut">超时时间，默认为int.MaxValue</param>
-    /// <typeparam name="T">泛型参数</typeparam>
-    /// <returns>一个表示异步操作的任务，任务结果为委托的返回值</returns>
-    Task<T> SendAsync<T>(Func<T> work, int timeOut = int.MaxValue);
-
-    /// <summary>
-    /// 异步发送有返回值的工作指令
-    /// </summary>
-    /// <param name="work">工作内容</param>
-    /// <param name="timeOut">超时时间，默认为int.MaxValue</param>
-    /// <param name="checkLock">是否检查锁</param>
-    /// <returns>一个表示异步操作的任务</returns>
-    Task SendAsync(Func<Task> work, int timeOut = int.MaxValue, bool checkLock = true);
-
-    /// <summary>
-    /// 异步发送有返回值的工作指令
-    /// </summary>
-    /// <param name="work">工作内容</param>
-    /// <param name="timeOut">超时时间，默认为int.MaxValue</param>
-    /// <typeparam name="T">泛型参数</typeparam>
-    /// <returns>一个表示异步操作的任务，任务结果为委托的返回值</returns>
-    Task<T> SendAsync<T>(Func<Task<T>> work, int timeOut = int.MaxValue);
+namespace GameFrameX.Core.Abstractions;
+
+/// <summary>
+/// 工作者接口定义
+/// 用于处理异步和同步的工作任务，支持超时和取消操作
+/// </summary>
+public interface IWorker
+{
+    /// <summary>
+    /// 发送无返回值的工作指令
+    /// 同步执行指定的工作内容
+    /// </summary>
+    /// <param name="work">需要执行的工作内容委托</param>
+    /// <param name="timeOut">执行超时时间（毫秒），默认为int.MaxValue</param>
+    /// <param name="cancellationToken">用于取消操作的令牌</param>
+    void Tell(Action work, int timeOut = int.MaxValue, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// 发送有返回值的工作指令
+    /// 同步执行指定的异步工作内容
+    /// </summary>
+    /// <param name="work">需要执行的异步工作内容委托</param>
+    /// <param name="timeOut">执行超时时间（毫秒），默认为int.MaxValue</param>
+    /// <param name="cancellationToken">用于取消操作的令牌</param>
+    void Tell(Func<Task> work, int timeOut = int.MaxValue, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// 异步发送无返回值的工作指令
+    /// 异步执行指定的工作内容
+    /// </summary>
+    /// <param name="work">需要执行的工作内容委托</param>
+    /// <param name="timeOut">执行超时时间（毫秒），默认为int.MaxValue</param>
+    /// <param name="cancellationToken">用于取消操作的令牌</param>
+    /// <returns>表示异步操作的任务对象</returns>
+    Task SendAsync(Action work, int timeOut = int.MaxValue, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// 异步发送有返回值的工作指令
+    /// 异步执行指定的同步工作内容并返回结果
+    /// </summary>
+    /// <param name="work">需要执行的工作内容委托</param>
+    /// <param name="timeOut">执行超时时间（毫秒），默认为int.MaxValue</param>
+    /// <param name="cancellationToken">用于取消操作的令牌</param>
+    /// <typeparam name="T">返回结果的类型</typeparam>
+    /// <returns>包含执行结果的异步任务对象</returns>
+    Task<T> SendAsync<T>(Func<T> work, int timeOut = int.MaxValue, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// 异步发送有返回值的工作指令
+    /// 异步执行指定的异步工作内容
+    /// </summary>
+    /// <param name="work">需要执行的异步工作内容委托</param>
+    /// <param name="timeOut">执行超时时间（毫秒），默认为int.MaxValue</param>
+    /// <param name="checkLock">是否在执行前检查锁定状态</param>
+    /// <param name="cancellationToken">用于取消操作的令牌</param>
+    /// <returns>表示嵌套异步操作的任务对象</returns>
+    Task SendAsync(Func<Task> work, int timeOut = int.MaxValue, bool checkLock = true, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// 异步发送有返回值的工作指令
+    /// 异步执行指定的异步工作内容并返回结果
+    /// </summary>
+    /// <param name="work">需要执行的异步工作内容委托</param>
+    /// <param name="timeOut">执行超时时间（毫秒），默认为int.MaxValue</param>
+    /// <param name="cancellationToken">用于取消操作的令牌</param>
+    /// <typeparam name="T">返回结果的类型</typeparam>
+    /// <returns>包含执行结果的异步任务对象</returns>
+    Task<T> SendAsync<T>(Func<Task<T>> work, int timeOut = int.MaxValue, CancellationToken cancellationToken = default);
 }

GameFrameX.Core/Abstractions/IWorkerActor.cs

@@ -1,55 +1,65 @@
-namespace GameFrameX.Core.Abstractions;
-
-/// <summary>
-/// 工作Actor接口定义
-/// </summary>
-public interface IWorkerActor : IWorker
-{
-    /// <summary>
-    /// 判断是否需要入队
-    /// </summary>
-    /// <returns>一个元组，包含是否需要入队的布尔值和调用链ID</returns>
-    (bool needEnqueue, long chainId) IsNeedEnqueue();
-
-    /// <summary>
-    /// 将无返回值的委托入队
-    /// </summary>
-    /// <param name="work">无返回值的委托</param>
-    /// <param name="callChainId">调用链ID</param>
-    /// <param name="discard">是否强制入队</param>
-    /// <param name="timeOut">超时时间</param>
-    /// <returns>一个表示异步操作的任务</returns>
-    Task Enqueue(Action work, long callChainId, bool discard = false, int timeOut = int.MaxValue);
-
-    /// <summary>
-    /// 将有返回值的委托入队
-    /// </summary>
-    /// <param name="work">有返回值的委托</param>
-    /// <param name="callChainId">调用链ID</param>
-    /// <param name="discard">是否强制入队</param>
-    /// <param name="timeOut">超时时间</param>
-    /// <typeparam name="T">泛型参数</typeparam>
-    /// <returns>一个表示异步操作的任务，任务结果为委托的返回值</returns>
-    Task<T> Enqueue<T>(Func<T> work, long callChainId, bool discard = false, int timeOut = int.MaxValue);
-
-    /// <summary>
-    /// 将返回Task的委托入队
-    /// </summary>
-    /// <param name="work">返回Task的委托</param>
-    /// <param name="callChainId">调用链ID</param>
-    /// <param name="discard">是否强制入队</param>
-    /// <param name="timeOut">超时时间</param>
-    /// <returns>一个表示异步操作的任务</returns>
-    Task Enqueue(Func<Task> work, long callChainId, bool discard = false, int timeOut = int.MaxValue);
-
-    /// <summary>
-    /// 将返回Task<T>的委托入队</T>
-    /// </summary>
-    /// <param name="work">返回Task<T>的委托</T></param>
-    /// <param name="callChainId">调用链ID</param>
-    /// <param name="discard">是否强制入队</param>
-    /// <param name="timeOut">超时时间</param>
-    /// <typeparam name="T">泛型参数</typeparam>
-    /// <returns>一个表示异步操作的任务，任务结果为委托的返回值</returns>
-    Task<T> Enqueue<T>(Func<Task<T>> work, long callChainId, bool discard = false, int timeOut = int.MaxValue);
+namespace GameFrameX.Core.Abstractions;
+
+/// <summary>
+/// 工作Actor接口定义
+/// 用于处理异步任务队列的Actor接口，继承自IWorker接口
+/// </summary>
+public interface IWorkerActor : IWorker
+{
+    /// <summary>
+    /// 判断是否需要入队
+    /// 检查当前任务是否需要进入队列进行处理
+    /// </summary>
+    /// <returns>返回一个元组，包含两个值：needEnqueue(bool类型，表示是否需要入队)和chainId(long类型，表示调用链ID)</returns>
+    (bool needEnqueue, long chainId) IsNeedEnqueue();
+
+    /// <summary>
+    /// 将无返回值的委托入队
+    /// 将Action类型的委托添加到任务队列中进行异步处理
+    /// </summary>
+    /// <param name="work">要执行的无返回值委托方法</param>
+    /// <param name="callChainId">用于跟踪调用链的唯一标识符</param>
+    /// <param name="discard">当为true时，表示强制将任务入队，即使队列已满也会尝试入队</param>
+    /// <param name="timeOut">任务执行的超时时间，默认为int.MaxValue</param>
+    /// <param name="cancellationToken">用于取消操作的令牌</param>
+    /// <returns>表示异步操作的Task对象</returns>
+    Task Enqueue(Action work, long callChainId, bool discard = false, int timeOut = int.MaxValue, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// 将有返回值的委托入队
+    /// 将Func<T/>类型的委托添加到任务队列中进行异步处理
+    /// </summary>
+    /// <param name="work">要执行的有返回值委托方法</param>
+    /// <param name="callChainId">用于跟踪调用链的唯一标识符</param>
+    /// <param name="discard">当为true时，表示强制将任务入队，即使队列已满也会尝试入队</param>
+    /// <param name="timeOut">任务执行的超时时间，默认为int.MaxValue</param>
+    /// <param name="cancellationToken">用于取消操作的令牌</param>
+    /// <typeparam name="T">委托返回值的类型</typeparam>
+    /// <returns>表示异步操作的Task<T/>对象，其结果为委托的返回值</returns>
+    Task<T> Enqueue<T>(Func<T> work, long callChainId, bool discard = false, int timeOut = int.MaxValue, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// 将返回Task的委托入队
+    /// 将Func<Task/>类型的委托添加到任务队列中进行异步处理
+    /// </summary>
+    /// <param name="work">要执行的返回Task的异步委托方法</param>
+    /// <param name="callChainId">用于跟踪调用链的唯一标识符</param>
+    /// <param name="discard">当为true时，表示强制将任务入队，即使队列已满也会尝试入队</param>
+    /// <param name="timeOut">任务执行的超时时间，默认为int.MaxValue</param>
+    /// <param name="cancellationToken">用于取消操作的令牌</param>
+    /// <returns>表示异步操作的Task对象</returns>
+    Task Enqueue(Func<Task> work, long callChainId, bool discard = false, int timeOut = int.MaxValue, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// 将返回Task<T/>的委托入队
+    /// 将Func<Task/><T/>>类型的委托添加到任务队列中进行异步处理
+    /// </summary>
+    /// <param name="work">要执行的返回Task<T/>的异步委托方法</param>
+    /// <param name="callChainId">用于跟踪调用链的唯一标识符</param>
+    /// <param name="discard">当为true时，表示强制将任务入队，即使队列已满也会尝试入队</param>
+    /// <param name="timeOut">任务执行的超时时间，默认为int.MaxValue</param>
+    /// <param name="cancellationToken">用于取消操作的令牌</param>
+    /// <typeparam name="T">异步操作返回值的类型</typeparam>
+    /// <returns>表示异步操作的Task<T/>对象，其结果为委托的返回值</returns>
+    Task<T> Enqueue<T>(Func<Task<T>> work, long callChainId, bool discard = false, int timeOut = int.MaxValue, CancellationToken cancellationToken = default);
 }