feat(coroutine): 添加协程分组管理和优先级支持

GFramework.Core.Abstractions/coroutine/CoroutinePriority.cs

@@ -0,0 +1,33 @@
+namespace GFramework.Core.Abstractions.coroutine;
+
+/// <summary>
+///     协程优先级枚举
+///     定义协程的执行优先级，高优先级的协程会优先执行
+/// </summary>
+public enum CoroutinePriority : byte
+{
+    /// <summary>
+    ///     最低优先级
+    /// </summary>
+    Lowest = 0,
+
+    /// <summary>
+    ///     低优先级
+    /// </summary>
+    Low = 1,
+
+    /// <summary>
+    ///     普通优先级（默认）
+    /// </summary>
+    Normal = 2,
+
+    /// <summary>
+    ///     高优先级
+    /// </summary>
+    High = 3,
+
+    /// <summary>
+    ///     最高优先级
+    /// </summary>
+    Highest = 4
+}

GFramework.Core.Abstractions/coroutine/ICoroutineStatistics.cs

@@ -0,0 +1,68 @@
+namespace GFramework.Core.Abstractions.coroutine;
+
+/// <summary>
+///     协程统计信息接口
+///     提供协程执行的性能统计数据
+/// </summary>
+public interface ICoroutineStatistics
+{
+    /// <summary>
+    ///     获取总协程启动数量
+    /// </summary>
+    long TotalStarted { get; }
+
+    /// <summary>
+    ///     获取总协程完成数量
+    /// </summary>
+    long TotalCompleted { get; }
+
+    /// <summary>
+    ///     获取总协程失败数量
+    /// </summary>
+    long TotalFailed { get; }
+
+    /// <summary>
+    ///     获取当前活跃协程数量
+    /// </summary>
+    int ActiveCount { get; }
+
+    /// <summary>
+    ///     获取当前暂停协程数量
+    /// </summary>
+    int PausedCount { get; }
+
+    /// <summary>
+    ///     获取协程平均执行时间（毫秒）
+    /// </summary>
+    double AverageExecutionTimeMs { get; }
+
+    /// <summary>
+    ///     获取协程最大执行时间（毫秒）
+    /// </summary>
+    double MaxExecutionTimeMs { get; }
+
+    /// <summary>
+    ///     获取按优先级分组的协程数量
+    /// </summary>
+    /// <param name="priority">协程优先级</param>
+    /// <returns>指定优先级的协程数量</returns>
+    int GetCountByPriority(CoroutinePriority priority);
+
+    /// <summary>
+    ///     获取按标签分组的协程数量
+    /// </summary>
+    /// <param name="tag">协程标签</param>
+    /// <returns>指定标签的协程数量</returns>
+    int GetCountByTag(string tag);
+
+    /// <summary>
+    ///     重置统计数据
+    /// </summary>
+    void Reset();
+
+    /// <summary>
+    ///     生成统计报告
+    /// </summary>
+    /// <returns>格式化的统计报告字符串</returns>
+    string GenerateReport();
+}

GFramework.Core.Tests/GlobalUsings.cs

@@ -15,4 +15,6 @@
 global using System.Collections.Generic;
 global using System.Linq;
 global using System.Threading;
-global using System.Threading.Tasks;
+global using System.Threading.Tasks;
+global using NUnit.Framework;
+global using NUnit.Compatibility;

GFramework.Core.Tests/coroutine/CoroutineGroupTests.cs

