diff --git a/CHANGELOG.md b/CHANGELOG.md index aa80d78b..a050e3fe 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,58 @@ 本文件记录**用户可见**的变化。版本号遵循[语义化版本](https://semver.org/lang/zh-CN/) `..`。 -## 2.0.0-beta7(尚未发布) + +## 2.0.0-beta8(尚未发布) + +> 本批仍是 `2.0.0` 的预发布——`2.0.0` 正式版保持未发布。 + +StdUnit.Tags / StdUnit.Tags.Core: **项目级启停的确定化(`State` / `RunId` / 配对保证)** + - `ITagsProjectCtrl` 新增 `State`(`TagsProjectState`:`Stopped` / `Starting` / `Running` / `Stopping`) + 与 `RunId`(每次启动递增)。**"已就绪"的唯一可靠判据是 `State == Running && Project is { }`**: + `Project` 在 `hook` 执行**之前**就已赋值(那时是 `Starting`),单看 `Project != null` 会早于就绪, + 旧文档里"等 `Project != null` 就去 `StopAsync` 会与 hook 竞态"正是这个原因。 + - `TagsProjectEventArgs` 新增 `State` / `RunId` / `Failure`,**移除** `IsStarted` 属性,改为扩展方法 + `TagsProjectEventArgsExtensions.IsStarted()`(等价于 `State == Running`),另提供 + `IsStarted(out ITagsProject project)`:判定与取项目一步完成(返回 `true` 时 `project` 必定可用, + 返回 `false` 时它是 `null`)。构造函数也改为只接收 `State`(不再有 `bool isstarted` 版本): + 事件参数里只有一个"真相",自定义实现与测试替身都不会造出"bool 与 State 各说各话"的参数。 + - **配对保证**:只要派发过一次"已启动",本次运行结束前**必定**派发一次、且只有一次"已停止",两者 `RunId` 相同。 + **运行中**异常结束(如 `RunAsync` 抛错)补发"已停止"并带 `Failure`;`RunAsync` 自行正常返回同样补发(`Failure` 为 null)。 + **启动阶段就失败**(`MakeProject` / `hook` 抛错)的运行没有"已启动",因此也不会补"已停止"——配对约束的是 + "对外宣告过的运行",不是"每次 `StartPollAsync` 都有回执"。此前这些路径只释放项目、不发事件, + 观察者会永远停在"已启动",且通道不会被断开——现在收尾统一:释放项目 → 断开通道 → 派发"已停止"。 + - **停机引起的取消不算失败**:`StopAsync` 触发的 `OperationCanceledException`(取决于 runner 是"正常返回"还是 + "抛 OCE")既不会让 `StartPollAsync` 外抛,也不会写进 `Failure`。判据与 `RunnerCrashed` 一致——看"令牌确实已取消", + 驱动自身原因抛的 `OCE` 仍算失败。 + - **`StopAsync()` 在未运行时是空操作**:不再凭空派发"已停止";重复调用也只派发一次。 + - **订阅者异常不再影响启停**:`StartedOrStopped` 改为逐个订阅者 `try/catch` + Error 日志,后续订阅者仍会收到通知。 + 此前"已启动"在 `StartPollAsync` 的 `try` 内派发,任一观察者抛异常都会**导致项目启动失败**。这与 + `RunnerStarted` 的 fast-fail 语义刻意不同:项目级观测是纯旁路,要参与启动的初始化请用 `hook`。 + - `OnStartingException` 改为**先取快照再调用**,启动过程中替换该属性不会引发二次读取。 + - 新增 `ITagsProjectCtrl.TryGetRunning(out ITagsProject project, out long runId)`:**一次读取**拿到 + "正在运行的项目 + 它的运行标识",且两者必定来自同一次运行。`State` / `Project` / `RunId` 是三个独立属性, + "停止后立刻重启"的窗口里分别读取可能拼出「旧项目 + 新 RunId」;需要配对时(尤其是晚订阅者的补查与去重) + 请用本方法。**"是否已就绪"只认它**:不再提供 `GetRunningProject()` 这类"只返回项目"的便捷包装, + 避免同一件事出现两种读法、两种语义。 + - 自定义 `ITagsProjectCtrl` 实现:需要补上 `State`、`RunId`、`TryGetRunning` 三个成员 + (`Stopped` / `0` / 恒返回 `false` 是合理默认)。 + - 新增扩展方法 `TagsProjectCtrlAttachmentExtensions.AttachRunningProject(Func)`: + 把"给正在运行的项目挂一段观测"的四件固定杂活收敛成一个方法——**晚挂补偿**(先订阅 `StartedOrStopped`, + 再补查 `TryGetRunning`)、**按 `RunId` 去重**、**配对摘除**(停止/换运行时先 `Dispose` 旧句柄)、**加锁串行化**。 + 没有它时,每个观察者都要抄一遍那十几行样板,且很容易写成"分别读 `RunId` 与 `Project`"的错误版本。 + +StdUnit.Tags.WebUi: 观测流改用 `AttachRunningProject` + 控制器提供的 `RunId` + - 不再自己维护轮次订阅列表、`OnStartedOrStopped` 分发与 `_transitionGate`:订阅、晚挂补偿、 + 按 `RunId` 去重、停止/换运行时摘除全部交给 `AttachRunningProject`,hub 只保留"挂上之后做什么" + (建索引、发布状态、逐入口订阅)。`_turnSubscriptions` / `UnsubscribeTurns` / `SyncWithController` 随之删除。 + - 心跳里的周期性"对账"不再需要:`StartedOrStopped` 的配对与晚挂补偿已经覆盖那些场景 + (`ReconcileInterval` 仍作为心跳 tick 的间隔保留)。 + - `epoch` 直接取 `RunId`(`TagsProjectEventArgs.RunId` / `ctrl.RunId`),不再维护私有计数器。 + - 行为保持:正常停止发一帧 `started=false`;**换运行时不发**中间的 `stopped`,只发新的 `started` + (`OnDetached` 用 `TryGetRunning` 区分"真停止"与"换运行")。 + + +## 2.0.0-beta7 > 本批仍是 `2.0.0` 的预发布——`2.0.0` 正式版保持未发布。 diff --git a/samples/StdUnit.Tags.Web/Components/Pages/Monitor.razor b/samples/StdUnit.Tags.Web/Components/Pages/Monitor.razor index 57ddc613..ec3b9723 100644 --- a/samples/StdUnit.Tags.Web/Components/Pages/Monitor.razor +++ b/samples/StdUnit.Tags.Web/Components/Pages/Monitor.razor @@ -1,4 +1,4 @@ -@using System.Collections.ObjectModel +@using System.Collections.ObjectModel @using System.Reactive.Linq @using System.Xml.Linq @using StdUnit.Tags @@ -66,7 +66,7 @@ { var sender = ep.Sender; var args = ep.EventArgs; - this._project = args.IsStarted ? this.projctrl.Project : null; + this._project = args.IsStarted() ? this.projctrl.Project : null; this.InvokeAsync(StateHasChanged); }); diff --git a/samples/WpfDemo/MainWindow.xaml.cs b/samples/WpfDemo/MainWindow.xaml.cs index 848f6016..27c03cfd 100644 --- a/samples/WpfDemo/MainWindow.xaml.cs +++ b/samples/WpfDemo/MainWindow.xaml.cs @@ -1,4 +1,4 @@ -using StdUnit.Tags; +using StdUnit.Tags; using StdUnit.Tags.R3; using R3; using System.Windows; @@ -19,7 +19,7 @@ public MainWindow() var app = App.Current as App ?? throw new InvalidCastException("App.Current is not of type App"); var projobs = app.Ctrl.ObserveStartedOrStopped() - .Select(evt => evt.IsStarted ? evt.Project : null) + .Select(evt => evt.IsStarted() ? evt.Project : null) // 测点项目由后台线程在 Application_Startup 中启动,可能早于本窗口构造; // StartedOrStopped 是普通事件、不会重放历史记录,因此用当前 Project 作首值兜底。 .Prepend(() => app.Ctrl.Project) diff --git a/src/StdUnit.Tags.Core/Projects/ITagsProjectCtrl.cs b/src/StdUnit.Tags.Core/Projects/ITagsProjectCtrl.cs index 687f229f..4624c7ff 100644 --- a/src/StdUnit.Tags.Core/Projects/ITagsProjectCtrl.cs +++ b/src/StdUnit.Tags.Core/Projects/ITagsProjectCtrl.cs @@ -2,6 +2,28 @@ namespace StdUnit.Tags; +/// +/// 测点项目的运行状态。
+/// 只有 与 是"稳定态", +/// 也是 唯一会派发的两个状态。
+/// / 是过渡态,只用于让 +/// 能如实反映"正在启动/正在停止",不会单独派发事件。 +///
+public enum TagsProjectState +{ + /// 未运行:从未启动、已停止,或启动失败收尾之后。 + Stopped = 0, + + /// 正在启动:项目实例已创建,正在执行 hook,轮询尚未开始。 + Starting = 1, + + /// 运行中:hook 已执行完,轮询进行中。此时 必不为 null。 + Running = 2, + + /// 正在停止:已发出取消,正在等待轮询退出、释放项目、断开通道。 + Stopping = 3, +} + /// /// 测点项目控制器接口。 /// 核心方法是
@@ -11,18 +33,68 @@ namespace StdUnit.Tags; public interface ITagsProjectCtrl { /// - /// 测点项目,如果测点项目未启动,则为null + /// 当前运行状态,可随时查询(不依赖事件)。
+ /// 判断"是否已就绪"请用 : + /// 在 hook 执行之前就已赋值(此时状态是 ), + /// 单看 Project != null 会早于"项目确实已就绪"。 + ///
+ TagsProjectState State { get; } + + /// + /// 当前(或最近一次)运行的标识:每次 StartPollAsync 递增,与 + /// 同源。
+ /// 用于把"事件"和"事后补查到的状态"对上。
+ /// 需要与 成对使用(判断"现在跑的是哪一次")时,请改用 + /// :两个属性是两次独立读取,"停止后立刻重启"的窗口里可能读到 + /// 「旧项目 + 新 RunId」这种不一致的组合。 + ///
+ long RunId { get; } + + /// + /// 一次读取拿到"正在运行的项目 + 它的运行标识",保证两者来自同一次运行。
+ /// 返回值等价于"读到的瞬间 是 且 + /// 非 null",但状态、项目、运行号是同一次快照读出的, + /// 不存在"分两次读、中间被一次启停插进来"的问题。观察者晚启动、需要补查当前状态时,用它最稳。
+ ///
+ /// 观察者晚于项目启动时,用它补偿:先订阅 , + /// 再调用本方法一次,覆盖"订阅之前已经发生的变化"。 + ///
+ /// 正在运行的项目 + /// 该项目的运行标识,与 同源 + /// 当前处于 时为 true + bool TryGetRunning(out ITagsProject project, out long runId); + + /// + /// 测点项目, / 时非 null, + /// 其余状态为 null。
+ ///
+ /// 注意,非null并不意味着项目在执行。要获取当前正在执行的项目,使用。 ///
ITagsProject? Project { get; } /// /// 当正在启动测点项目时发生异常时的回调。
- /// 返回值表示是否已经处理了异常,如果返回true,则不会再向外层抛出异常。 + /// 返回值表示是否已经处理了异常,如果返回true,则不会再向外层抛出异常。
+ /// 该属性在每次读取时取值:启动过程中被替换不会影响本次启动已取到的委托。 ///
Func>? OnStartingException { get; set; } /// - /// 测点项目启动或停止事件 + /// 测点项目启动或停止事件。只在两个稳定态上派发( / ):
+ /// + /// 配对由库保证:只要派发过一次"已启动",本次运行结束前必定派发一次"已停止", + /// 两者的 相同。"运行中"异常结束(如 RunAsync 抛错)同样补发, + /// 此时 带异常;正常停机为 null(停机引起的 + /// 也算正常停机)。启动阶段就失败(MakeProject / hook 抛错) + /// 的运行没有"已启动",因此也不会有"已停止"——配对约束的是"对外宣告过的运行",不是"每次 StartPollAsync 都有回执"。 + /// 热事件:只在状态迁移时派发一次,晚订阅者收不到历史通知。 + /// 需要"当前是否已启动"请查 ,需要"现在就是这个状态"请自行补偿。 + /// 订阅者抛异常不影响启停:逐个 try/catch 并记 Error 日志,后续订阅者仍会收到通知 + /// (与 的 fast-fail 语义不同——项目级观测是纯旁路, + /// 要参与启动的初始化请用 hook)。 + /// 派发"已停止"事件时,轮询已退出、项目已释放、通道已断开, 为 null; + /// 此时可以安全复用通道实例、目录,或替换 XML。 + /// ///
event TagsProjectStartedOrStopped? StartedOrStopped; @@ -30,6 +102,10 @@ public interface ITagsProjectCtrl /// 启动测点项目轮询。
/// 此方法通常不会结束,除非测点项目被停止或在启动阶段发生异常。
/// 如果在项目启动阶段就发生异常,则会触发回调。
+ /// 状态与会话:进入时 变为 (此时 已非 null、 + /// hook 正在执行),hook 完成后变为 并派发"已启动"; + /// 无论正常结束还是异常结束,退出前都会回到 , + /// 并且只要派发过"已启动",就必定补派一次"已停止"(异常时 非 null)。
/// 示例: /// { @@ -59,7 +135,8 @@ public interface ITagsProjectCtrl /// 语义:发取消信号 → 等待轮询循环退出(有界)→ 释放项目 → 断开通道 → 触发 的"已停止"事件。
/// 因此返回后可以安全地复用通道实例/项目目录或替换 XML;"已停止"事件也因此是确定性信号。
/// 唯一的例外是底层驱动不响应取消:此时等待会在 PollExitWaitTimeout(默认 30s)后超时, - /// 记一条 Warning 并继续清理,不再等待循环退出。 + /// 记一条 Warning 并继续清理,不再等待循环退出。
+ /// 未运行时调用是空操作:不会派发"已停止"(重复调用也只会派发一次)。 ///
/// Task StopAsync(); @@ -72,14 +149,19 @@ public interface ITagsProjectCtrl public class TagsProjectEventArgs : EventArgs { /// - /// c'tor + /// c'tor。控制器与自定义 实现都用它构造事件参数—— + /// 只有 这一个"真相",不再存在"bool 与 State 各说各话"的可能。 /// - /// - /// - public TagsProjectEventArgs(bool isstarted, ITagsProject? project) + /// 本次通知对应的状态(只会是 或 ) + /// 项目实例;停止事件传 null + /// 运行标识;自定义实现没有这个概念时可留默认值 + /// 导致本次运行结束的异常;正常停机传 null + public TagsProjectEventArgs(TagsProjectState state, ITagsProject? project, long runId = 0, Exception? failure = null) { - this.IsStarted = isstarted; - Project = project; + this.State = state; + this.Project = project; + this.RunId = runId; + this.Failure = failure; } /// @@ -89,9 +171,22 @@ public TagsProjectEventArgs(bool isstarted, ITagsProject? project) public ITagsProject? Project { get; } /// - /// 测点项目是否启动 + /// 本次通知对应的状态:只会是 或 。 + /// + public TagsProjectState State { get; } + + /// + /// 运行标识:每次 StartPollAsync 递增。"已启动"与"已停止"的 RunId 相同, + /// 可以据此配对、关联日志(例如界面推送流用它区分不同批次的快照)。 + /// + public long RunId { get; } + + /// + /// 导致本次运行结束的异常:运行中异常结束(如 RunAsync 抛错)时非 null; + /// 正常停机(StopAsync,含停机引起的 )为 null。 + /// "已启动"通知里恒为 null;启动阶段就失败的运行不会派发任何事件,因此也谈不上 Failure。 /// - public bool IsStarted { get; } + public Exception? Failure { get; } } /// diff --git a/src/StdUnit.Tags.Core/Projects/TagsProjectCtrlAttachmentExtensions.cs b/src/StdUnit.Tags.Core/Projects/TagsProjectCtrlAttachmentExtensions.cs new file mode 100644 index 00000000..ce058d27 --- /dev/null +++ b/src/StdUnit.Tags.Core/Projects/TagsProjectCtrlAttachmentExtensions.cs @@ -0,0 +1,143 @@ +using System; + +namespace StdUnit.Tags; + +/// +/// "给正在运行的项目挂一段观测"的通用封装。 +/// +public static class TagsProjectCtrlAttachmentExtensions +{ + /// + /// 把一段观测挂到"当前正在运行的项目"上,并在项目停止、换运行、或返回的句柄被 Dispose 时自动摘掉。
+ ///
+ /// 调用方只需要提供 ,其余样板由本方法负责: + /// + /// 晚挂补偿:先订阅 ,再立刻补查一次 + /// ()——观察者比项目晚启动时,"已启动"那次热事件已经过去了。 + /// 去重:补查与事件可能描述同一次运行,按 RunId 判定, 每次运行最多调用一次。 + /// 配对摘除:收到"已停止"、或发现 RunId 变了,先 Dispose 上一次 返回的句柄,再挂新的。 + /// 串行化:内部加锁,"事件线程"与"调用方线程"同时触发也不会重复挂载。 + /// + ///
+ /// 异常: 抛出的异常在构造时原样抛出(同时会撤掉事件订阅,不留悬挂); + /// 若是在"已启动"事件里触发,则由 的派发器接住并记日志, + /// 项目启停不受影响;该次运行不会被标记为已挂载,下一次通知会重试。
+ ///
+ /// 回调线程: / 上一次返回的 Dispose 运行在 + /// StartPollAsync / StopAsync 的执行上下文(不是轮询线程),应当尽快返回。 + ///
+ /// 项目控制器 + /// + /// 挂载回调:参数是正在运行的项目及其运行标识(与 同源)。 + /// 返回的句柄会在解挂时被 Dispose;可以返回一个把多个订阅打包起来的复合句柄。 + /// + /// 解挂句柄:Dispose 即退订事件并摘掉当前挂载(幂等) + /// 或 为 null + public static IDisposable AttachRunningProject( + this ITagsProjectCtrl ctrl, + Func attach) + { + if (ctrl is null) + { + throw new ArgumentNullException(nameof(ctrl)); + } + + if (attach is null) + { + throw new ArgumentNullException(nameof(attach)); + } + + return new Attachment(ctrl, attach); + } + + /// 一次"挂到运行中项目"的会话。 + private sealed class Attachment : IDisposable + { + private readonly object _gate = new(); + private readonly ITagsProjectCtrl _ctrl; + private readonly Func _attach; + + private IDisposable? _subscription; + + /// 已挂载的运行标识;-1 表示当前没有挂载(RunId 从 1 开始)。 + private long _attachedRunId = -1; + + private bool _disposed; + + internal Attachment(ITagsProjectCtrl ctrl, Func attach) + { + this._ctrl = ctrl; + this._attach = attach; + + // 顺序不能反:先订阅再补查,才覆盖"订阅之前已经发生的变化"。 + ctrl.StartedOrStopped += this.OnStartedOrStopped; + try + { + this.Sync(); + } + catch + { + // 构造失败不能让事件订阅留在外面(否则 _ctrl 会一直引用一个半死的对象)。 + ctrl.StartedOrStopped -= this.OnStartedOrStopped; + throw; + } + } + + private void OnStartedOrStopped(ITagsProjectCtrl sender, TagsProjectEventArgs args) => this.Sync(); + + /// 让"当前挂载"与"当前运行"对齐:该挂的挂、该摘的摘、已挂过的跳过。 + private void Sync() + { + lock (this._gate) + { + if (this._disposed) + { + return; + } + + // TryGetRunning 是单次读取:项目与 RunId 必定来自同一次运行。 + if (!this._ctrl.TryGetRunning(out var project, out var runId)) + { + this.Detach(); // 已停止 + return; + } + + if (runId == this._attachedRunId) + { + return; // 同一次运行:补查与事件都走到过这里 + } + + this.Detach(); // 换运行了:先摘旧的 + + var subscription = this._attach(project, runId); + this._subscription = subscription; + this._attachedRunId = runId; // 即便回调返回 null,也算处理过这次运行 + } + } + + /// 摘掉当前挂载(幂等)。 + private void Detach() + { + var subscription = this._subscription; + this._subscription = null; + this._attachedRunId = -1; + + subscription?.Dispose(); + } + + public void Dispose() + { + lock (this._gate) + { + if (this._disposed) + { + return; + } + + this._disposed = true; + this._ctrl.StartedOrStopped -= this.OnStartedOrStopped; + this.Detach(); + } + } + } +} diff --git a/src/StdUnit.Tags.Core/Projects/TagsProjectEventArgsExtensions.cs b/src/StdUnit.Tags.Core/Projects/TagsProjectEventArgsExtensions.cs new file mode 100644 index 00000000..b143c628 --- /dev/null +++ b/src/StdUnit.Tags.Core/Projects/TagsProjectEventArgsExtensions.cs @@ -0,0 +1,53 @@ +using System; + +namespace StdUnit.Tags; + +/// +/// 的扩展方法。 +/// +public static class TagsProjectEventArgsExtensions +{ + /// + /// 本次通知是否为"已启动"。等价于 args.State == TagsProjectState.Running。
+ /// 做成扩展方法而不是属性:事件参数里只保留 这一个"真相", + /// 不再有"派生属性可能与 State 不一致"的空间(自定义实现、手写测试替身都不会跑偏)。
+ /// 需要同时拿到项目时用 , + /// 可以省掉调用点的 Project is { } 判断。 + ///
+ /// 事件参数 + /// 是"已启动"通知时为 true + /// 为 null + public static bool IsStarted(this TagsProjectEventArgs args) => args.IsStarted(out _); + + /// + /// 本次通知是否为"已启动",是则一并交出项目实例。
+ /// 判定比无参版本更严格:State == Running 且 Project 非 null 才返回 true。 + /// 因此返回 true 时 必定可用,返回 false 时它是 null + /// ——刻意不提供"半截状态",免得调用点再判一次空。
+ ///
+ /// 为什么用 out 而不是返回可空值:Core 同时编译 net472,那里没有 NotNullWhen 可空标注, + /// 返回可空值会让调用点在 if 里被迫写 !;而 out 形参在这里天然是"成功才有值"。 + ///
+ /// 事件参数 + /// 处于运行中的项目;未启动时被置为 null + /// 是"已启动"通知且项目可用时为 true + /// 为 null + public static bool IsStarted(this TagsProjectEventArgs args, out ITagsProject project) + { + if (args is null) + { + throw new ArgumentNullException(nameof(args)); + } + + if (args.State == TagsProjectState.Running && args.Project is { } running) + { + project = running; + return true; + } + + // 返回 false 时该 out 形参不可用;声明成非可空是为了让调用点在 if 里直接使用, + // 这里的 null! 只是满足编译器,不做任何运行时保证的让步。 + project = null!; + return false; + } +} diff --git a/src/StdUnit.Tags.WebUi/Core/TagsStreamHub.cs b/src/StdUnit.Tags.WebUi/Core/TagsStreamHub.cs index 3e1a7577..e4e49c7e 100644 --- a/src/StdUnit.Tags.WebUi/Core/TagsStreamHub.cs +++ b/src/StdUnit.Tags.WebUi/Core/TagsStreamHub.cs @@ -15,7 +15,8 @@ namespace StdUnit.Tags.WebUi; /// 启动时机:由 MapTagsStream()()启动—— /// 映射端点必然发生在任何请求之前,也早于 StartPollAsync,因此不依赖 Generic Host 的 /// IHostedService 机制;启动后运行期的状态迁移一律以 为准 -/// (见 )。 +/// (订阅、晚挂补偿、按运行去重都交给 , +/// hub 自己只负责"挂上之后做什么":见 )。 /// /// /// 停止时机:由 在宿主的 ApplicationStopping 上调用 @@ -27,7 +28,7 @@ namespace StdUnit.Tags.WebUi; /// StopAsync 就不能再 StartAsync(实测两边都抛 ), /// 所以 在 之后是 no-op,而不是"再起一遍"。 /// 运行期会反复启停的是被观测的项目(),那条路径不需要重启 hub: -/// 见 / (每次启动递增 epoch)。 +/// 见 / (每次启动递增 epoch)。 /// /// /// 线程模型:轮次回调在轮询线程上执行,只做 O(改动的点) 的字典写入 + 一次 TryWrite, @@ -41,27 +42,23 @@ internal sealed class TagsStreamHub : ITagsStreamHub, IDisposable private readonly TagsStreamOptions _options; private readonly ILogger? _logger; - /// 订阅者集合与状态发布。_transitionGate → _gate 是唯一允许的加锁顺序。 + /// 订阅者集合与状态发布。 private readonly object _gate = new(); - /// 启动/停止的状态迁移串行化(避免事件与对账线程同时迁移)。 - private readonly object _transitionGate = new(); - private readonly HashSet _pipers = new(); private readonly Channel _pending; /// - /// 当前项目上的轮次订阅句柄(只在 下访问)。
- /// 项目停止/切换、或 hub 自己停止时必须退订:否则已释放的项目会因为委托引用而多活, - /// 回调也会继续打到已经停掉的 hub 上。 + /// "挂到当前运行中的项目"的会话:订阅/退订轮次回调、晚挂补偿、按运行去重、配对摘除都由 + /// 负责。 + /// 换运行时旧会话会被它自己摘掉,所以这里只需要持有"最新一次"的句柄。 ///
- private readonly List _turnSubscriptions = new(); + private IDisposable? _attachment; private volatile ProjectIndex? _index; private volatile ITagsProject? _project; private volatile StateDto _state = new(0, false, null); - private long _epoch; private int _pipersCount; private int _overflow; private int _started; @@ -139,12 +136,11 @@ public void Start() var cts = new CancellationTokenSource(); this._cts = cts; - this._ctrl.StartedOrStopped += this.OnStartedOrStopped; this._pumpTask = Task.Run(() => this.PumpAsync(cts.Token), CancellationToken.None); this._heartbeatTask = Task.Run(() => this.HeartbeatAsync(cts.Token), CancellationToken.None); - // 订阅之前项目可能就已经在跑(hub 启动得晚):先对一次账。 - this.SyncWithController(); + // 订阅 + 晚挂补偿 + 按运行去重,一次交给库:hub 比项目晚启动时也接得上。 + this._attachment = this._ctrl.AttachRunningProject(this.AttachProject); } /// @@ -154,8 +150,6 @@ public void Start() /// public void Stop() { - this._ctrl.StartedOrStopped -= this.OnStartedOrStopped; - lock (this._gate) { if (Interlocked.Exchange(ref this._stopped, 1) != 0) @@ -174,11 +168,9 @@ public void Stop() Interlocked.Exchange(ref this._pipersCount, 0); } - // 停止观测后不再接收轮次通知:退订并把句柄还给项目(避免已释放的项目被委托引用拖住)。 - lock (this._transitionGate) - { - this.UnsubscribeTurns(); - } + // 停止观测后不再接收轮次通知:摘掉挂载(会退订并把句柄还给项目, + // 避免已释放的项目被委托引用拖住)。此时 _stopped 已置位,不会再多播一帧"已停止"。 + Interlocked.Exchange(ref this._attachment, null)?.Dispose(); var cts = Interlocked.Exchange(ref this._cts, null); if (cts is null) @@ -315,141 +307,131 @@ public IReadOnlyList> BuildSyncFrames(SseFramesPiper piper) /// public void Dispose() => this.Stop(); - private void OnStartedOrStopped(ITagsProjectCtrl sender, TagsProjectEventArgs args) + /// + /// 挂到一次运行上:建索引、发布"已运行"状态、并给每个入口订阅轮次回调。
+ /// 由 在"某次运行就绪"时调用一次 + /// (同一次运行只会调用一次,晚挂/重启/去重由它负责)。返回的句柄在停止或换运行时被 Dispose。 + ///
+ private IDisposable AttachProject(ITagsProject project, long runId) { + ProjectIndex index; try { - if (args.IsStarted && args.Project is not null) - { - this.OnProjectStarted(args.Project); - } - else - { - this.OnProjectStopped(); - } + index = ProjectIndex.Build(runId, project); } catch (Exception ex) { - // ⚠ "已启动"是在 TagsProjectCtrl.StartPollAsync 的 try 里同步派发的: - // 从这里抛出会被当作启动失败并让 StartPollAsync 抛错(项目随即被释放)。 - // 观测流的问题绝不允许影响项目启动。 - this._logger?.LogError(ex, "观测流处理 StartedOrStopped 时出错"); + // 索引建不起来:不发布状态、也不订阅轮次。下一次运行会重新尝试。 + this._logger?.LogError(ex, "构建观测索引失败(项目根目录={ProjectRoot})", project.ProjectRoot); + return new ProjectAttachment(this, runId, new List(0)); } - } - private void OnProjectStarted(ITagsProject project) - { - lock (this._transitionGate) + lock (this._gate) { - if (ReferenceEquals(project, this._project)) + this._project = project; + this._index = index; + this._state = new StateDto(runId, true, project.ProjectRoot); + this.Broadcast(SseFrames.State(this._state)); + foreach (var subscriber in this._pipers) { - return; + subscriber.MarkResync(); } + } - // 换项目(或上一次"已停止"没派发到):先把旧项目上的订阅摘干净,再挂新的。 - this.UnsubscribeTurns(); - - var epoch = Interlocked.Increment(ref this._epoch); - ProjectIndex index; - try - { - index = ProjectIndex.Build(epoch, project); - } - catch (Exception ex) + // 运行期也能订阅(从下一轮生效):hub 晚于轮询启动时,这里就是在补挂回调。 + var subscriptions = new List(index.Entries.Count); + foreach (var entry in index.Entries) + { + if (Volatile.Read(ref this._stopped) != 0) { - this._logger?.LogError(ex, "构建观测索引失败(项目根目录={ProjectRoot})", project.ProjectRoot); - return; + // 已经停机:不再补挂,否则会留下指向已停止 hub 的回调。 + break; } - lock (this._gate) + var entryKey = entry.Key; + try { - this._project = project; - this._index = index; - this._state = new StateDto(epoch, true, project.ProjectRoot); - this.Broadcast(SseFrames.State(this._state)); - foreach (var subscriber in this._pipers) + subscriptions.Add(project.SubscribeTurnProcess(entryKey, (_, _, _) => { - subscriber.MarkResync(); - } + this.OnTurn(runId, entryKey); + return Task.CompletedTask; + })); } - - // 运行期也能订阅(从下一轮生效):hub 晚于轮询启动时,这里就是在补挂回调。 - foreach (var entry in index.Entries) + catch (Exception ex) { - if (Volatile.Read(ref this._stopped) != 0) - { - // 已经停机:不再补挂,否则会留下指向已停止 hub 的回调。 - break; - } - - var entryKey = entry.Key; - try - { - this._turnSubscriptions.Add(project.SubscribeTurnProcess(entryKey, (_, _, _) => - { - this.OnTurn(epoch, entryKey); - return Task.CompletedTask; - })); - } - catch (Exception ex) - { - this._logger?.LogWarning( - ex, - "无法为入口 {Entry} 订阅轮次回调(项目可能已释放):该入口只能观测结构,观测不到值", - entryKey); - } + this._logger?.LogWarning( + ex, + "无法为入口 {Entry} 订阅轮次回调(项目可能已释放):该入口只能观测结构,观测不到值", + entryKey); } } + + return new ProjectAttachment(this, runId, subscriptions); } - /// 退订当前项目的全部轮次订阅(调用方必须持有 )。 - private void UnsubscribeTurns() + /// + /// 一次挂载的句柄:退订该运行上的全部轮次回调,并在"真正停止"时补发一帧状态。
+ /// 换运行时也会被调用(新运行还没发布状态),此时不发帧——由新运行的"已运行"帧接续, + /// 避免客户端看到 started → stopped → started 的多余抖动。 + ///
+ private sealed class ProjectAttachment : IDisposable { - foreach (var subscription in this._turnSubscriptions) + private readonly TagsStreamHub _hub; + private readonly long _runId; + private List? _subscriptions; + + internal ProjectAttachment(TagsStreamHub hub, long runId, List subscriptions) { - subscription.Dispose(); + this._hub = hub; + this._runId = runId; + this._subscriptions = subscriptions; } - this._turnSubscriptions.Clear(); - } - - private void OnProjectStopped() - { - lock (this._transitionGate) + public void Dispose() { - this.UnsubscribeTurns(); - - lock (this._gate) + var subscriptions = Interlocked.Exchange(ref this._subscriptions, null); + if (subscriptions is null) { - if (this._project is null) - { - return; - } + return; + } - this._project = null; - this._index = null; - this._state = new StateDto(this._state.Epoch, false, this._state.ProjectRoot); - this.Broadcast(SseFrames.State(this._state)); + foreach (var subscription in subscriptions) + { + subscription.Dispose(); } + + this._hub.OnDetached(this._runId); } } /// - /// 对账:以 为准,纠正"未收到事件"的状态差异 - /// (例如 RunAsync 异常退出时项目被释放但不会派发"已停止")。 + /// 某次运行被摘除后的收尾:只有"项目确实停了"才发布"已停止"。 + /// hub 自己停机(_stopped)或只是换运行时不发帧。 /// - private void SyncWithController() + private void OnDetached(long runId) { - var project = this._ctrl.Project; - if (project is null) + if (Volatile.Read(ref this._stopped) != 0) + { + return; + } + + if (this._ctrl.TryGetRunning(out _, out _)) { - this.OnProjectStopped(); + // 换运行:新运行的"已运行"帧紧跟其后,这里不必先发一帧 stopped。 return; } - if (!ReferenceEquals(project, this._project)) + lock (this._gate) { - this.OnProjectStarted(project); + if (this._project is null || this._state.Epoch != runId) + { + return; // 已经被别的运行取代(或从未发布过) + } + + this._project = null; + this._index = null; + this._state = new StateDto(this._state.Epoch, false, this._state.ProjectRoot); + this.Broadcast(SseFrames.State(this._state)); } } @@ -534,15 +516,6 @@ private async Task HeartbeatAsync(CancellationToken ct) { while (await timer.WaitForNextTickAsync(ct).ConfigureAwait(false)) { - try - { - this.SyncWithController(); - } - catch (Exception ex) - { - this._logger?.LogError(ex, "观测流对账失败"); - } - if (DateTime.UtcNow >= nextPing) { nextPing = DateTime.UtcNow + this._options.HeartbeatInterval; diff --git a/src/StdUnit.Tags/TagsProject/TagsProjectCtrl.cs b/src/StdUnit.Tags/TagsProject/TagsProjectCtrl.cs index 4a5b5214..f836b768 100644 --- a/src/StdUnit.Tags/TagsProject/TagsProjectCtrl.cs +++ b/src/StdUnit.Tags/TagsProject/TagsProjectCtrl.cs @@ -24,12 +24,91 @@ public TagsProjectCtrl(IServiceScopeFactory ssf, ILogger logger } /// - public ITagsProject? Project { get; private set; } + public ITagsProject? Project => this._project; + + /// + public TagsProjectState State => (TagsProjectState)Volatile.Read(ref this._state); + + /// + public long RunId => Volatile.Read(ref this._runId); + + /// + public bool TryGetRunning(out ITagsProject project, out long runId) + { + // 单次 volatile 读:Project 与 RunId 来自同一个不可变快照,绝不会拼出"旧项目 + 新 RunId"。 + if (this._running is { } snapshot) + { + project = snapshot.Project; + runId = snapshot.RunId; + return true; + } + + project = null!; + runId = 0; + return false; + } + + /// + /// "正在运行的项目 + 它的运行标识"的不可变快照。只在 期间非 null, + /// 用于让 能用一次读取取到配对的一对值。 + /// + private sealed class RunSnapshot + { + internal RunSnapshot(ITagsProject project, long runId) + { + this.Project = project; + this.RunId = runId; + } + + internal ITagsProject Project { get; } + + internal long RunId { get; } + } + + private volatile RunSnapshot? _running; + + private volatile ITagsProject? _project; + + /// + /// 的底层存储(用 读写,保证 可跨线程查询)。 + /// + private int _state = (int)TagsProjectState.Stopped; CancellationTokenSource? _cts; private int _lock = 0; + #region 单次运行的会话状态 + // 下面这些字段都由 _lock 串行化:同一时刻最多只有一次运行,所以进入 StartPollAsync 后重置即可。 + // 但清理路径可能由 StartPollAsync 的 finally 或 StopAsync 之一执行,故用 Interlocked 保证"只做一次"。 + + /// 运行标识,每次启动递增;"已启动"/"已停止"携带同一个值,便于配对。 + private long _runId; + + /// 本次运行是否已对外派发过"已启动"(只有派发过才需要补"已停止")。 + private int _startedNotified; + + /// 本次运行是否已派发过"已停止"(保证最多一次)。 + private int _stopNotified; + + /// 通道是否已断开(保证最多一次)。 + private int _channelsDisconnected; + + /// 是否已由 接管收尾(此时 的 finally 不再重复断开通道/派发事件)。 + private int _stopping; + + /// 导致本次运行结束的异常;正常停机为 null。会随"已停止"事件一起派发。 + private volatile Exception? _failure; + #endregion + + /// + /// 离开 时清空快照:此后 立刻返回 false, + /// 不会在停机过程中继续交出项目。 + /// + private void ClearRunning() => this._running = null; + + private void SetState(TagsProjectState state) => Volatile.Write(ref this._state, (int)state); + /// /// "轮询循环已退出"的信号:由 的 finally 置位, 等它。 /// @@ -46,11 +125,14 @@ public TagsProjectCtrl(IServiceScopeFactory ssf, ILogger logger /// public async Task StartPollAsync(string? dir, XElement? root, Func hook) { + // 防止重复启动 if (Interlocked.CompareExchange(ref _lock, 1, 0) != 0) { - if (this.OnStartingException != null) + // 取一次快照再用:属性可能在启动过程中被替换 + var onStartingException = this.OnStartingException; + if (onStartingException != null) { - var handled = await this.OnStartingException(new InvalidOperationException("当前测点项目已经启动!")); + var handled = await onStartingException(new InvalidOperationException("当前测点项目已经启动!")); if (handled) { return; @@ -60,47 +142,75 @@ public async Task StartPollAsync(string? dir, XElement? root, Func(TaskCreationOptions.RunContinuationsAsynchronously); this._pollExitSource = exitSource; - using var scope = this._ssf.CreateScope(); - var sp = scope.ServiceProvider; - + // 这两个声明在 try 之外: + // - ct 供 catch 的 when 过滤条件使用(try 块内声明的局部变量在 catch 里不在作用域内); + // - scope 交给 finally 释放(项目里的对象可能引用作用域内的服务,所以必须先放项目、再放作用域)。 + CancellationToken ct = default; + IServiceScope? scope = null; try { - this._cts = new CancellationTokenSource(); + scope = this._ssf.CreateScope(); + var sp = scope.ServiceProvider; + + var cts = new CancellationTokenSource(); + this._cts = cts; + ct = cts.Token; var project = sp.MakeProject(dir, root); - this.Project = project; - var ct = _cts.Token; + this._project = project; await hook(project, sp, ct); - this.StartedOrStopped?.Invoke(this, new TagsProjectEventArgs(true, project)); + + // hook 已执行完、轮询即将开始:这是唯一的"已就绪"时刻 + this.SetState(TagsProjectState.Running); + this._running = new RunSnapshot(project, runId); + Volatile.Write(ref this._startedNotified, 1); + this.RaiseStartedOrStopped(new TagsProjectEventArgs(TagsProjectState.Running, project, runId, null)); + await project.RunAsync(ct); } + catch (OperationCanceledException) when (ct.IsCancellationRequested) + { + // 正常停机:取消不是失败(与 RunnerCrashed 的判据一致)。不记 Error、不填 Failure、不外抛—— + // 否则 StopAsync 引发的 OCE 会让每次正常停机都表现成"启动失败"。 + } catch (Exception ex) { + this._failure = ex; this._logger.LogError(ex, "TagsProjectCtrl.StartPollAsync error"); - // 如果用户没有注册OnStartException回调,则直接抛出异常 - if (this.OnStartingException == null) + // 取一次快照再用:属性可能在启动过程中被替换 + var onStartingException = this.OnStartingException; + if (onStartingException == null) { throw; } - var handled = await this.OnStartingException(ex); - + var handled = await onStartingException(ex); // 如果用户处理了异常,则不再向外抛出 if (handled) { return; } + // 如果用户没有处理异常,则继续向外抛出 throw; } finally { - var project = this.Project; + var project = this._project; if (project is not null) { try @@ -114,11 +224,24 @@ public async Task StartPollAsync(string? dir, XElement? root, Func public async Task StopAsync() { - var project = this.Project; + // 如果测点项目尚未运行,直接返回:重复调用也不应该重复派发"已停止"事件——观察者不该看到一次没人宣布过的停止。 + if (Volatile.Read(ref this._lock) == 0) + { + return; + } + + // 声明"收尾由我负责":StartPollAsync 的 finally 会据此跳过断开通道/派发事件, + // 保证"已停止"发生在通道断开之后(调用方拿它当"可以复用通道/目录"的信号)。 + Interlocked.Exchange(ref this._stopping, 1); + this.SetState(TagsProjectState.Stopping); + this.ClearRunning(); + + var project = this._project; var exitSource = this._pollExitSource; try { @@ -146,20 +296,21 @@ public async Task StopAsync() catch (Exception ex) { // 有意吞掉:取消失败(如 CTS 已释放)不应阻断后续的清理。但不能静默——留痕。 - this._logger.LogWarning(ex, "取消测点项目轮询时出错(项目根目录={ProjectRoot})", project?.ProjectRoot); + // 这里不记项目根目录:能走到这个 catch 的前提是 Cancel() 执行了注册回调并抛异常, + // 那时项目必定已创建(回调只可能由 hook/项目自己注册),写 project?.ProjectRoot 是永远走不到的分支。 + this._logger.LogWarning(ex, "取消测点项目轮询时出错"); } - // 取消是协作式的:先等轮询循环真正退出(它会在退出路径里断开自己的通道)。 - // 不等它就直接释放/断开,会与循环里的读/写/重连并发——"已停止"之后仍有通道活动, - // 而调用方往往正是拿这个事件当"可以复用通道/目录/换配置"的信号。 + // 取消是协作式的:先等轮询循环真正退出。不等它就直接释放/断开,会与循环里的读/写/重连并发—— + // "已停止"之后仍有通道活动,而调用方往往正是拿这个事件当"可以复用通道/目录/换配置"的信号。 if (exitSource is not null && !await this.WaitPollExitAsync(exitSource)) { // 超时兜底:循环没能退出 ⇒ StartPollAsync 的 finally 还没机会释放项目,这里代为释放。 // 正常路径下项目已由 StartPollAsync 的 finally 释放并清空,不需要(也不能)重复释放。 - var timedOutProject = this.Project; + var timedOutProject = this._project; if (timedOutProject is not null) { - this.Project = null; + this._project = null; try { timedOutProject.Dispose(); @@ -172,39 +323,110 @@ public async Task StopAsync() } } - var oldchannels = project?.Channels; - try + await this.DisconnectChannelsAsync(project); + this.RaiseStoppedOnce(); + this.SetState(TagsProjectState.Stopped); + + Interlocked.Exchange(ref _lock, 0); + } + + /// + /// 逐个调用订阅者并分别捕获异常:项目级观测是纯旁路,不能让一个写坏的观察者把启动/停止搞挂, + /// 也不能让排在它后面的订阅者收不到通知。异常只记日志(Error),因此这里永远不会抛。 + /// + private void RaiseStartedOrStopped(TagsProjectEventArgs args) + { + var handlers = this.StartedOrStopped; + if (handlers is null) + { + return; + } + + foreach (TagsProjectStartedOrStopped handler in handlers.GetInvocationList()) { - // disconnect from each channel - if (oldchannels is not null) + try { - foreach (var ch in oldchannels) - { - var channelName = ch?.ChannelName() ?? "null"; - try - { - if (ch is not null) - { - await ch.DisconnectAsync(CancellationToken.None); - } - } - catch (Exception ex) - { - // 有意吞掉:一个通道断开失败不应阻断其它通道的清理。但不能静默——留痕以便确认连接是否真的断开了。 - this._logger.LogWarning(ex, "断开通道失败:通道={Channel}", channelName); - } - } + handler(this, args); + } + catch (Exception ex) + { + this._logger.LogError( + ex, + "StartedOrStopped 的订阅者抛出异常(State={State}, RunId={RunId}),已忽略:订阅者异常不影响项目启停", + args.State, + args.RunId); } + } + } + + /// + /// 派发"已停止":最多一次,且只在派发过"已启动"时才发(否则观察者从未被告知启动过,配不上对)。 + /// + private void RaiseStoppedOnce() + { + if (Interlocked.Exchange(ref this._stopNotified, 1) != 0) + { + return; + } - this.StartedOrStopped?.Invoke(this, new TagsProjectEventArgs(false, null)); + if (Volatile.Read(ref this._startedNotified) == 0) + { + return; } - catch (Exception ex) + + var args = new TagsProjectEventArgs( + TagsProjectState.Stopped, + project: null, + Volatile.Read(ref this._runId), + this._failure); + + this.RaiseStartedOrStopped(args); + } + + /// + /// 断开通道:最多一次。轮询从未开始时通道也没连过,跳过(避免驱动对"未连接的断开"报噪声)。 + /// + private async Task DisconnectChannelsAsync(ITagsProject? project) + { + // 没有项目就没有通道可断(启动阶段在 MakeProject 之前失败时会传 null)。 + if (project is null) { - // 有意吞掉:StartedOrStopped 的事件处理器抛错不应让 StopAsync 失败。但不能静默——留痕。 - this._logger.LogWarning(ex, "向 StartedOrStopped 事件处理器派发\"已停止\"通知时出错"); + return; } - Interlocked.Exchange(ref _lock, 0); + if (Interlocked.Exchange(ref this._channelsDisconnected, 1) != 0) + { + return; + } + + if (Volatile.Read(ref this._startedNotified) == 0) + { + return; + } + + // 接口声明 Channels 非 null,但第三方实现可能违反:此时同样没有通道可断。 + var channels = project.Channels; + if (channels is null) + { + return; + } + + foreach (var ch in channels) + { + var channelName = ch?.ChannelName() ?? "null"; + try + { + if (ch is not null) + { + await ch.DisconnectAsync(CancellationToken.None); + } + } + catch (Exception ex) + { + // 有意吞掉:一个通道断开失败不应阻断其它通道的清理。但不能静默——留痕以便确认连接是否真的断开了。 + this._logger.LogWarning(ex, "断开通道失败:通道={Channel}", channelName); + } + } } /// diff --git a/tests/StdUnit.Tags.Tests.NetCoreOnly/WebUi/StreamTestContext.cs b/tests/StdUnit.Tags.Tests.NetCoreOnly/WebUi/StreamTestContext.cs index 917f88c3..4bb14d5a 100644 --- a/tests/StdUnit.Tags.Tests.NetCoreOnly/WebUi/StreamTestContext.cs +++ b/tests/StdUnit.Tags.Tests.NetCoreOnly/WebUi/StreamTestContext.cs @@ -145,8 +145,28 @@ public IReadOnlyList> BuildSyncFrames(SseFramesPiper piper) /// 可控的假控制器:只用于决定"何时启动/停止"。 internal sealed class FakeProjectCtrl : ITagsProjectCtrl { + private long _runId; + public ITagsProject? Project { get; private set; } + public TagsProjectState State => this.Project is null ? TagsProjectState.Stopped : TagsProjectState.Running; + + public long RunId => Volatile.Read(ref this._runId); + + public bool TryGetRunning(out ITagsProject project, out long runId) + { + if (this.Project is { } running) + { + project = running; + runId = this.RunId; + return true; + } + + project = null!; + runId = 0; + return false; + } + public Func>? OnStartingException { get; set; } public event TagsProjectStartedOrStopped? StartedOrStopped; @@ -154,13 +174,14 @@ internal sealed class FakeProjectCtrl : ITagsProjectCtrl public void RaiseStarted(ITagsProject project) { this.Project = project; - this.StartedOrStopped?.Invoke(this, new TagsProjectEventArgs(true, project)); + var runId = Interlocked.Increment(ref this._runId); + this.StartedOrStopped?.Invoke(this, new TagsProjectEventArgs(TagsProjectState.Running, project, runId, null)); } public void RaiseStopped() { this.Project = null; - this.StartedOrStopped?.Invoke(this, new TagsProjectEventArgs(false, null)); + this.StartedOrStopped?.Invoke(this, new TagsProjectEventArgs(TagsProjectState.Stopped, null, Volatile.Read(ref this._runId), null)); } public Task StartPollAsync(string? dir, System.Xml.Linq.XElement? root, Func hook) => diff --git a/tests/StdUnit.Tags.Tests/Core/TagsProjectCtrls/AttachRunningProjectTests.cs b/tests/StdUnit.Tags.Tests/Core/TagsProjectCtrls/AttachRunningProjectTests.cs new file mode 100644 index 00000000..a67512eb --- /dev/null +++ b/tests/StdUnit.Tags.Tests/Core/TagsProjectCtrls/AttachRunningProjectTests.cs @@ -0,0 +1,263 @@ +using System; +using System.Collections.Generic; +using System.Threading; +using System.Threading.Tasks; +using System.Xml.Linq; +using Xunit; + +namespace StdUnit.Tags.Tests.Core.TagsProjectCtrls; + +/// +/// : +/// 把"订阅 + 晚挂补偿 + 按运行去重 + 停止时摘除"收敛成一个方法。 +/// +public class AttachRunningProjectTests +{ + [Fact] + public void AttachRunningProject_WhenProjectAlreadyRunning_AttachesImmediately() + { + var ctrl = new FakeCtrl(); + var project = new MockTagsProject(); + ctrl.Start(project); + + var attachCalls = 0; + long attachedRunId = 0; + var subscription = new CountingSubscription(); + + using var handle = ctrl.AttachRunningProject((proj, runId) => + { + attachCalls++; + attachedRunId = runId; + Assert.Same(project, proj); + return subscription; + }); + + Assert.Equal(1, attachCalls); + Assert.Equal(ctrl.RunId, attachedRunId); + } + + [Fact] + public void AttachRunningProject_WhenNotRunning_DoesNotAttachUntilStarted() + { + var ctrl = new FakeCtrl(); + var attachCalls = 0; + + using var handle = ctrl.AttachRunningProject((_, _) => + { + attachCalls++; + return new CountingSubscription(); + }); + + Assert.Equal(0, attachCalls); + + ctrl.Start(new MockTagsProject()); + Assert.Equal(1, attachCalls); + } + + [Fact] + public void AttachRunningProject_SameRunNotifiedTwice_AttachesOnce() + { + var ctrl = new FakeCtrl(); + var project = new MockTagsProject(); + ctrl.Start(project); + + var attachCalls = 0; + using var handle = ctrl.AttachRunningProject((_, _) => + { + attachCalls++; + return new CountingSubscription(); + }); + + // 构造里的补查 + 之后重复的"已启动"(同一次运行) + ctrl.RaiseStartedAgain(project); + ctrl.RaiseStartedAgain(project); + + Assert.Equal(1, attachCalls); + } + + [Fact] + public void AttachRunningProject_WhenStopped_DisposesPreviousAttachment() + { + var ctrl = new FakeCtrl(); + ctrl.Start(new MockTagsProject()); + + var subscriptions = new List(); + using var handle = ctrl.AttachRunningProject((_, _) => + { + var s = new CountingSubscription(); + subscriptions.Add(s); + return s; + }); + + ctrl.Stop(); + + Assert.Single(subscriptions); + Assert.Equal(1, subscriptions[0].DisposeCount); + } + + [Fact] + public void AttachRunningProject_WhenRunChanges_DisposesOldAndAttachesNew() + { + var ctrl = new FakeCtrl(); + var first = new MockTagsProject(); + ctrl.Start(first); + + var subscriptions = new List<(long RunId, CountingSubscription Subscription)>(); + using var handle = ctrl.AttachRunningProject((_, runId) => + { + var s = new CountingSubscription(); + subscriptions.Add((runId, s)); + return s; + }); + + ctrl.Stop(); + ctrl.Start(new MockTagsProject()); + + Assert.Equal(2, subscriptions.Count); + Assert.NotEqual(subscriptions[0].RunId, subscriptions[1].RunId); + Assert.Equal(1, subscriptions[0].Subscription.DisposeCount); + Assert.Equal(0, subscriptions[1].Subscription.DisposeCount); + } + + [Fact] + public void AttachRunningProject_Dispose_DetachesAndUnsubscribes() + { + var ctrl = new FakeCtrl(); + ctrl.Start(new MockTagsProject()); + + var subscriptions = new List(); + var handle = ctrl.AttachRunningProject((_, _) => + { + var s = new CountingSubscription(); + subscriptions.Add(s); + return s; + }); + + handle.Dispose(); + handle.Dispose(); // 幂等 + + Assert.Equal(1, subscriptions[0].DisposeCount); + + // 已经解挂:后续启停不再触发 attach + ctrl.Stop(); + ctrl.Start(new MockTagsProject()); + Assert.Single(subscriptions); + } + + [Fact] + public void AttachRunningProject_WhenAttachThrowsAtConstruction_PropagatesAndUnsubscribes() + { + var ctrl = new FakeCtrl(); + ctrl.Start(new MockTagsProject()); + + Assert.Throws(() => + ctrl.AttachRunningProject((_, _) => throw new InvalidOperationException("attach-boom"))); + + // 构造失败必须把事件订阅撤掉:再启停不应再次抛 + ctrl.Stop(); + ctrl.Start(new MockTagsProject()); + } + + [Fact] + public void AttachRunningProject_EventArrivesAfterDispose_IsIgnored() + { + var ctrl = new FakeCtrl(); + var project = new MockTagsProject(); + ctrl.Start(project); + + var attachCalls = 0; + var handle = ctrl.AttachRunningProject((_, _) => + { + attachCalls++; + return new CountingSubscription(); + }); + + // 派发器已取到订阅者快照;此时调用方 Dispose,之后那份快照仍会被调用一次。 + var inFlight = ctrl.CaptureStartedSnapshot(project); + handle.Dispose(); + + inFlight(); + + // 已解挂:迟到的通知不能再挂一次 + Assert.Equal(1, attachCalls); + } + + [Fact] + public void AttachRunningProject_WhenArgsAreNull_Throws() + { + ITagsProjectCtrl? ctrl = null; + Assert.Throws(() => ctrl!.AttachRunningProject((_, _) => new CountingSubscription())); + + var real = new FakeCtrl(); + Assert.Throws(() => real.AttachRunningProject(null!)); + } + + private sealed class CountingSubscription : IDisposable + { + public int DisposeCount { get; private set; } + + public void Dispose() => this.DisposeCount++; + } + + private sealed class FakeCtrl : ITagsProjectCtrl + { + private long _runId; + + public ITagsProject? Project { get; private set; } + + public TagsProjectState State => this.Project is null ? TagsProjectState.Stopped : TagsProjectState.Running; + + public long RunId => Volatile.Read(ref this._runId); + + public Func>? OnStartingException { get; set; } + + public event TagsProjectStartedOrStopped? StartedOrStopped; + + public bool TryGetRunning(out ITagsProject project, out long runId) + { + if (this.Project is { } running) + { + project = running; + runId = this.RunId; + return true; + } + + project = null!; + runId = 0; + return false; + } + + public void Start(ITagsProject project) + { + this.Project = project; + var runId = Interlocked.Increment(ref this._runId); + this.StartedOrStopped?.Invoke(this, new TagsProjectEventArgs(TagsProjectState.Running, project, runId)); + } + + /// 模拟重复派发同一个运行的"已启动"。 + public void RaiseStartedAgain(ITagsProject project) + => this.StartedOrStopped?.Invoke(this, new TagsProjectEventArgs(TagsProjectState.Running, project, this.RunId)); + + public void Stop() + { + this.Project = null; + this.StartedOrStopped?.Invoke(this, new TagsProjectEventArgs(TagsProjectState.Stopped, null, this.RunId)); + } + + /// + /// 抓一份事件订阅者快照,返回"调用这份快照"的委托。
+ /// 用于模拟派发器的真实竞态:它先取到订阅者快照,随后订阅者被 Dispose 退订, + /// 但那份快照仍会被调用一次。 + ///
+ public Action CaptureStartedSnapshot(ITagsProject project) + { + var handlers = this.StartedOrStopped; + return () => handlers?.Invoke(this, new TagsProjectEventArgs(TagsProjectState.Running, project, this.RunId)); + } + + public Task StartPollAsync(string? dir, XElement? root, Func hook) + => throw new NotSupportedException(); + + public Task StopAsync() => Task.CompletedTask; + } +} diff --git a/tests/StdUnit.Tags.Tests/Core/TagsProjectCtrls/MockTagsProject.cs b/tests/StdUnit.Tags.Tests/Core/TagsProjectCtrls/MockTagsProject.cs index 284c0a1a..44321c21 100644 --- a/tests/StdUnit.Tags.Tests/Core/TagsProjectCtrls/MockTagsProject.cs +++ b/tests/StdUnit.Tags.Tests/Core/TagsProjectCtrls/MockTagsProject.cs @@ -14,7 +14,7 @@ internal class MockTagsProject : ITagsProject { private readonly List _channels = new(); - public IReadOnlyList Channels => _channels; + public IReadOnlyList Channels => this.ChannelsReturnsNull ? null! : _channels; public IList Logicets { get; } = new List(); public ITagGrp Tags { get; set; } = null!; public string? ProjectRoot { get; set; } @@ -35,6 +35,23 @@ internal class MockTagsProject : ITagsProject ///
public bool RunAsyncNeverCompletes { get; set; } + /// + /// 如果为 true, 立即正常返回(模拟"轮询自行结束",即没有调用 StopAsync)。 + /// + public bool RunAsyncCompletesImmediately { get; set; } + + /// + /// 如果为 true, 返回 null。
+ /// 用于验证 TagsProjectCtrl 断开通道时对"第三方实现违反接口约定"的防御分支。 + ///
+ public bool ChannelsReturnsNull { get; set; } + + /// + /// 如果为 true, 在被取消时以 结束 + /// (模拟"runner 不把取消当正常返回"的实现)。用于验证正常停机的"已停止"事件里 Failure 仍为 null。 + /// + public bool RunAsyncThrowsOceOnCancel { get; set; } + /// /// 如果为 true, 会在计数之后抛出 InvalidOperationException。
/// 用于验证清理路径「吞掉异常但必须留痕」的语义。 @@ -72,6 +89,20 @@ public Task RunAsync(CancellationToken ct) return new TaskCompletionSource().Task; } + if (RunAsyncCompletesImmediately) + { + // 自行结束:模拟"轮询没有等到 StopAsync 就退出了" + return Task.CompletedTask; + } + + if (RunAsyncThrowsOceOnCancel) + { + // 取消时以 OCE 结束:模拟"runner 把取消当异常抛出"的实现 + var oce = new TaskCompletionSource(); + ct.Register(() => oce.TrySetException(new OperationCanceledException(ct))); + return oce.Task; + } + // 阻塞直到被取消,模拟正在运行的测点项目 var tcs = new TaskCompletionSource(); ct.Register(() => tcs.TrySetResult(true)); diff --git a/tests/StdUnit.Tags.Tests/Core/TagsProjectCtrls/TagsProjectCtrlTests.cs b/tests/StdUnit.Tags.Tests/Core/TagsProjectCtrls/TagsProjectCtrlTests.cs index 43a05c0c..c187c593 100644 --- a/tests/StdUnit.Tags.Tests/Core/TagsProjectCtrls/TagsProjectCtrlTests.cs +++ b/tests/StdUnit.Tags.Tests/Core/TagsProjectCtrls/TagsProjectCtrlTests.cs @@ -75,7 +75,7 @@ public ProjectStartedWatcher(TagsProjectCtrl ctrl) { _subscription = ctrl.ObserveStartedOrStopped().Subscribe(args => { - if (args.IsStarted) + if (args.IsStarted()) { _started.TrySetResult(args); } @@ -145,7 +145,7 @@ public async Task StartPollAsync_FiresStartedEvent() ctrl.StartedOrStopped += (_, args) => { - if (args.IsStarted) + if (args.IsStarted()) { startEventFired.TrySetResult(args); } @@ -158,7 +158,7 @@ public async Task StartPollAsync_FiresStartedEvent() var eventArgs = await startEventFired.Task.WaitAsync(TimeSpan.FromSeconds(5)); - Assert.True(eventArgs.IsStarted); + Assert.True(eventArgs.IsStarted()); Assert.NotNull(eventArgs.Project); Assert.Same(ctrl.Project, eventArgs.Project); @@ -175,7 +175,7 @@ public async Task StopAsync_FiresStoppedEvent() ctrl.StartedOrStopped += (_, args) => { - if (!args.IsStarted) + if (!args.IsStarted()) { stopEventFired.TrySetResult(args); } @@ -193,7 +193,7 @@ public async Task StopAsync_FiresStoppedEvent() var eventArgs = await stopEventFired.Task.WaitAsync(TimeSpan.FromSeconds(5)); - Assert.False(eventArgs.IsStarted); + Assert.False(eventArgs.IsStarted()); Assert.Null(eventArgs.Project); await startTask.WaitAsync(TimeSpan.FromSeconds(5)); @@ -560,7 +560,7 @@ public async Task StopAsync_WhenStartedOrStoppedHandlerThrows_SwallowsAndLogs() ctrl.StartedOrStopped += (_, args) => { - if (!args.IsStarted) + if (!args.IsStarted()) { throw new InvalidOperationException("停止通知处理器-boom"); } @@ -576,7 +576,7 @@ public async Task StopAsync_WhenStartedOrStoppedHandlerThrows_SwallowsAndLogs() await ctrl.StopAsync(); // 不应抛出 await startTask.WaitAsync(TimeSpan.FromSeconds(5)); - Assert.Contains(logs.Entries, e => e.Level == LogLevel.Warning && e.Exception?.Message == "停止通知处理器-boom"); + Assert.Contains(logs.Entries, e => e.Level == LogLevel.Error && e.Exception?.Message == "停止通知处理器-boom"); sp.Dispose(); } @@ -637,6 +637,650 @@ public async Task Start_Stop_Start_Works() sp.Dispose(); } + /// + /// 状态机:hook 执行期间是 (此时 Project 已非 null), + /// hook 完成后是 ,停止后回到 。 + /// 这条测试锁住"Project != null 不等于已就绪"的语义:就绪只能看 State。 + /// + [Fact] + public async Task State_IsStartingInsideHook_ThenRunning_ThenStopped() + { + var (ctrl, sp) = CreateCtrl(); + Assert.Equal(TagsProjectState.Stopped, ctrl.State); + Assert.Null(ctrl.Project); + + TagsProjectState stateInsideHook = default; + var projectInsideHookIsNull = true; + + using var started = WatchProjectStarted(ctrl); + var startTask = Task.Run(() => ctrl.StartPollAsync( + dir: "test_dir", + root: new XElement("Project"), + hook: (proj, _, _) => + { + stateInsideHook = ctrl.State; + projectInsideHookIsNull = ctrl.Project is null; + return Task.CompletedTask; + })); + + await started.WaitAsync(); + + // hook 期间:已经是 Starting、Project 已经赋值(所以不能凭 Project != null 判定就绪) + Assert.Equal(TagsProjectState.Starting, stateInsideHook); + Assert.False(projectInsideHookIsNull); + + // hook 完成之后:Running,且 RunId 非 0 + Assert.Equal(TagsProjectState.Running, ctrl.State); + Assert.NotNull(ctrl.Project); + Assert.True(ctrl.RunId > 0); + + await ctrl.StopAsync(); + await startTask.WaitAsync(TimeSpan.FromSeconds(5)); + + Assert.Equal(TagsProjectState.Stopped, ctrl.State); + Assert.Null(ctrl.Project); + sp.Dispose(); + } + + /// + /// 从未启动时调用 StopAsync:空操作,**不派发**"已停止"(否则观察者会收到一次没人宣布过的停止)。 + /// + [Fact] + public async Task StopAsync_WhenNeverStarted_DoesNotFireStopped() + { + var (ctrl, sp) = CreateCtrl(); + var stoppedCount = 0; + + ctrl.StartedOrStopped += (_, args) => + { + if (!args.IsStarted()) + { + Interlocked.Increment(ref stoppedCount); + } + }; + + await ctrl.StopAsync(); + await ctrl.StopAsync(); + + Assert.Equal(0, stoppedCount); + Assert.Equal(TagsProjectState.Stopped, ctrl.State); + sp.Dispose(); + } + + /// + /// 重复 StopAsync 只派发一次"已停止"。 + /// + [Fact] + public async Task StopAsync_CalledTwice_FiresStoppedOnce() + { + var (ctrl, sp) = CreateCtrl(); + var stoppedCount = 0; + + ctrl.StartedOrStopped += (_, args) => + { + if (!args.IsStarted()) + { + Interlocked.Increment(ref stoppedCount); + } + }; + + using var started = WatchProjectStarted(ctrl); + var startTask = Task.Run(() => ctrl.StartPollAsync( + dir: "test_dir", + root: new XElement("Project"), + hook: (_, _, _) => Task.CompletedTask)); + + await started.WaitAsync(); + await ctrl.StopAsync(); + await ctrl.StopAsync(); + await startTask.WaitAsync(TimeSpan.FromSeconds(5)); + + Assert.Equal(1, stoppedCount); + sp.Dispose(); + } + + /// + /// 启动之后 RunAsync 抛异常(没有 StopAsync):仍然必须补发一次"已停止", + /// 并且用 告诉观察者"这不是正常停机"。 + /// + [Fact] + public async Task StartPollAsync_WhenRunAsyncThrows_EmitsStoppedWithFailure() + { + var (ctrl, sp) = CreateCtrl(); + var startedArgs = new TaskCompletionSource(); + var stoppedArgs = new TaskCompletionSource(); + + ctrl.StartedOrStopped += (_, args) => + { + if (args.IsStarted()) + { + startedArgs.TrySetResult(args); + } + else + { + stoppedArgs.TrySetResult(args); + } + }; + + var startTask = Task.Run(() => ctrl.StartPollAsync( + dir: "test_dir", + root: new XElement("Project"), + hook: (proj, _, _) => + { + ((MockTagsProject)proj).RunAsyncThrows = true; + return Task.CompletedTask; + })); + + var started = await startedArgs.Task.WaitAsync(TimeSpan.FromSeconds(5)); + var ex = await Assert.ThrowsAsync( + () => startTask.WaitAsync(TimeSpan.FromSeconds(5))); + Assert.Contains("模拟的 RunAsync 异常", ex.Message); + + var stopped = await stoppedArgs.Task.WaitAsync(TimeSpan.FromSeconds(5)); + Assert.Equal(TagsProjectState.Stopped, stopped.State); + Assert.Equal(started.RunId, stopped.RunId); + Assert.NotNull(stopped.Failure); + Assert.Contains("模拟的 RunAsync 异常", stopped.Failure!.Message); + Assert.Equal(TagsProjectState.Stopped, ctrl.State); + sp.Dispose(); + } + + /// + /// 启动之后 RunAsync 自行正常结束(没有 StopAsync):同样补发"已停止",只是 Failure 为 null。 + /// + [Fact] + public async Task StartPollAsync_WhenRunAsyncCompletesByItself_EmitsStoppedWithoutFailure() + { + var (ctrl, sp) = CreateCtrl(); + var stoppedArgs = new TaskCompletionSource(); + + ctrl.StartedOrStopped += (_, args) => + { + if (!args.IsStarted()) + { + stoppedArgs.TrySetResult(args); + } + }; + + await ctrl.StartPollAsync( + dir: "test_dir", + root: new XElement("Project"), + hook: (proj, _, _) => + { + ((MockTagsProject)proj).RunAsyncCompletesImmediately = true; + return Task.CompletedTask; + }); + + var stopped = await stoppedArgs.Task.WaitAsync(TimeSpan.FromSeconds(5)); + Assert.Null(stopped.Failure); + Assert.Equal(TagsProjectState.Stopped, stopped.State); + Assert.Equal(TagsProjectState.Stopped, ctrl.State); + Assert.Null(ctrl.Project); + sp.Dispose(); + } + + /// + /// "已启动"的订阅者抛异常:启动必须照常成功,并且排在它后面的订阅者仍然收到通知。 + /// (项目级观测是纯旁路,不能因为一个写坏的观察者就让整个项目起不来。) + /// + [Fact] + public async Task StartPollAsync_WhenStartedHandlerThrows_StartupSucceedsAndLaterHandlersRun() + { + var logs = new CapturingLoggerProvider(); + var (ctrl, sp) = CreateCtrl(logs); + var laterHandlerFired = new TaskCompletionSource(); + + ctrl.StartedOrStopped += (_, args) => + { + if (args.IsStarted()) + { + throw new InvalidOperationException("启动通知处理器-boom"); + } + }; + ctrl.StartedOrStopped += (_, args) => + { + if (args.IsStarted()) + { + laterHandlerFired.TrySetResult(true); + } + }; + + var startTask = Task.Run(() => ctrl.StartPollAsync( + dir: "test_dir", + root: new XElement("Project"), + hook: (_, _, _) => Task.CompletedTask)); + + await laterHandlerFired.Task.WaitAsync(TimeSpan.FromSeconds(5)); + Assert.Equal(TagsProjectState.Running, ctrl.State); + + await ctrl.StopAsync(); + await startTask.WaitAsync(TimeSpan.FromSeconds(5)); // 不应抛出 + + Assert.Contains(logs.Entries, e => e.Level == LogLevel.Error && e.Exception?.Message == "启动通知处理器-boom"); + sp.Dispose(); + } + + /// + /// "已启动"与"已停止"携带同一个 ;重新启动后 RunId 递增。 + /// + [Fact] + public async Task StartedAndStopped_ShareRunId_AndRunIdIncreasesPerStart() + { + var (ctrl, sp) = CreateCtrl(); + var events = new List(); + var started = new SemaphoreSlim(0); + var stopped = new SemaphoreSlim(0); + + ctrl.StartedOrStopped += (_, args) => + { + lock (events) + { + events.Add(args); + } + + if (args.IsStarted()) + { + started.Release(); + } + else + { + stopped.Release(); + } + }; + + for (var round = 0; round < 2; round++) + { + var startTask = Task.Run(() => ctrl.StartPollAsync( + dir: "test_dir", + root: new XElement("Project"), + hook: (_, _, _) => Task.CompletedTask)); + + Assert.True(await started.WaitAsync(TimeSpan.FromSeconds(5))); + await ctrl.StopAsync(); + Assert.True(await stopped.WaitAsync(TimeSpan.FromSeconds(5))); + await startTask.WaitAsync(TimeSpan.FromSeconds(5)); + } + + TagsProjectEventArgs[] snapshot; + lock (events) + { + snapshot = events.ToArray(); + } + + Assert.Equal(4, snapshot.Length); + Assert.Equal(snapshot[0].RunId, snapshot[1].RunId); + Assert.Equal(snapshot[2].RunId, snapshot[3].RunId); + Assert.True(snapshot[2].RunId > snapshot[0].RunId, "每次启动应分配新的 RunId"); + sp.Dispose(); + } + + /// + /// :一次读取就拿到配对的 (Project, RunId), + /// 且只在 期间返回 true(hook 执行期间是 Starting,应为 false)。 + /// + [Fact] + public async Task TryGetRunning_ReturnsAtomicPairOnlyWhileRunning() + { + var (ctrl, sp) = CreateCtrl(); + var startedArgs = new TaskCompletionSource(); + + ctrl.StartedOrStopped += (_, args) => + { + if (args.IsStarted()) + { + startedArgs.TrySetResult(args); + } + }; + + var insideHookResult = true; + long insideHookRunId = -1; + + var startTask = Task.Run(() => ctrl.StartPollAsync( + dir: "test_dir", + root: new XElement("Project"), + hook: (_, _, _) => + { + insideHookResult = ctrl.TryGetRunning(out _, out insideHookRunId); + return Task.CompletedTask; + })); + + var args = await startedArgs.Task.WaitAsync(TimeSpan.FromSeconds(5)); + + // hook 期间是 Starting:即便 Project 已赋值,也不该被当成"正在运行" + Assert.False(insideHookResult); + Assert.Equal(0, insideHookRunId); + + // 已启动之后:快照里的项目和 RunId 与"已启动"事件完全一致 + Assert.True(ctrl.TryGetRunning(out var project, out var runId)); + Assert.Same(ctrl.Project, project); + Assert.Equal(args.RunId, runId); + + await ctrl.StopAsync(); + await startTask.WaitAsync(TimeSpan.FromSeconds(5)); + + Assert.False(ctrl.TryGetRunning(out _, out var stoppedRunId)); + Assert.Equal(0, stoppedRunId); + sp.Dispose(); + } + + /// + /// 正常停机时,即便 RunAsync 以 结束,"已停止"里的 + /// 也必须为 null —— 判据是"令牌确实已取消", + /// 否则每次正常停机都会被误报成"崩了"。 + /// + [Fact] + public async Task StopAsync_WhenRunAsyncEndsWithOce_StoppedHasNoFailure() + { + var (ctrl, sp) = CreateCtrl(); + var stoppedArgs = new TaskCompletionSource(); + + ctrl.StartedOrStopped += (_, args) => + { + if (!args.IsStarted()) + { + stoppedArgs.TrySetResult(args); + } + }; + + using var started = WatchProjectStarted(ctrl); + var startTask = Task.Run(() => ctrl.StartPollAsync( + dir: "test_dir", + root: new XElement("Project"), + hook: (proj, _, _) => + { + ((MockTagsProject)proj).RunAsyncThrowsOceOnCancel = true; + return Task.CompletedTask; + })); + + await started.WaitAsync(); + await ctrl.StopAsync(); + + // OCE 是停机引起的,不算失败:StartPollAsync 正常结束(不抛),停止事件也不带 Failure + await startTask.WaitAsync(TimeSpan.FromSeconds(5)); + + var stopped = await stoppedArgs.Task.WaitAsync(TimeSpan.FromSeconds(5)); + Assert.Null(stopped.Failure); + sp.Dispose(); + } + + /// + /// 并发调用两次 StopAsync:两次都可能越过"未运行则直接返回"的检查, + /// 但"断开通道"和"派发已停止"必须各自只生效一次(靠 Interlocked 守卫)。 + /// + [Fact] + public async Task StopAsync_CalledConcurrently_CleansUpAndNotifiesOnce() + { + var (ctrl, sp) = CreateCtrl(); + var stoppedCount = 0; + var disconnectedCount = 0; + + ctrl.StartedOrStopped += (_, args) => + { + if (!args.IsStarted()) + { + Interlocked.Increment(ref stoppedCount); + } + }; + + var channel = new MockChannel + { + DisconnectAsyncImpl = _ => + { + Interlocked.Increment(ref disconnectedCount); + return Task.CompletedTask; + }, + }; + + using var started = WatchProjectStarted(ctrl); + var startTask = Task.Run(() => ctrl.StartPollAsync( + dir: "test_dir", + root: new XElement("Project"), + hook: (proj, _, _) => + { + ((MockTagsProject)proj).AddChannel(channel); + return Task.CompletedTask; + })); + + await started.WaitAsync(); + + // 两次都同步越过"未运行"检查(第一次还在 await 轮询退出,_lock 仍为 1) + var first = ctrl.StopAsync(); + var second = ctrl.StopAsync(); + await Task.WhenAll(first, second).WaitAsync(TimeSpan.FromSeconds(10)); + await startTask.WaitAsync(TimeSpan.FromSeconds(10)); + + Assert.Equal(1, stoppedCount); + Assert.Equal(1, disconnectedCount); + sp.Dispose(); + } + + /// + /// CancellationTokenSource.Cancel() 会同步执行注册的回调;回调抛异常时会以 + /// 冒出。停机不能被它打断:记 Warning 后继续清理。 + /// + [Fact] + public async Task StopAsync_WhenCancellationCallbackThrows_SwallowsAndLogs() + { + var logs = new CapturingLoggerProvider(); + var (ctrl, sp) = CreateCtrl(logs); + + using var started = WatchProjectStarted(ctrl); + var startTask = Task.Run(() => ctrl.StartPollAsync( + dir: "test_dir", + root: new XElement("Project"), + hook: (_, _, ct) => + { + ct.Register(() => throw new InvalidOperationException("取消回调-boom")); + return Task.CompletedTask; + })); + + await started.WaitAsync(); + + // 不应抛出 + await ctrl.StopAsync().WaitAsync(TimeSpan.FromSeconds(10)); + await startTask.WaitAsync(TimeSpan.FromSeconds(10)); + + Assert.Contains(logs.Entries, e => e.Message.Contains("取消测点项目轮询时出错")); + Assert.Equal(TagsProjectState.Stopped, ctrl.State); + sp.Dispose(); + } + + /// + /// 轮询不响应取消(等超时)且项目释放抛异常:超时兜底里的释放失败必须被吞掉并留痕, + /// 不能把 StopAsync 变成异常。 + /// + [Fact] + public async Task StopAsync_WhenTimedOutProjectDisposeThrows_SwallowsAndLogs() + { + var logs = new CapturingLoggerProvider(); + var (ctrl, sp) = CreateCtrl(logs); + ctrl.PollExitWaitTimeout = TimeSpan.FromMilliseconds(100); + _factory.ProjectRunAsyncNeverCompletes = true; + + using var started = WatchProjectStarted(ctrl); + _ = Task.Run(() => ctrl.StartPollAsync( + dir: "test_dir", + root: new XElement("Project"), + hook: (proj, _, _) => + { + ((MockTagsProject)proj).DisposeThrows = true; + return Task.CompletedTask; + })); + + await started.WaitAsync(); + await ctrl.StopAsync().WaitAsync(TimeSpan.FromSeconds(10)); // 不应抛出 + + Assert.Contains(logs.Entries, e => e.Exception?.Message == "模拟的 Dispose 异常"); + sp.Dispose(); + } + + /// + /// DI 作用域释放抛异常:不能覆盖原始结果,也不能拦着后续启动(锁必须已释放)。记 Warning 留痕。 + /// + [Fact] + public async Task StartPollAsync_WhenScopeDisposeThrows_SwallowsAndLogs() + { + var logs = new CapturingLoggerProvider(); + var services = new ServiceCollection(); + services.AddLogging(b => b.AddProvider(logs)); + services.AddSingleton(_factory); + using var root = services.BuildServiceProvider(); + + var logger = root.GetRequiredService>(); + var inner = new ServiceCollection().AddSingleton(_factory).BuildServiceProvider(); + await using var _ = inner.ConfigureAwait(false); + + var ssf = new ThrowingScopeFactory(inner); + var ctrl = new TagsProjectCtrl(ssf, logger); + + using var started = WatchProjectStarted(ctrl); + var startTask = Task.Run(() => ctrl.StartPollAsync( + dir: "test_dir", + root: new XElement("Project"), + hook: (_, _, _) => Task.CompletedTask)); + + await started.WaitAsync(); + await ctrl.StopAsync(); + await startTask.WaitAsync(TimeSpan.FromSeconds(10)); + + Assert.Contains(logs.Entries, e => e.Level == LogLevel.Warning && e.Message.Contains("释放 DI 作用域失败")); + + // 作用域释放失败不得让控制器卡在"已启动" + Assert.Equal(TagsProjectState.Stopped, ctrl.State); + } + + /// + /// 并发停机的真实时序:第一次 StopAsync 在等轮询退出超时后已把 Project 置空, + /// 但还堵在"断开通道"里(_lock 仍为 1);此时第二次 StopAsync 到达, + /// 它看到的是一个没有项目、取消回调还会抛异常的控制器——两条兜底日志都必须留痕且不抛。 + /// + [Fact] + public async Task StopAsync_ConcurrentWhileDisconnectBlocks_SecondToleratesMissingProject() + { + var logs = new CapturingLoggerProvider(); + var (ctrl, sp) = CreateCtrl(logs); + ctrl.PollExitWaitTimeout = TimeSpan.FromMilliseconds(50); + _factory.ProjectRunAsyncNeverCompletes = true; + + var disconnectStarted = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); + var releaseDisconnect = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); + var slowChannel = new MockChannel + { + DisconnectAsyncImpl = async _ => + { + disconnectStarted.TrySetResult(true); + await releaseDisconnect.Task; + }, + }; + + using var started = WatchProjectStarted(ctrl); + _ = Task.Run(() => ctrl.StartPollAsync( + dir: "test_dir", + root: new XElement("Project"), + hook: (proj, _, ct) => + { + ((MockTagsProject)proj).AddChannel(slowChannel); + ct.Register(() => throw new InvalidOperationException("取消回调-boom")); + return Task.CompletedTask; + })); + + await started.WaitAsync(); + + var first = ctrl.StopAsync(); + // 等第一次进入"断开通道":此时 Project 已被置空、锁尚未释放 + await disconnectStarted.Task.WaitAsync(TimeSpan.FromSeconds(10)); + + var second = ctrl.StopAsync(); // 第二次看到的 Project 为 null + await second.WaitAsync(TimeSpan.FromSeconds(10)); + + releaseDisconnect.TrySetResult(true); + await first.WaitAsync(TimeSpan.FromSeconds(10)); + + // 两条"看似不可能"的兜底分支都走到了:取消时没有项目、超时日志里没有项目 + Assert.Contains(logs.Entries, e => e.Message.Contains("取消测点项目轮询时出错")); + Assert.Contains(logs.Entries, e => e.Message.Contains("等待轮询循环退出超时")); + Assert.Equal(TagsProjectState.Stopped, ctrl.State); + sp.Dispose(); + } + + /// + /// 第三方项目实现违反"Channels 非 null"的约定:断开通道时跳过,不影响其它清理。 + /// + [Fact] + public async Task StopAsync_WhenProjectChannelsIsNull_SkipsDisconnect() + { + var (ctrl, sp) = CreateCtrl(); + + using var started = WatchProjectStarted(ctrl); + var startTask = Task.Run(() => ctrl.StartPollAsync( + dir: "test_dir", + root: new XElement("Project"), + hook: (proj, _, _) => + { + ((MockTagsProject)proj).ChannelsReturnsNull = true; + return Task.CompletedTask; + })); + + await started.WaitAsync(); + await ctrl.StopAsync(); // 不应因为 Channels 为 null 抛 NullReferenceException + await startTask.WaitAsync(TimeSpan.FromSeconds(5)); + + Assert.Equal(TagsProjectState.Stopped, ctrl.State); + Assert.Equal(1, _factory.LastCreatedProject!.DisposeCallCount); + sp.Dispose(); + } + + /// + /// 通道列表里混入 null 元素(第三方实现的脏数据):跳过它,其它通道照常断开。 + /// + [Fact] + public async Task StopAsync_WhenChannelListContainsNull_SkipsNullEntry() + { + var (ctrl, sp) = CreateCtrl(); + var healthyDisconnected = false; + + using var started = WatchProjectStarted(ctrl); + var startTask = Task.Run(() => ctrl.StartPollAsync( + dir: "test_dir", + root: new XElement("Project"), + hook: (proj, _, _) => + { + var mock = (MockTagsProject)proj; + mock.AddChannel(null!); + mock.AddChannel(new MockChannel + { + DisconnectAsyncImpl = _ => + { + healthyDisconnected = true; + return Task.CompletedTask; + }, + }); + return Task.CompletedTask; + })); + + await started.WaitAsync(); + await ctrl.StopAsync(); // 不应抛 NullReferenceException + await startTask.WaitAsync(TimeSpan.FromSeconds(5)); + + Assert.True(healthyDisconnected, "null 元素不应阻断其它通道的断开"); + sp.Dispose(); + } + + /// + /// 用于验证"DI 作用域释放失败"的工厂:作用域照常提供项目工厂,但 Dispose 抛异常。 + /// + private sealed class ThrowingScopeFactory(IServiceProvider provider) : IServiceScopeFactory + { + public IServiceScope CreateScope() => new ThrowingScope(provider); + + private sealed class ThrowingScope(IServiceProvider provider) : IServiceScope + { + public IServiceProvider ServiceProvider { get; } = provider; + + public void Dispose() => throw new InvalidOperationException("作用域释放-boom"); + } + } + /// /// 用于测试通道断开连接的模拟通道。 /// diff --git a/tests/StdUnit.Tags.Tests/Core/TagsProjectCtrls/TagsProjectEventArgsExtensionsTests.cs b/tests/StdUnit.Tags.Tests/Core/TagsProjectCtrls/TagsProjectEventArgsExtensionsTests.cs new file mode 100644 index 00000000..b5f47902 --- /dev/null +++ b/tests/StdUnit.Tags.Tests/Core/TagsProjectCtrls/TagsProjectEventArgsExtensionsTests.cs @@ -0,0 +1,96 @@ +using System; +using Xunit; + +namespace StdUnit.Tags.Tests.Core.TagsProjectCtrls; + +/// +/// :只是 +/// 的派生判断,事件参数本身不再保存这个状态(避免"bool 与 State 各说各话")。 +/// +public class TagsProjectEventArgsExtensionsTests +{ + [Fact] + public void IsStarted_WhenRunning_ReturnsTrue() + { + var args = new TagsProjectEventArgs(TagsProjectState.Running, new MockTagsProject()); + Assert.True(args.IsStarted()); + } + + [Fact] + public void IsStarted_WhenStopped_ReturnsFalse() + { + var args = new TagsProjectEventArgs(TagsProjectState.Stopped, project: null, runId: 42, failure: null); + Assert.False(args.IsStarted()); + } + + [Fact] + public void IsStarted_WhenFailureCarried_StillFalse() + { + var args = new TagsProjectEventArgs( + TagsProjectState.Stopped, + project: null, + runId: 7, + failure: new InvalidOperationException("boom")); + + Assert.False(args.IsStarted()); + Assert.NotNull(args.Failure); + Assert.Equal(7, args.RunId); + } + + [Fact] + public void IsStarted_WhenArgsIsNull_Throws() + { + TagsProjectEventArgs? args = null; + Assert.Throws(() => args!.IsStarted()); + } + + [Fact] + public void IsStarted_WithProject_WhenRunning_ReturnsTrueAndProject() + { + var project = new MockTagsProject(); + var args = new TagsProjectEventArgs(TagsProjectState.Running, project); + + Assert.True(args.IsStarted(out var running)); + + // 返回 true 时 out 参数必定可用:调用点不需要再判空 + Assert.Same(project, running); + } + + [Fact] + public void IsStarted_WithProject_WhenStopped_ReturnsFalseAndNull() + { + var args = new TagsProjectEventArgs(TagsProjectState.Stopped, project: null, runId: 42); + + Assert.False(args.IsStarted(out var project)); + + // 返回 false 时 out 参数刻意置空:不交出"半截状态" + Assert.Null(project); + } + + [Fact] + public void IsStarted_WithProject_WhenRunningButProjectIsNull_ReturnsFalse() + { + // State 与 Project 是两次独立读取,理论上可能读到不一致的瞬间;此时按"未启动"处理 + var args = new TagsProjectEventArgs(TagsProjectState.Running, project: null); + + Assert.False(args.IsStarted(out var project)); + Assert.Null(project); + } + + [Fact] + public void IsStarted_WithProject_WhenArgsIsNull_Throws() + { + TagsProjectEventArgs? args = null; + Assert.Throws(() => args!.IsStarted(out _)); + } + + [Fact] + public void IsStarted_WithoutOut_IsEquivalentToOutVersion() + { + var running = new TagsProjectEventArgs(TagsProjectState.Running, new MockTagsProject()); + var stopped = new TagsProjectEventArgs(TagsProjectState.Stopped, project: null); + + Assert.Equal(running.IsStarted(), running.IsStarted(out _)); + Assert.Equal(stopped.IsStarted(), stopped.IsStarted(out _)); + } +} diff --git a/tests/StdUnit.Tags.Tests/McpServerTests/TagsMcpServerToolsTests.cs b/tests/StdUnit.Tags.Tests/McpServerTests/TagsMcpServerToolsTests.cs index 576c9e22..85b555ce 100644 --- a/tests/StdUnit.Tags.Tests/McpServerTests/TagsMcpServerToolsTests.cs +++ b/tests/StdUnit.Tags.Tests/McpServerTests/TagsMcpServerToolsTests.cs @@ -711,6 +711,25 @@ await Assert.ThrowsAsync(() => private sealed class ProjectCtrl(ITagsProject? project) : ITagsProjectCtrl { public ITagsProject? Project => project; + + public TagsProjectState State => project is null ? TagsProjectState.Stopped : TagsProjectState.Running; + + public long RunId => project is null ? 0 : 1; + + public bool TryGetRunning(out ITagsProject running, out long runId) + { + if (project is not null) + { + running = project; + runId = 1; + return true; + } + + running = null!; + runId = 0; + return false; + } + public Func>? OnStartingException { get; set; } public event TagsProjectStartedOrStopped? StartedOrStopped; diff --git a/tests/StdUnit.Tags.Tests/R3/FakeR3TagsProjectCtrl.cs b/tests/StdUnit.Tags.Tests/R3/FakeR3TagsProjectCtrl.cs index 2d9467f5..0dc95c4c 100644 --- a/tests/StdUnit.Tags.Tests/R3/FakeR3TagsProjectCtrl.cs +++ b/tests/StdUnit.Tags.Tests/R3/FakeR3TagsProjectCtrl.cs @@ -11,6 +11,25 @@ namespace StdUnit.Tags.Tests.R3; internal sealed class FakeR3TagsProjectCtrl : ITagsProjectCtrl { public ITagsProject? Project { get; private set; } + + public TagsProjectState State => this.Project is null ? TagsProjectState.Stopped : TagsProjectState.Running; + + public long RunId { get; private set; } + + public bool TryGetRunning(out ITagsProject project, out long runId) + { + if (this.Project is { } running) + { + project = running; + runId = this.RunId; + return true; + } + + project = null!; + runId = 0; + return false; + } + public Func>? OnStartingException { get; set; } public event TagsProjectStartedOrStopped? StartedOrStopped; @@ -20,17 +39,20 @@ public Task StartPollAsync(string? dir, XElement? root, Func Task.CompletedTask; - public void FireStarted(ITagsProject? project = null) + public void FireStarted(ITagsProject project) { + // 真实控制器派发"已启动"时 Project 必定非 null;这个 Fake 也保持同一不变量, + // 否则会造出"State=Running 却没有项目"的畸形事件参数。 Project = project; - var args = new TagsProjectEventArgs(true, project); + RunId++; + var args = new TagsProjectEventArgs(TagsProjectState.Running, project, RunId, null); StartedOrStopped?.Invoke(this, args); } public void FireStopped() { Project = null; - var args = new TagsProjectEventArgs(false, null); + var args = new TagsProjectEventArgs(TagsProjectState.Stopped, null); StartedOrStopped?.Invoke(this, args); } } diff --git a/tests/StdUnit.Tags.Tests/R3/TagsProjectCtrlR3Extensions_ObserveStartedOrStopped_Tests.cs b/tests/StdUnit.Tags.Tests/R3/TagsProjectCtrlR3Extensions_ObserveStartedOrStopped_Tests.cs index 926a8446..5f9998e8 100644 --- a/tests/StdUnit.Tags.Tests/R3/TagsProjectCtrlR3Extensions_ObserveStartedOrStopped_Tests.cs +++ b/tests/StdUnit.Tags.Tests/R3/TagsProjectCtrlR3Extensions_ObserveStartedOrStopped_Tests.cs @@ -17,13 +17,13 @@ public void ObserveStartedOrStopped_ShouldReceiveStartedAndStoppedEvents() using var subscription = ctrl.ObserveStartedOrStopped().Subscribe(received.Add); // Act - ctrl.FireStarted(); + ctrl.FireStarted(new Mock().Object); ctrl.FireStopped(); // Assert Assert.Equal(2, received.Count); - Assert.True(received[0].IsStarted); - Assert.False(received[1].IsStarted); + Assert.True(received[0].IsStarted()); + Assert.False(received[1].IsStarted()); Assert.Null(received[1].Project); } @@ -41,7 +41,7 @@ public void ObserveStartedOrStopped_ShouldKeepProjectPayload() // Assert Assert.Single(received); - Assert.True(received[0].IsStarted); + Assert.True(received[0].IsStarted()); Assert.Same(project, received[0].Project); } @@ -52,7 +52,7 @@ public void ObserveStartedOrStopped_ShouldStopReceiving_AfterDisposal() var ctrl = new FakeR3TagsProjectCtrl(); var received = new List(); var subscription = ctrl.ObserveStartedOrStopped().Subscribe(received.Add); - ctrl.FireStarted(); + ctrl.FireStarted(new Mock().Object); Assert.Single(received); // Act @@ -61,6 +61,6 @@ public void ObserveStartedOrStopped_ShouldStopReceiving_AfterDisposal() // Assert Assert.Single(received); - Assert.True(received[0].IsStarted); + Assert.True(received[0].IsStarted()); } } diff --git a/tests/StdUnit.Tags.Tests/Rx/FakeRxTagsProjectCtrl.cs b/tests/StdUnit.Tags.Tests/Rx/FakeRxTagsProjectCtrl.cs index d1fe0d51..1a3c300a 100644 --- a/tests/StdUnit.Tags.Tests/Rx/FakeRxTagsProjectCtrl.cs +++ b/tests/StdUnit.Tags.Tests/Rx/FakeRxTagsProjectCtrl.cs @@ -11,6 +11,25 @@ namespace StdUnit.Tags.Tests.Rx; internal sealed class FakeRxTagsProjectCtrl : ITagsProjectCtrl { public ITagsProject? Project { get; private set; } + + public TagsProjectState State => this.Project is null ? TagsProjectState.Stopped : TagsProjectState.Running; + + public long RunId { get; private set; } + + public bool TryGetRunning(out ITagsProject project, out long runId) + { + if (this.Project is { } running) + { + project = running; + runId = this.RunId; + return true; + } + + project = null!; + runId = 0; + return false; + } + public Func>? OnStartingException { get; set; } public event TagsProjectStartedOrStopped? StartedOrStopped; @@ -20,17 +39,20 @@ public Task StartPollAsync(string? dir, XElement? root, Func Task.CompletedTask; - public void FireStarted(ITagsProject? project = null) + public void FireStarted(ITagsProject project) { + // 真实控制器派发"已启动"时 Project 必定非 null;这个 Fake 也保持同一不变量, + // 否则会造出"State=Running 却没有项目"的畸形事件参数。 Project = project; - var args = new TagsProjectEventArgs(true, project); + RunId++; + var args = new TagsProjectEventArgs(TagsProjectState.Running, project, RunId, null); StartedOrStopped?.Invoke(this, args); } public void FireStopped() { Project = null; - var args = new TagsProjectEventArgs(false, null); + var args = new TagsProjectEventArgs(TagsProjectState.Stopped, null); StartedOrStopped?.Invoke(this, args); } } diff --git a/tests/StdUnit.Tags.Tests/Rx/TagsProjectCtrlRxExtensions_ObserveStartedOrStopped_Tests.cs b/tests/StdUnit.Tags.Tests/Rx/TagsProjectCtrlRxExtensions_ObserveStartedOrStopped_Tests.cs index 4a5536f8..0e2e5afe 100644 --- a/tests/StdUnit.Tags.Tests/Rx/TagsProjectCtrlRxExtensions_ObserveStartedOrStopped_Tests.cs +++ b/tests/StdUnit.Tags.Tests/Rx/TagsProjectCtrlRxExtensions_ObserveStartedOrStopped_Tests.cs @@ -17,13 +17,13 @@ public void ObserveStartedOrStopped_ShouldReceiveStartedAndStoppedEvents() using var subscription = ctrl.ObserveStartedOrStopped().Subscribe(new ListObserver(received)); // Act - ctrl.FireStarted(); + ctrl.FireStarted(new Mock().Object); ctrl.FireStopped(); // Assert Assert.Equal(2, received.Count); - Assert.True(received[0].IsStarted); - Assert.False(received[1].IsStarted); + Assert.True(received[0].IsStarted()); + Assert.False(received[1].IsStarted()); Assert.Null(received[1].Project); } @@ -41,7 +41,7 @@ public void ObserveStartedOrStopped_ShouldKeepProjectPayload() // Assert Assert.Single(received); - Assert.True(received[0].IsStarted); + Assert.True(received[0].IsStarted()); Assert.Same(project, received[0].Project); } @@ -52,7 +52,7 @@ public void ObserveStartedOrStopped_ShouldStopReceiving_AfterDisposal() var ctrl = new FakeRxTagsProjectCtrl(); var received = new List(); var subscription = ctrl.ObserveStartedOrStopped().Subscribe(new ListObserver(received)); - ctrl.FireStarted(); + ctrl.FireStarted(new Mock().Object); Assert.Single(received); // Act @@ -61,7 +61,7 @@ public void ObserveStartedOrStopped_ShouldStopReceiving_AfterDisposal() // Assert Assert.Single(received); - Assert.True(received[0].IsStarted); + Assert.True(received[0].IsStarted()); } private sealed class ListObserver(List target) : IObserver