@@ -0,0 +1,197 @@
+using GFramework.Core.Abstractions.coroutine;
+using GFramework.Core.coroutine;
+using GFramework.Core.coroutine.instructions;
+
+namespace GFramework.Core.Tests.coroutine;
+
+/// <summary>
+///     协程分组管理测试
+/// </summary>
+public sealed class CoroutineGroupTests
+{
+    [Test]
+    public void Run_WithGroup_ShouldAddToGroup()
+    {
+        // Arrange
+        var timeSource = new FakeTimeSource();
+        var scheduler = new CoroutineScheduler(timeSource);
+
+        IEnumerator<IYieldInstruction> TestCoroutine()
+        {
+            yield return new WaitOneFrame();
+        }
+
+        // Act
+        scheduler.Run(TestCoroutine(), group: "TestGroup");
+        scheduler.Run(TestCoroutine(), group: "TestGroup");
+        scheduler.Run(TestCoroutine(), group: "OtherGroup");
+
+        // Assert
+        Assert.That(scheduler.GetGroupCount("TestGroup"), Is.EqualTo(2));
+        Assert.That(scheduler.GetGroupCount("OtherGroup"), Is.EqualTo(1));
+    }
+
+    [Test]
+    public void PauseGroup_ShouldPauseAllCoroutinesInGroup()
+    {
+        // Arrange
+        var timeSource = new FakeTimeSource();
+        var scheduler = new CoroutineScheduler(timeSource);
+        var executionCount = 0;
+
+        IEnumerator<IYieldInstruction> TestCoroutine()
+        {
+            while (true)
+            {
+                executionCount++;
+                yield return new WaitOneFrame();
+            }
+        }
+
+        // Act
+        scheduler.Run(TestCoroutine(), group: "TestGroup");
+        scheduler.Run(TestCoroutine(), group: "TestGroup");
+
+        scheduler.Update(); // 第一次更新，执行计数应为 4（每个协程执行2次）
+        var pausedCount = scheduler.PauseGroup("TestGroup");
+        scheduler.Update(); // 暂停后更新，执行计数不应增加
+
+        // Assert
+        Assert.That(pausedCount, Is.EqualTo(2));
+        Assert.That(executionCount, Is.EqualTo(4)); // 第一次更新时每个协程执行了2次
+    }
+
+    [Test]
+    public void ResumeGroup_ShouldResumeAllCoroutinesInGroup()
+    {
+        // Arrange
+        var timeSource = new FakeTimeSource();
+        var scheduler = new CoroutineScheduler(timeSource);
+        var executionCount = 0;
+
+        IEnumerator<IYieldInstruction> TestCoroutine()
+        {
+            while (true)
+            {
+                executionCount++;
+                yield return new WaitOneFrame();
+            }
+        }
+
+        // Act
+        scheduler.Run(TestCoroutine(), group: "TestGroup");
+        scheduler.Run(TestCoroutine(), group: "TestGroup");
+
+        scheduler.Update(); // 第一次更新
+        scheduler.PauseGroup("TestGroup");
+        scheduler.Update(); // 暂停期间
+        var resumedCount = scheduler.ResumeGroup("TestGroup");
+        scheduler.Update(); // 恢复后更新
+
+        // Assert
+        Assert.That(resumedCount, Is.EqualTo(2));
+        Assert.That(executionCount, Is.EqualTo(6)); // 第一次 4，恢复后 2
+    }
+
+    [Test]
+    public void KillGroup_ShouldKillAllCoroutinesInGroup()
+    {
+        // Arrange
+        var timeSource = new FakeTimeSource();
+        var scheduler = new CoroutineScheduler(timeSource);
+
+        IEnumerator<IYieldInstruction> TestCoroutine()
+        {
+            yield return new WaitOneFrame();
+        }
+
+        // Act
+        scheduler.Run(TestCoroutine(), group: "TestGroup");
+        scheduler.Run(TestCoroutine(), group: "TestGroup");
+        scheduler.Run(TestCoroutine(), group: "OtherGroup");
+
+        var initialCount = scheduler.ActiveCoroutineCount;
+        var killedCount = scheduler.KillGroup("TestGroup");
+
+        // Assert
+        Assert.That(initialCount, Is.EqualTo(3));
+        Assert.That(killedCount, Is.EqualTo(2));
+        Assert.That(scheduler.ActiveCoroutineCount, Is.EqualTo(1));
+        Assert.That(scheduler.GetGroupCount("TestGroup"), Is.EqualTo(0));
+    }
+
+    [Test]
+    public void GetGroupCount_WithNonExistentGroup_ShouldReturnZero()
+    {
+        // Arrange
+        var timeSource = new FakeTimeSource();
+        var scheduler = new CoroutineScheduler(timeSource);
+
+        // Act & Assert
+        Assert.That(scheduler.GetGroupCount("NonExistent"), Is.EqualTo(0));
+    }
+
+    [Test]
+    public void Complete_ShouldRemoveFromGroup()
+    {
+        // Arrange
+        var timeSource = new FakeTimeSource();
+        var scheduler = new CoroutineScheduler(timeSource);
+
+        IEnumerator<IYieldInstruction> TestCoroutine()
+        {
+            yield return new WaitOneFrame(); // 等待一帧后完成
+        }
+
+        // Act
+        scheduler.Run(TestCoroutine(), group: "TestGroup");
+        scheduler.Run(TestCoroutine(), group: "TestGroup");
+
+        Assert.That(scheduler.GetGroupCount("TestGroup"), Is.EqualTo(2));
+
+        scheduler.Update(); // 协程完成
+
+        // Assert
+        Assert.That(scheduler.GetGroupCount("TestGroup"), Is.EqualTo(0));
+    }
+
+    [Test]
+    public void PauseGroup_WithMixedGroups_ShouldOnlyAffectTargetGroup()
+    {
+        // Arrange
+        var timeSource = new FakeTimeSource();
+        var scheduler = new CoroutineScheduler(timeSource);
+        var group1Count = 0;
+        var group2Count = 0;
+
+        IEnumerator<IYieldInstruction> Group1Coroutine()
+        {
+            while (true)
+            {
+                group1Count++;
+                yield return new WaitOneFrame();
+            }
+        }
+
+        IEnumerator<IYieldInstruction> Group2Coroutine()
+        {
+            while (true)
+            {
+                group2Count++;
+                yield return new WaitOneFrame();
+            }
+        }
+
+        // Act
+        scheduler.Run(Group1Coroutine(), group: "Group1");
+        scheduler.Run(Group2Coroutine(), group: "Group2");
+
+        scheduler.Update(); // 第一次更新
+        scheduler.PauseGroup("Group1");
+        scheduler.Update(); // Group1 暂停，Group2 继续
+
+        // Assert
+        Assert.That(group1Count, Is.EqualTo(2)); // Group1 执行了2次（第一次更新）
+        Assert.That(group2Count, Is.EqualTo(3)); // Group2 执行了3次（第一次更新2次，第二次更新1次）
+    }
+}