From c5688892bd710cec5820914b14dd2ee5c587e50e Mon Sep 17 00:00:00 2001 From: newbienewbie Date: Wed, 11 Nov 2026 01:17:24 +0800 Subject: [PATCH 01/17] =?UTF-8?q?TagsProjectCtrl=EF=BC=9A=E7=A7=BB?= =?UTF-8?q?=E9=99=A4=E5=88=B0=E5=A4=84=E9=83=BD=E6=98=AF=E7=9A=84volatile?= =?UTF-8?q?=E5=AD=97=E6=AE=B5=EF=BC=8C=E6=94=B9=E7=94=A8record=20+=20Inter?= =?UTF-8?q?Lock?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 13 +- .../TagsProject/TagsProjectCtrl.cs | 271 ++++++++++-------- .../TagsProjectCtrls/TagsProjectCtrlTests.cs | 28 ++ 3 files changed, 190 insertions(+), 122 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a050e3f..a45ce98 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,8 +2,17 @@ 本文件记录**用户可见**的变化。版本号遵循[语义化版本](https://semver.org/lang/zh-CN/) `..`。 - -## 2.0.0-beta8(尚未发布) +## 2.0.0-beta9(尚未发布) + - **修复启动/停止之间的潜在竞态问题**:`CancellationTokenSource` 与"轮询已退出"信号此前是两个字段分别发布, + `StopAsync` 可能读到"门已开、但两个手柄都还没写"的中间态——于是取消落空、也不等退出, + 还会顺手把 `_lock` 清零,让新的启动与旧循环并发跑。 + 现在控制器的**全部可变状态收进一个不可变快照**(`State` / `Project` / `RunId` / 运行手柄 / 各类"只做一次"标记), + 迁移一律走"构造新快照 + CAS 替换":读者一次读取即得一致组合,"只做一次"的副作用由 CAS 认领, + 并因此**不再使用 `volatile` 关键字、也不再需要单独的门字段**(`Handles` 非 null 即"有运行在飞")。 + 同时**只有 `StartPollAsync` 的 finally 能释放门**,`StopAsync` 不再碰它 + (超时兜底后旧循环仍活着时,门保持关闭,新的启动会被 `OnStartingException` 拒绝,而不是并发出第二个运行)。 + +## 2.0.0-beta8 > 本批仍是 `2.0.0` 的预发布——`2.0.0` 正式版保持未发布。 diff --git a/src/StdUnit.Tags/TagsProject/TagsProjectCtrl.cs b/src/StdUnit.Tags/TagsProject/TagsProjectCtrl.cs index f836b76..3c6cdba 100644 --- a/src/StdUnit.Tags/TagsProject/TagsProjectCtrl.cs +++ b/src/StdUnit.Tags/TagsProject/TagsProjectCtrl.cs @@ -24,22 +24,23 @@ public TagsProjectCtrl(IServiceScopeFactory ssf, ILogger logger } /// - public ITagsProject? Project => this._project; + public ITagsProject? Project => this.Read().Project; /// - public TagsProjectState State => (TagsProjectState)Volatile.Read(ref this._state); + public TagsProjectState State => this.Read().State; /// - public long RunId => Volatile.Read(ref this._runId); + public long RunId => this.Read().RunId; /// public bool TryGetRunning(out ITagsProject project, out long runId) { - // 单次 volatile 读:Project 与 RunId 来自同一个不可变快照,绝不会拼出"旧项目 + 新 RunId"。 - if (this._running is { } snapshot) + // 一次读快照:状态、项目、运行号必然来自同一次运行。 + var current = this.Read(); + if (current.State == TagsProjectState.Running && current.Project is { } running) { - project = snapshot.Project; - runId = snapshot.RunId; + project = running; + runId = current.RunId; return true; } @@ -48,71 +49,107 @@ public bool TryGetRunning(out ITagsProject project, out long runId) return false; } - /// - /// "正在运行的项目 + 它的运行标识"的不可变快照。只在 期间非 null, - /// 用于让 能用一次读取取到配对的一对值。 - /// - private sealed class RunSnapshot + #region 状态快照 + // 控制器的全部可变状态集中在一个不可变快照里,只有这一个字段。 + // 任何迁移 = 构造一个新快照 + CAS 替换,因此: + // * 读者一次读取就拿到"状态 + 项目 + 运行标识 + 运行手柄"的一致组合,不会撕裂; + // * "只做一次"的副作用(派发事件、断开通道)靠 CAS 认领,只有一个赢家; + // * 不再需要 volatile 关键字,也不再需要单独的"门"字段(Handles 非 null 即表示有运行在飞)。 + + /// 一次运行的两个手柄:取消源 + "轮询已退出"信号。 + private sealed class RunHandle { - internal RunSnapshot(ITagsProject project, long runId) + internal RunHandle(CancellationTokenSource cts, TaskCompletionSource exitSource) { - this.Project = project; - this.RunId = runId; + this.Cts = cts; + this.ExitSource = exitSource; } - internal ITagsProject Project { get; } + internal CancellationTokenSource Cts { get; } - internal long RunId { get; } + /// 轮询循环已退出的信号:由 的 finally 置位。 + internal TaskCompletionSource ExitSource { get; } } - private volatile RunSnapshot? _running; - - private volatile ITagsProject? _project; - /// - /// 的底层存储(用 读写,保证 可跨线程查询)。 + /// 控制器状态的一次快照(不可变)。所有字段一起发布、一起替换。 /// - private int _state = (int)TagsProjectState.Stopped; + private sealed record Snapshot + { + /// 当前状态。 + internal TagsProjectState State { get; init; } = TagsProjectState.Stopped; - CancellationTokenSource? _cts; + /// 当前(或最近一次)运行的标识;每次启动递增。 + internal long RunId { get; init; } - private int _lock = 0; + /// 当前项目: / 期间非 null。 + internal ITagsProject? Project { get; init; } - #region 单次运行的会话状态 - // 下面这些字段都由 _lock 串行化:同一时刻最多只有一次运行,所以进入 StartPollAsync 后重置即可。 - // 但清理路径可能由 StartPollAsync 的 finally 或 StopAsync 之一执行,故用 Interlocked 保证"只做一次"。 + /// 当前运行的手柄;非 null 即表示"有运行在飞",也就是旧实现里的那道门。 + internal RunHandle? Handles { get; init; } - /// 运行标识,每次启动递增;"已启动"/"已停止"携带同一个值,便于配对。 - private long _runId; + /// 导致本次运行结束的异常;正常停机为 null。 + internal Exception? Failure { get; init; } - /// 本次运行是否已对外派发过"已启动"(只有派发过才需要补"已停止")。 - private int _startedNotified; + /// 本次运行是否已对外派发过"已启动"。 + internal bool StartedRaised { get; init; } - /// 本次运行是否已派发过"已停止"(保证最多一次)。 - private int _stopNotified; + /// 本次运行是否已派发过"已停止"。 + internal bool StoppedRaised { get; init; } - /// 通道是否已断开(保证最多一次)。 - private int _channelsDisconnected; + /// 本次运行的通道是否已断开。 + internal bool ChannelsDisconnected { get; init; } - /// 是否已由 接管收尾(此时 的 finally 不再重复断开通道/派发事件)。 - private int _stopping; + /// 收尾是否已由 接管( 的 finally 据此跳过重复收尾)。 + internal bool StopOwnsCleanup { get; init; } + } - /// 导致本次运行结束的异常;正常停机为 null。会随"已停止"事件一起派发。 - private volatile Exception? _failure; - #endregion + private Snapshot _snapshot = new(); + + private Snapshot Read() => Volatile.Read(ref this._snapshot); /// - /// 离开 时清空快照:此后 立刻返回 false, - /// 不会在停机过程中继续交出项目。 + /// 读取当前状态 curr,计算 mutate(curr) 得到新的状态 next,然后以CAS的手法更新快照。
+ ///
+ /// 函数 返回 null 表示"条件不成立、什么也不做"; 返回非null表述需要把它的结果 CAS 进去。
+ /// 如果 CAS 失败,就基于最新快照重试。
+ ///
+ /// 约定: 必须是纯函数(只看快照、不产生副作用), + /// 因为它可能被反复重试。 ///
- private void ClearRunning() => this._running = null; + private bool TryUpdate(Func mutate) + { + while (true) + { + var current = this.Read(); + var next = mutate(current); + if (next is null) + { + return false; + } + + if (this.TryOptimSwap(current, next)) + { + return true; + } - private void SetState(TagsProjectState state) => Volatile.Write(ref this._state, (int)state); + // 运行至此,说明有人抢先改了快照,重试 + } + } /// - /// "轮询循环已退出"的信号:由 的 finally 置位, 等它。 + /// 乐观锁实现:仅当快照仍是 时,才替换为 。 /// - private TaskCompletionSource? _pollExitSource; + /// 期望当前版本 + /// 要替换的新快照 + /// 如果替换成功返回 true,否则返回 false + private bool TryOptimSwap(Snapshot expected, Snapshot next) + { + var original = Interlocked.CompareExchange(ref this._snapshot, next, expected); + // 对于record,必须用 object.ReferenceEquals(a, b),不能用 == + return ReferenceEquals(original, expected); + } + #endregion /// /// 等待轮询循环退出的上限。
@@ -125,9 +162,26 @@ internal RunSnapshot(ITagsProject project, long runId) /// public async Task StartPollAsync(string? dir, XElement? root, Func hook) { - // 防止重复启动 - if (Interlocked.CompareExchange(ref _lock, 1, 0) != 0) + // 抢门 + var cts = new CancellationTokenSource(); + var exitSource = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); + if (!this.TryUpdate(current => current.Handles is null ? + current with { + State = TagsProjectState.Starting, + RunId = current.RunId + 1, + Handles = new RunHandle(cts, exitSource), + Project = null, + Failure = null, + StartedRaised = false, + StoppedRaised = false, + ChannelsDisconnected = false, + StopOwnsCleanup = false, + } + : null) + ) { + // 失败 + cts.Dispose(); // 取一次快照再用:属性可能在启动过程中被替换 var onStartingException = this.OnStartingException; if (onStartingException != null) @@ -142,41 +196,25 @@ public async Task StartPollAsync(string? dir, XElement? root, Func(TaskCreationOptions.RunContinuationsAsynchronously); - this._pollExitSource = exitSource; - - // 这两个声明在 try 之外: - // - ct 供 catch 的 when 过滤条件使用(try 块内声明的局部变量在 catch 里不在作用域内); - // - scope 交给 finally 释放(项目里的对象可能引用作用域内的服务,所以必须先放项目、再放作用域)。 - CancellationToken ct = default; IServiceScope? scope = null; - try { 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; + this.TryUpdate(current => current with { Project = project }); await hook(project, sp, ct); - // hook 已执行完、轮询即将开始:这是唯一的"已就绪"时刻 - this.SetState(TagsProjectState.Running); - this._running = new RunSnapshot(project, runId); - Volatile.Write(ref this._startedNotified, 1); + // hook 已执行完、轮询即将开始:这是唯一的"已就绪"时刻。 + // 一次迁移同时完成"进入 Running"与"已宣告启动"标记——只有本次运行的所有者会执行到这里,且只执行一次。 + this.TryUpdate(current => current with { State = TagsProjectState.Running, StartedRaised = true }); this.RaiseStartedOrStopped(new TagsProjectEventArgs(TagsProjectState.Running, project, runId, null)); await project.RunAsync(ct); @@ -188,7 +226,7 @@ public async Task StartPollAsync(string? dir, XElement? root, Func current with { Failure = ex }); this._logger.LogError(ex, "TagsProjectCtrl.StartPollAsync error"); // 取一次快照再用:属性可能在启动过程中被替换 @@ -210,7 +248,9 @@ public async Task StartPollAsync(string? dir, XElement? root, Func s with { Project = null }); } } - this._cts = null; - // 正常停机由 StopAsync 接管收尾(它要在断开通道之后才派发"已停止")。 // 其余路径(启动失败、RunAsync 自行结束)没有 StopAsync,必须由这里补上收尾—— // 否则"已启动"永远等不到"已停止",观察者的状态会永远停在 Running,通道也不会断开。 - if (Volatile.Read(ref this._stopping) == 0) + if (!current.StopOwnsCleanup) { - this.SetState(TagsProjectState.Stopping); - this.ClearRunning(); + this.TryUpdate(s => s with { State = TagsProjectState.Stopping }); await this.DisconnectChannelsAsync(project); this.RaiseStoppedOnce(); - this.SetState(TagsProjectState.Stopped); } - Interlocked.Exchange(ref this._lock, 0); - - // 最后才置位:保证等到它的 StopAsync 看到的是"项目已释放、锁已释放"的完整状态 - exitSource.TrySetResult(true); - if (ReferenceEquals(this._pollExitSource, exitSource)) + // 结束这次运行:清手柄(= 释放门)、状态归位。门只在这里释放,StopAsync 绝不碰。 + this.TryUpdate(s => s with { - this._pollExitSource = null; - } + State = TagsProjectState.Stopped, + Handles = null, + Project = null, + }); + + // 最后才置位:保证等到它的 StopAsync 看到的是"项目已释放、门已释放"的完整状态 + handles.ExitSource.TrySetResult(true); // DI 作用域放在最后释放:通道实例可能来自作用域内的服务,必须先让它们断开(上面那步)、 // 再放作用域。这也保持了原来 `using var scope` 的"方法结束才释放"的时序。 @@ -272,26 +310,24 @@ public async Task StartPollAsync(string? dir, XElement? root, Func public async Task StopAsync() { - // 如果测点项目尚未运行,直接返回:重复调用也不应该重复派发"已停止"事件——观察者不该看到一次没人宣布过的停止。 - if (Volatile.Read(ref this._lock) == 0) + // 一次读快照就拿到"有没有运行 + 手柄 + 项目",不会读到半成品。 + var current = this.Read(); + var handles = current.Handles; + if (handles is null) { + // 未运行(或刚结束):空操作,不派生"已停止"——观察者不该看到一次没人宣布过的停止。 return; } // 声明"收尾由我负责":StartPollAsync 的 finally 会据此跳过断开通道/派发事件, // 保证"已停止"发生在通道断开之后(调用方拿它当"可以复用通道/目录"的信号)。 - Interlocked.Exchange(ref this._stopping, 1); - this.SetState(TagsProjectState.Stopping); - this.ClearRunning(); + // 同时进入 Stopping:TryGetRunning 立刻返回 false,不再交出正在拆的项目。 + this.TryUpdate(s => s with { State = TagsProjectState.Stopping, StopOwnsCleanup = true }); - var project = this._project; - var exitSource = this._pollExitSource; + var project = current.Project; try { - if (this._cts != null) - { - this._cts.Cancel(); - } + handles.Cts.Cancel(); } catch (Exception ex) { @@ -303,14 +339,14 @@ public async Task StopAsync() // 取消是协作式的:先等轮询循环真正退出。不等它就直接释放/断开,会与循环里的读/写/重连并发—— // "已停止"之后仍有通道活动,而调用方往往正是拿这个事件当"可以复用通道/目录/换配置"的信号。 - if (exitSource is not null && !await this.WaitPollExitAsync(exitSource)) + if (!await this.WaitPollExitAsync(handles.ExitSource)) { // 超时兜底:循环没能退出 ⇒ StartPollAsync 的 finally 还没机会释放项目,这里代为释放。 // 正常路径下项目已由 StartPollAsync 的 finally 释放并清空,不需要(也不能)重复释放。 - var timedOutProject = this._project; + var timedOutProject = this.Read().Project; if (timedOutProject is not null) { - this._project = null; + this.TryUpdate(s => s with { Project = null }); try { timedOutProject.Dispose(); @@ -325,9 +361,12 @@ public async Task StopAsync() await this.DisconnectChannelsAsync(project); this.RaiseStoppedOnce(); - this.SetState(TagsProjectState.Stopped); + this.TryUpdate(s => s with { State = TagsProjectState.Stopped }); - Interlocked.Exchange(ref _lock, 0); + // 有意不碰 Handles:那是 StartPollAsync 的独占门,只有它的 finally 能释放。 + // 这里若顺手清掉,会开出两个真实的洞: + // ① 启动窗口里进来时(手柄刚发布、hook 还没跑)→ 替一次"还没开始"的运行开了门,新的启动就能挤进来并发跑; + // ② 正常停机时这里若在 StartPollAsync 之后才执行 → 把"刚启动的另一次运行"的门关回去。 } /// @@ -364,21 +403,17 @@ private void RaiseStartedOrStopped(TagsProjectEventArgs args) /// private void RaiseStoppedOnce() { - if (Interlocked.Exchange(ref this._stopNotified, 1) != 0) - { - return; - } - - if (Volatile.Read(ref this._startedNotified) == 0) + if (!this.TryUpdate(s => s.StoppedRaised || !s.StartedRaised ? null : s with { StoppedRaised = true })) { return; } + var current = this.Read(); var args = new TagsProjectEventArgs( TagsProjectState.Stopped, project: null, - Volatile.Read(ref this._runId), - this._failure); + current.RunId, + current.Failure); this.RaiseStartedOrStopped(args); } @@ -394,12 +429,8 @@ private async Task DisconnectChannelsAsync(ITagsProject? project) return; } - if (Interlocked.Exchange(ref this._channelsDisconnected, 1) != 0) - { - return; - } - - if (Volatile.Read(ref this._startedNotified) == 0) + // 认领"由我来断":CAS 失败说明已经断过(或本次从未宣告过启动,通道根本没连过)。 + if (!this.TryUpdate(s => s.ChannelsDisconnected || !s.StartedRaised ? null : s with { ChannelsDisconnected = true })) { return; } diff --git a/tests/StdUnit.Tags.Tests/Core/TagsProjectCtrls/TagsProjectCtrlTests.cs b/tests/StdUnit.Tags.Tests/Core/TagsProjectCtrls/TagsProjectCtrlTests.cs index c187c59..d7c40f2 100644 --- a/tests/StdUnit.Tags.Tests/Core/TagsProjectCtrls/TagsProjectCtrlTests.cs +++ b/tests/StdUnit.Tags.Tests/Core/TagsProjectCtrls/TagsProjectCtrlTests.cs @@ -1266,6 +1266,34 @@ public async Task StopAsync_WhenChannelListContainsNull_SkipsNullEntry() sp.Dispose(); } + /// + /// 轮询不响应取消、StopAsync 超时返回后:那一次运行其实还活着(卡在 RunAsync 里), + /// 所以独占门必须仍然关着——否则第二次启动会与旧循环并发操作同一个控制器。 + /// + [Fact] + public async Task StopAsync_WhenPollingNeverExits_KeepsGateClosedSoRestartIsRejected() + { + var (ctrl, sp) = CreateCtrl(); + 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: (_, _, _) => Task.CompletedTask)); + + await started.WaitAsync(); + await ctrl.StopAsync().WaitAsync(TimeSpan.FromSeconds(10)); + + // 旧循环仍在跑:不能放新的启动进来 + var ex = await Assert.ThrowsAsync(() => + ctrl.StartPollAsync("dir2", new XElement("Project"), (_, _, _) => Task.CompletedTask)); + Assert.Contains("已经启动", ex.Message); + + sp.Dispose(); + } + /// /// 用于验证"DI 作用域释放失败"的工厂:作用域照常提供项目工厂,但 Dispose 抛异常。 /// From f4eaa133d703641ebb39ca41ca35caa19ac34454 Mon Sep 17 00:00:00 2001 From: newbienewbie Date: Wed, 11 Nov 2026 18:56:10 +0800 Subject: [PATCH 02/17] =?UTF-8?q?=E7=A7=BB=E9=99=A4BlazorLib=E5=AE=9E?= =?UTF-8?q?=E9=AA=8C=E9=A1=B9=E7=9B=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 24 +++-- StdUnit.Tags.sln | 6 -- samples/StdUnit.Tags.Web/Program.cs | 2 +- .../StdUnit.Tags.Web/StdUnit.Tags.Web.csproj | 2 +- src/StdUnit.Tags.BlazorLib/Alias.cs | 1 - .../Com/ComChannelDescriptorEditor.cs | 28 ----- .../Com/ComChannelDescriptorEditorView.razor | 100 ------------------ .../Com/ComChannelDescriptorViewer.cs | 23 ---- .../Com/ComChannelDescriptorViewerView.razor | 49 --------- .../ChannelDescriptors/Com/_Extensions.cs | 18 ---- .../Hjzk/HjzkTagChannelDescriptorEditor.cs | 27 ----- .../HjzkTagChannelDescriptorEditorView.razor | 23 ---- .../Hjzk/HjzkTagChannelDescriptorViewer.cs | 22 ---- .../HjzkTagChannelDescriptorViewerView.razor | 19 ---- .../ChannelDescriptors/Hjzk/_Extensions.cs | 18 ---- .../ModbusTcpTagChannelDescriptorEditor.cs | 27 ----- ...busTcpTagChannelDescriptorEditorView.razor | 19 ---- .../ModbusTcpTagChannelDescriptorViewer.cs | 22 ---- ...busTcpTagChannelDescriptorViewerView.razor | 19 ---- .../ModbusTcp/_Extensions.cs | 19 ---- .../OpcUaClientTagChannelDescriptorEditor.cs | 28 ----- ...ClientTagChannelDescriptorEditorView.razor | 34 ------ .../OpcUaClientTagChannelDescriptorViewer.cs | 23 ---- ...ClientTagChannelDescriptorViewerView.razor | 25 ----- .../ChannelDescriptors/OpcUa/_Extensions.cs | 18 ---- .../S7/S7TagChannelDescriptorEditor.cs | 27 ----- .../S7/S7TagChannelDescriptorEditorView.razor | 22 ---- .../S7/S7TagChannelDescriptorViewer.cs | 22 ---- .../S7/S7TagChannelDescriptorViewerView.razor | 22 ---- .../ChannelDescriptors/S7/_Extensions.cs | 18 ---- .../ZLan/ZLanTcpTagChannelDescriptorEditor.cs | 28 ----- ...LanTcpTagChannelDescriptorEditorView.razor | 19 ---- .../ZLan/ZLanTcpTagChannelDescriptorViewer.cs | 23 ---- ...LanTcpTagChannelDescriptorViewerView.razor | 19 ---- .../ChannelDescriptors/ZLan/_Extensions.cs | 18 ---- .../Components/_Imports.razor | 11 -- src/StdUnit.Tags.BlazorLib/LICENSE | 21 ---- .../ServiceCollectionExtensions.cs | 41 ------- .../StdUnit.Tags.BlazorLib.csproj | 23 ---- src/StdUnit.Tags.BlazorLib/paket.references | 2 - .../wwwroot/background.png | Bin 378 -> 0 bytes .../wwwroot/tags.JsInterop.js | 20 ---- 42 files changed, 18 insertions(+), 914 deletions(-) delete mode 100644 src/StdUnit.Tags.BlazorLib/Alias.cs delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorEditor.cs delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorEditorView.razor delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorViewer.cs delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorViewerView.razor delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/_Extensions.cs delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorEditor.cs delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorEditorView.razor delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorViewer.cs delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorViewerView.razor delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/_Extensions.cs delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorEditor.cs delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorEditorView.razor delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorViewer.cs delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorViewerView.razor delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/_Extensions.cs delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorEditor.cs delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorEditorView.razor delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorViewer.cs delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorViewerView.razor delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/_Extensions.cs delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorEditor.cs delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorEditorView.razor delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorViewer.cs delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorViewerView.razor delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/_Extensions.cs delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorEditor.cs delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorEditorView.razor delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorViewer.cs delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorViewerView.razor delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/_Extensions.cs delete mode 100644 src/StdUnit.Tags.BlazorLib/Components/_Imports.razor delete mode 100644 src/StdUnit.Tags.BlazorLib/LICENSE delete mode 100644 src/StdUnit.Tags.BlazorLib/ServiceCollectionExtensions.cs delete mode 100644 src/StdUnit.Tags.BlazorLib/StdUnit.Tags.BlazorLib.csproj delete mode 100644 src/StdUnit.Tags.BlazorLib/paket.references delete mode 100644 src/StdUnit.Tags.BlazorLib/wwwroot/background.png delete mode 100644 src/StdUnit.Tags.BlazorLib/wwwroot/tags.JsInterop.js diff --git a/CHANGELOG.md b/CHANGELOG.md index a45ce98..5b796ff 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,15 +2,23 @@ 本文件记录**用户可见**的变化。版本号遵循[语义化版本](https://semver.org/lang/zh-CN/) `..`。 +> 对于重大发版,使用如下术语: +> - Alpha(内测版):内部测试版本,功能不全,Bug较多。 +> - Beta(公测版):公开测试版本,功能基本齐全,但仍可能存在一些已知问题。 +> - Release Candidate (RC,候选版):功能已冻结,仅修复错误,是正式版最直接的候选 + ## 2.0.0-beta9(尚未发布) - - **修复启动/停止之间的潜在竞态问题**:`CancellationTokenSource` 与"轮询已退出"信号此前是两个字段分别发布, - `StopAsync` 可能读到"门已开、但两个手柄都还没写"的中间态——于是取消落空、也不等退出, - 还会顺手把 `_lock` 清零,让新的启动与旧循环并发跑。 - 现在控制器的**全部可变状态收进一个不可变快照**(`State` / `Project` / `RunId` / 运行手柄 / 各类"只做一次"标记), - 迁移一律走"构造新快照 + CAS 替换":读者一次读取即得一致组合,"只做一次"的副作用由 CAS 认领, - 并因此**不再使用 `volatile` 关键字、也不再需要单独的门字段**(`Handles` 非 null 即"有运行在飞")。 - 同时**只有 `StartPollAsync` 的 finally 能释放门**,`StopAsync` 不再碰它 - (超时兜底后旧循环仍活着时,门保持关闭,新的启动会被 `OnStartingException` 拒绝,而不是并发出第二个运行)。 + +2.0.0-beta9 将是最后一个2.0.0 系列的最后一个beta版,预计将在2026年12月发布,此后进入RC阶段发版。 + +- `ITagsProjectCtrl`:**修复启动/停止之间的潜在竞态问题**:`CancellationTokenSource` 与"轮询已退出"信号此前是两个字段分别发布, + `StopAsync` 可能读到"门已开、但两个手柄都还没写"的中间态——于是取消落空、也不等退出, + 还会顺手把 `_lock` 清零,让新的启动与旧循环并发跑。 + 现在控制器的**全部可变状态收进一个不可变快照**(`State` / `Project` / `RunId` / 运行手柄 / 各类"只做一次"标记), + 迁移一律走"构造新快照 + CAS 替换":读者一次读取即得一致组合,"只做一次"的副作用由 CAS 认领, + 并因此**不再使用 `volatile` 关键字、也不再需要单独的门字段**(`Handles` 非 null 即"有运行在飞")。 + 同时**只有 `StartPollAsync` 的 finally 能释放门**,`StopAsync` 不再碰它 + (超时兜底后旧循环仍活着时,门保持关闭,新的启动会被 `OnStartingException` 拒绝,而不是并发出第二个运行)。 ## 2.0.0-beta8 diff --git a/StdUnit.Tags.sln b/StdUnit.Tags.sln index c1f8fc1..0827511 100644 --- a/StdUnit.Tags.sln +++ b/StdUnit.Tags.sln @@ -11,8 +11,6 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Samples", "Samples", "{02EA EndProject Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "StdUnit.Tags", "src\StdUnit.Tags\StdUnit.Tags.csproj", "{9B38BA08-BC35-CB42-62F6-827CE718B8CB}" EndProject -Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "StdUnit.Tags.BlazorLib", "src\StdUnit.Tags.BlazorLib\StdUnit.Tags.BlazorLib.csproj", "{90B26840-43C9-9104-B6C2-B2F315D241E1}" -EndProject Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "StdUnit.Tags.BlazorLib.Core", "src\StdUnit.Tags.BlazorLib.Core\StdUnit.Tags.BlazorLib.Core.csproj", "{B22AB846-B36E-8482-63DF-F55C07698852}" EndProject Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "StdUnit.Tags.ComScanner", "src\StdUnit.Tags.ComScanner\StdUnit.Tags.ComScanner.csproj", "{4363E7BE-55F3-E487-A37A-F5960CDE8A75}" @@ -78,10 +76,6 @@ Global {9B38BA08-BC35-CB42-62F6-827CE718B8CB}.Debug|Any CPU.Build.0 = Debug|Any CPU {9B38BA08-BC35-CB42-62F6-827CE718B8CB}.Release|Any CPU.ActiveCfg = Release|Any CPU {9B38BA08-BC35-CB42-62F6-827CE718B8CB}.Release|Any CPU.Build.0 = Release|Any CPU - {90B26840-43C9-9104-B6C2-B2F315D241E1}.Debug|Any CPU.ActiveCfg = Debug|Any CPU - {90B26840-43C9-9104-B6C2-B2F315D241E1}.Debug|Any CPU.Build.0 = Debug|Any CPU - {90B26840-43C9-9104-B6C2-B2F315D241E1}.Release|Any CPU.ActiveCfg = Release|Any CPU - {90B26840-43C9-9104-B6C2-B2F315D241E1}.Release|Any CPU.Build.0 = Release|Any CPU {B22AB846-B36E-8482-63DF-F55C07698852}.Debug|Any CPU.ActiveCfg = Debug|Any CPU {B22AB846-B36E-8482-63DF-F55C07698852}.Debug|Any CPU.Build.0 = Debug|Any CPU {B22AB846-B36E-8482-63DF-F55C07698852}.Release|Any CPU.ActiveCfg = Release|Any CPU diff --git a/samples/StdUnit.Tags.Web/Program.cs b/samples/StdUnit.Tags.Web/Program.cs index 4b4a184..0a2d1c0 100644 --- a/samples/StdUnit.Tags.Web/Program.cs +++ b/samples/StdUnit.Tags.Web/Program.cs @@ -18,7 +18,7 @@ builder.Services.AddTags(); builder.Services.AddMudServices(); -builder.Services.AddTagsBlazorLib(); +builder.Services.AddTagsBlazorLibCore(); diff --git a/samples/StdUnit.Tags.Web/StdUnit.Tags.Web.csproj b/samples/StdUnit.Tags.Web/StdUnit.Tags.Web.csproj index 8e5ea56..9b18572 100644 --- a/samples/StdUnit.Tags.Web/StdUnit.Tags.Web.csproj +++ b/samples/StdUnit.Tags.Web/StdUnit.Tags.Web.csproj @@ -21,7 +21,7 @@ - + diff --git a/src/StdUnit.Tags.BlazorLib/Alias.cs b/src/StdUnit.Tags.BlazorLib/Alias.cs deleted file mode 100644 index e8457d4..0000000 --- a/src/StdUnit.Tags.BlazorLib/Alias.cs +++ /dev/null @@ -1 +0,0 @@ -global using TagKinds = System.String; \ No newline at end of file diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorEditor.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorEditor.cs deleted file mode 100644 index 1e332de..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorEditor.cs +++ /dev/null @@ -1,28 +0,0 @@ -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Editing; -using StdUnit.Tags.ComScanner; -using StdUnit.Tags.ComScanner.Channels; -using Microsoft.AspNetCore.Components; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Com; - -sealed class ComChannelDescriptorEditor : ITagChannelDescriptorEditor -{ - public int Priority => 100; - public bool CanEdit(TagChannelDescriptor descriptor) => descriptor.Driver == ComDriverNames.DriverName; - - public RenderFragment Edit(TagChannelDescriptor descriptor, Action descriptorChanged) - { - var d = descriptor.ToComChannelDescriptor(); - if (!ReferenceEquals(d, descriptor)) - { - descriptorChanged(d); - } - - return builder => - { - builder.OpenComponent(0); - builder.AddAttribute(1, nameof(ComChannelDescriptorEditorView.Descriptor), d); - builder.CloseComponent(); - }; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorEditorView.razor b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorEditorView.razor deleted file mode 100644 index be2683b..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorEditorView.razor +++ /dev/null @@ -1,100 +0,0 @@ -@using System.IO.Ports -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using StdUnit.Tags.ComScanner.Channels - - - - - - - - - - - - - - - - - @foreach (var v in Enum.GetValues()) - { - @v - } - - - - - - - - - - @foreach (var v in Enum.GetValues()) - { - @v - } - - - - - - - - - - - - - - - - - - - -@code { - [Parameter, EditorRequired] public ComChannelDescriptor Descriptor { get; set; } = default!; - - private string? _newline; - - protected override void OnParametersSet() - { - _newline = Escape(Descriptor.Option.NewLine); - } - - private Task OnNewLineChanged(string? raw) - { - _newline = raw; - Descriptor.Option.NewLine = Unescape(raw); - return Task.CompletedTask; - } - - private static string? Escape(string? s) - { - if (s is null) return null; - return s.Replace("\r", "\\r").Replace("\n", "\\n").Replace("\t", "\\t"); - } - - private static string? Unescape(string? s) - { - if (string.IsNullOrEmpty(s)) - return null; - try - { - return System.Text.RegularExpressions.Regex.Unescape(s); - } - catch - { - return "\\r\\n"; // ignore invalid escape sequences - } - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorViewer.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorViewer.cs deleted file mode 100644 index b44d5db..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorViewer.cs +++ /dev/null @@ -1,23 +0,0 @@ -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Editing; -using StdUnit.Tags.ComScanner; -using StdUnit.Tags.ComScanner.Channels; -using Microsoft.AspNetCore.Components; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Com; - -sealed class ComChannelDescriptorViewer : ITagChannelDescriptorViewer -{ - public int Priority => 100; - public bool CanView(TagChannelDescriptor descriptor) => descriptor.Driver == ComDriverNames.DriverName; - - public RenderFragment View(TagChannelDescriptor descriptor) - { - var d = descriptor.ToComChannelDescriptor(); - return builder => - { - builder.OpenComponent(0); - builder.AddAttribute(1, nameof(ComChannelDescriptorViewerView.Descriptor), d); - builder.CloseComponent(); - }; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorViewerView.razor b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorViewerView.razor deleted file mode 100644 index 2372509..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorViewerView.razor +++ /dev/null @@ -1,49 +0,0 @@ -@using System.IO.Ports -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using StdUnit.Tags.ComScanner.Channels - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@code { - [Parameter, EditorRequired] public ComChannelDescriptor Descriptor { get; set; } = default!; - - private static string? Escape(string? s) - { - if (s is null) return null; - return s.Replace("\r", "\\r") - .Replace("\n", "\\n") - .Replace("\t", "\\t"); - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/_Extensions.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/_Extensions.cs deleted file mode 100644 index b048339..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/_Extensions.cs +++ /dev/null @@ -1,18 +0,0 @@ -using System; -using System.Collections.Generic; -using System.Linq; -using System.Text; -using System.Threading.Tasks; -using Microsoft.Extensions.DependencyInjection; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Com; - -internal static class ServiceCollectionExtensions -{ - public static TagsBlazorBuilder AddComScannerChannelDescriptorViewerAndEditor(this TagsBlazorBuilder builder) - { - builder.AddTagChannelDescriptorViewer() - .AddTagChannelDescriptorEditor(); - return builder; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorEditor.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorEditor.cs deleted file mode 100644 index 46c4501..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorEditor.cs +++ /dev/null @@ -1,27 +0,0 @@ -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Editing; -using StdUnit.Tags.Hjzk; -using Microsoft.AspNetCore.Components; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Hjzk; - -sealed class HjzkTagChannelDescriptorEditor : ITagChannelDescriptorEditor -{ - public int Priority => 110; - public bool CanEdit(TagChannelDescriptor descriptor) => descriptor.Driver == HjzkNames.DriverName; - - public RenderFragment Edit(TagChannelDescriptor descriptor, Action descriptorChanged) - { - var d = descriptor.ToHjzkTagChannelDescriptor(); - if (!ReferenceEquals(d, descriptor)) - { - descriptorChanged(d); - } - - return builder => - { - builder.OpenComponent(0); - builder.AddAttribute(1, nameof(HjzkTagChannelDescriptorEditorView.Descriptor), d); - builder.CloseComponent(); - }; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorEditorView.razor b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorEditorView.razor deleted file mode 100644 index 85ea80e..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorEditorView.razor +++ /dev/null @@ -1,23 +0,0 @@ -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using StdUnit.Tags.Hjzk - - - HjzkIoBox 基于 ModbusTcp。 - - - - - - - - - - - - - - -@code { - [Parameter, EditorRequired] public HjzkTagChannelDescriptor Descriptor { get; set; } = default!; -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorViewer.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorViewer.cs deleted file mode 100644 index b2f7ae1..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorViewer.cs +++ /dev/null @@ -1,22 +0,0 @@ -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Editing; -using StdUnit.Tags.Hjzk; -using Microsoft.AspNetCore.Components; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Hjzk; - -sealed class HjzkTagChannelDescriptorViewer : ITagChannelDescriptorViewer -{ - public int Priority => 110; - public bool CanView(TagChannelDescriptor descriptor) => descriptor.Driver == HjzkNames.DriverName; - - public RenderFragment View(TagChannelDescriptor descriptor) - { - var d = descriptor.ToHjzkTagChannelDescriptor(); - return builder => - { - builder.OpenComponent(0); - builder.AddAttribute(1, nameof(HjzkTagChannelDescriptorViewerView.Descriptor), d); - builder.CloseComponent(); - }; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorViewerView.razor b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorViewerView.razor deleted file mode 100644 index 3c2d037..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorViewerView.razor +++ /dev/null @@ -1,19 +0,0 @@ -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using StdUnit.Tags.Hjzk - - - - - - - - - - - - - -@code { - [Parameter, EditorRequired] public HjzkTagChannelDescriptor Descriptor { get; set; } = default!; -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/_Extensions.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/_Extensions.cs deleted file mode 100644 index c42c309..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/_Extensions.cs +++ /dev/null @@ -1,18 +0,0 @@ -using System; -using System.Collections.Generic; -using System.Linq; -using System.Text; -using System.Threading.Tasks; -using Microsoft.Extensions.DependencyInjection; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Hjzk; - -internal static class ServiceCollectionExtensions -{ - public static TagsBlazorBuilder AddHjzkChannelDescriptorViewerAndEditor(this TagsBlazorBuilder builder) - { - builder.AddTagChannelDescriptorViewer() - .AddTagChannelDescriptorEditor(); - return builder; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorEditor.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorEditor.cs deleted file mode 100644 index 35d16cd..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorEditor.cs +++ /dev/null @@ -1,27 +0,0 @@ -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Editing; -using StdUnit.Tags.ModbusTcp; -using Microsoft.AspNetCore.Components; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.ModbusTcp; - -sealed class ModbusTcpTagChannelDescriptorEditor : ITagChannelDescriptorEditor -{ - public int Priority => 100; - public bool CanEdit(TagChannelDescriptor descriptor) => descriptor.Driver == ModbusTcpNames.DriverName; - - public RenderFragment Edit(TagChannelDescriptor descriptor, Action descriptorChanged) - { - var d = descriptor.ToModbusTcpTagChannelDescriptor(); - if (!ReferenceEquals(d, descriptor)) - { - descriptorChanged(d); - } - - return builder => - { - builder.OpenComponent(0); - builder.AddAttribute(1, nameof(ModbusTcpTagChannelDescriptorEditorView.Descriptor), d); - builder.CloseComponent(); - }; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorEditorView.razor b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorEditorView.razor deleted file mode 100644 index 2cc835f..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorEditorView.razor +++ /dev/null @@ -1,19 +0,0 @@ -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using StdUnit.Tags.ModbusTcp - - - - - - - - - - - - - -@code { - [Parameter, EditorRequired] public ModbusTcpTagChannelDescriptor Descriptor { get; set; } = default!; -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorViewer.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorViewer.cs deleted file mode 100644 index 48724b0..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorViewer.cs +++ /dev/null @@ -1,22 +0,0 @@ -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Editing; -using StdUnit.Tags.ModbusTcp; -using Microsoft.AspNetCore.Components; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.ModbusTcp; - -sealed class ModbusTcpTagChannelDescriptorViewer : ITagChannelDescriptorViewer -{ - public int Priority => 100; - public bool CanView(TagChannelDescriptor descriptor) => descriptor.Driver == ModbusTcpNames.DriverName; - - public RenderFragment View(TagChannelDescriptor descriptor) - { - var d = descriptor.ToModbusTcpTagChannelDescriptor(); - return builder => - { - builder.OpenComponent(0); - builder.AddAttribute(1, nameof(ModbusTcpTagChannelDescriptorViewerView.Descriptor), d); - builder.CloseComponent(); - }; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorViewerView.razor b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorViewerView.razor deleted file mode 100644 index 4deecb8..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorViewerView.razor +++ /dev/null @@ -1,19 +0,0 @@ -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using StdUnit.Tags.ModbusTcp - - - - - - - - - - - - - -@code { - [Parameter, EditorRequired] public ModbusTcpTagChannelDescriptor Descriptor { get; set; } = default!; -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/_Extensions.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/_Extensions.cs deleted file mode 100644 index 9cab9f3..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/_Extensions.cs +++ /dev/null @@ -1,19 +0,0 @@ -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.ModbusTcp; -using Microsoft.Extensions.DependencyInjection; -using System; -using System.Collections.Generic; -using System.Linq; -using System.Text; -using System.Threading.Tasks; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.ModbusTcp; - -internal static class ServiceCollectionExtensions -{ - public static TagsBlazorBuilder AddModbusTcpChannelDescriptorViewerAndEditor(this TagsBlazorBuilder builder) - { - builder.AddTagChannelDescriptorViewer() - .AddTagChannelDescriptorEditor(); - return builder; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorEditor.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorEditor.cs deleted file mode 100644 index ba264a8..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorEditor.cs +++ /dev/null @@ -1,28 +0,0 @@ -using StdUnit.Tags; -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Editing; -using StdUnit.Tags.OpcUaClient; -using Microsoft.AspNetCore.Components; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.OpcUa; - -public sealed class OpcUaClientTagChannelDescriptorEditor : ITagChannelDescriptorEditor -{ - public int Priority => 100; - public bool CanEdit(TagChannelDescriptor descriptor) => descriptor.Driver == OpcUaClientNames.DriverName; - - public RenderFragment Edit(TagChannelDescriptor descriptor, Action descriptorChanged) - { - var d = descriptor.ToOpcUaClientTagChannelDescriptor(); - if (!ReferenceEquals(d, descriptor)) - { - descriptorChanged(d); - } - - return builder => - { - builder.OpenComponent(0); - builder.AddAttribute(1, nameof(OpcUaClientTagChannelDescriptorEditorView.Descriptor), d); - builder.CloseComponent(); - }; - } -} \ No newline at end of file diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorEditorView.razor b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorEditorView.razor deleted file mode 100644 index 3e594df..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorEditorView.razor +++ /dev/null @@ -1,34 +0,0 @@ -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using StdUnit.Tags.OpcUaClient - - - - - - - - - - - - - - - - - - @if (Descriptor.OpcUaTagChannelOpt.ServerOpt.UsePassword) - { - - - - - - - } - - -@code { - [Parameter, EditorRequired] public OpcUaClientTagChannelDescriptor Descriptor { get; set; } = default!; -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorViewer.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorViewer.cs deleted file mode 100644 index 0fc22f5..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorViewer.cs +++ /dev/null @@ -1,23 +0,0 @@ -using StdUnit.Tags; -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Editing; -using StdUnit.Tags.OpcUaClient; -using Microsoft.AspNetCore.Components; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.OpcUa; - -public sealed class OpcUaClientTagChannelDescriptorViewer : ITagChannelDescriptorViewer -{ - public int Priority => 100; - public bool CanView(TagChannelDescriptor descriptor) => descriptor.Driver == OpcUaClientNames.DriverName; - - public RenderFragment View(TagChannelDescriptor descriptor) - { - var d = descriptor.ToOpcUaClientTagChannelDescriptor(); - return builder => - { - builder.OpenComponent(0); - builder.AddAttribute(1, nameof(OpcUaClientTagChannelDescriptorViewerView.Descriptor), d); - builder.CloseComponent(); - }; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorViewerView.razor b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorViewerView.razor deleted file mode 100644 index 977be5d..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorViewerView.razor +++ /dev/null @@ -1,25 +0,0 @@ -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using StdUnit.Tags.OpcUaClient - - - - - - - - - - - - - - - - - - - -@code { - [Parameter, EditorRequired] public OpcUaClientTagChannelDescriptor Descriptor { get; set; } = default!; -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/_Extensions.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/_Extensions.cs deleted file mode 100644 index e1da3e8..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/_Extensions.cs +++ /dev/null @@ -1,18 +0,0 @@ -using System; -using System.Collections.Generic; -using System.Linq; -using System.Text; -using System.Threading.Tasks; -using Microsoft.Extensions.DependencyInjection; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.OpcUa; - -internal static class ServiceCollectionExtensions -{ - public static TagsBlazorBuilder AddOpcUaChannelDescriptorViewerAndEditor(this TagsBlazorBuilder builder) - { - builder.AddTagChannelDescriptorViewer() - .AddTagChannelDescriptorEditor(); - return builder; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorEditor.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorEditor.cs deleted file mode 100644 index d1fb2ad..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorEditor.cs +++ /dev/null @@ -1,27 +0,0 @@ -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Editing; -using StdUnit.Tags.S7; -using Microsoft.AspNetCore.Components; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.S7; - -sealed class S7TagChannelDescriptorEditor : ITagChannelDescriptorEditor -{ - public int Priority => 100; - public bool CanEdit(TagChannelDescriptor descriptor) => descriptor.Driver == S7Names.DriverName; - - public RenderFragment Edit(TagChannelDescriptor descriptor, Action descriptorChanged) - { - var d = descriptor.ToS7TagChannelDescriptor(); - if (!ReferenceEquals(d, descriptor)) - { - descriptorChanged(d); - } - - return builder => - { - builder.OpenComponent(0); - builder.AddAttribute(1, nameof(S7TagChannelDescriptorEditorView.Descriptor), d); - builder.CloseComponent(); - }; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorEditorView.razor b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorEditorView.razor deleted file mode 100644 index 5e94c78..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorEditorView.razor +++ /dev/null @@ -1,22 +0,0 @@ -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using StdUnit.Tags.S7 - - - - - - - - - - - - - - - - -@code { - [Parameter, EditorRequired] public S7TagChannelDescriptor Descriptor { get; set; } = default!; -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorViewer.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorViewer.cs deleted file mode 100644 index d8d6702..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorViewer.cs +++ /dev/null @@ -1,22 +0,0 @@ -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Editing; -using StdUnit.Tags.S7; -using Microsoft.AspNetCore.Components; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.S7; - -sealed class S7TagChannelDescriptorViewer : ITagChannelDescriptorViewer -{ - public int Priority => 100; - public bool CanView(TagChannelDescriptor descriptor) => descriptor.Driver == S7Names.DriverName; - - public RenderFragment View(TagChannelDescriptor descriptor) - { - var d = descriptor.ToS7TagChannelDescriptor(); - return builder => - { - builder.OpenComponent(0); - builder.AddAttribute(1, nameof(S7TagChannelDescriptorViewerView.Descriptor), d); - builder.CloseComponent(); - }; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorViewerView.razor b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorViewerView.razor deleted file mode 100644 index 2cb76ae..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorViewerView.razor +++ /dev/null @@ -1,22 +0,0 @@ -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using StdUnit.Tags.S7 - - - - - - - - - - - - - - - - -@code { - [Parameter, EditorRequired] public S7TagChannelDescriptor Descriptor { get; set; } = default!; -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/_Extensions.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/_Extensions.cs deleted file mode 100644 index f5652ee..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/_Extensions.cs +++ /dev/null @@ -1,18 +0,0 @@ -using System; -using System.Collections.Generic; -using System.Linq; -using System.Text; -using System.Threading.Tasks; -using Microsoft.Extensions.DependencyInjection; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.S7; - -internal static class ServiceCollectionExtensions -{ - public static TagsBlazorBuilder AddS7ChannelDescriptorViewerAndEditor(this TagsBlazorBuilder builder) - { - builder.AddTagChannelDescriptorViewer() - .AddTagChannelDescriptorEditor(); - return builder; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorEditor.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorEditor.cs deleted file mode 100644 index 12e4bd1..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorEditor.cs +++ /dev/null @@ -1,28 +0,0 @@ -using StdUnit.Tags; -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Editing; -using StdUnit.Tags.ZLan; -using Microsoft.AspNetCore.Components; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.ZLan; - -public sealed class ZLanTcpTagChannelDescriptorEditor : ITagChannelDescriptorEditor -{ - public int Priority => 105; - public bool CanEdit(TagChannelDescriptor descriptor) => descriptor.Driver == ZLanTcpNames.DriverName; - - public RenderFragment Edit(TagChannelDescriptor descriptor, Action descriptorChanged) - { - var d = descriptor.ToZLanTcpTagChannelDescriptor(); - if (!ReferenceEquals(d, descriptor)) - { - descriptorChanged(d); - } - - return builder => - { - builder.OpenComponent(0); - builder.AddAttribute(1, nameof(ZLanTcpTagChannelDescriptorEditorView.Descriptor), d); - builder.CloseComponent(); - }; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorEditorView.razor b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorEditorView.razor deleted file mode 100644 index 0a4ab1f..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorEditorView.razor +++ /dev/null @@ -1,19 +0,0 @@ -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using StdUnit.Tags.ZLan - - - - - - - - - - - - - -@code { - [Parameter, EditorRequired] public ZLanTcpTagChannelDescriptor Descriptor { get; set; } = default!; -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorViewer.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorViewer.cs deleted file mode 100644 index c1b4ea0..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorViewer.cs +++ /dev/null @@ -1,23 +0,0 @@ -using StdUnit.Tags; -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Editing; -using StdUnit.Tags.ZLan; -using Microsoft.AspNetCore.Components; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.ZLan; - -public sealed class ZLanTcpTagChannelDescriptorViewer : ITagChannelDescriptorViewer -{ - public int Priority => 105; - public bool CanView(TagChannelDescriptor descriptor) => descriptor.Driver == ZLanTcpNames.DriverName; - - public RenderFragment View(TagChannelDescriptor descriptor) - { - var d = descriptor.ToZLanTcpTagChannelDescriptor(); - return builder => - { - builder.OpenComponent(0); - builder.AddAttribute(1, nameof(ZLanTcpTagChannelDescriptorViewerView.Descriptor), d); - builder.CloseComponent(); - }; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorViewerView.razor b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorViewerView.razor deleted file mode 100644 index 4da8181..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorViewerView.razor +++ /dev/null @@ -1,19 +0,0 @@ -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using StdUnit.Tags.ZLan - - - - - - - - - - - - - -@code { - [Parameter, EditorRequired] public ZLanTcpTagChannelDescriptor Descriptor { get; set; } = default!; -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/_Extensions.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/_Extensions.cs deleted file mode 100644 index d86ae0c..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/_Extensions.cs +++ /dev/null @@ -1,18 +0,0 @@ -using System; -using System.Collections.Generic; -using System.Linq; -using System.Text; -using System.Threading.Tasks; -using Microsoft.Extensions.DependencyInjection; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.ZLan; - -internal static class ServiceCollectionExtensions -{ - public static TagsBlazorBuilder AddZLanChannelDescriptorViewerAndEditor(this TagsBlazorBuilder builder) - { - builder.AddTagChannelDescriptorViewer() - .AddTagChannelDescriptorEditor(); - return builder; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/_Imports.razor b/src/StdUnit.Tags.BlazorLib/Components/_Imports.razor deleted file mode 100644 index 432c0b2..0000000 --- a/src/StdUnit.Tags.BlazorLib/Components/_Imports.razor +++ /dev/null @@ -1,11 +0,0 @@ -@using System.Net.Http -@using System.Net.Http.Json -@using Microsoft.AspNetCore.Components.Forms -@using Microsoft.AspNetCore.Components.Routing -@using Microsoft.AspNetCore.Components.Web -@using Microsoft.AspNetCore.Components.Web.Virtualization -@using Microsoft.JSInterop -@using MudBlazor -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using static Microsoft.AspNetCore.Components.Web.RenderMode diff --git a/src/StdUnit.Tags.BlazorLib/LICENSE b/src/StdUnit.Tags.BlazorLib/LICENSE deleted file mode 100644 index 81ec167..0000000 --- a/src/StdUnit.Tags.BlazorLib/LICENSE +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2026 StdUnit.Tags - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/src/StdUnit.Tags.BlazorLib/ServiceCollectionExtensions.cs b/src/StdUnit.Tags.BlazorLib/ServiceCollectionExtensions.cs deleted file mode 100644 index a839587..0000000 --- a/src/StdUnit.Tags.BlazorLib/ServiceCollectionExtensions.cs +++ /dev/null @@ -1,41 +0,0 @@ -using Microsoft.Extensions.DependencyInjection; -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.OpcUa; -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.ZLan; -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Hjzk; -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.ModbusTcp; -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.S7; -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Com; - -namespace StdUnit.Tags.BlazorLib; - -/// -/// extensions for DependencyInjection -/// -public static class ServiceCollectionExtensions -{ - /// - /// 增加TagsBlazorLib服务 - /// - /// - /// - /// - public static IServiceCollection AddTagsBlazorLib(this IServiceCollection services, Action? config = null) - { - services.AddTagsBlazorLibCore(builder => - { - // Default channel descriptor viewers/editors - builder.AddS7ChannelDescriptorViewerAndEditor() - .AddModbusTcpChannelDescriptorViewerAndEditor() - .AddHjzkChannelDescriptorViewerAndEditor() - .AddComScannerChannelDescriptorViewerAndEditor() - .AddZLanChannelDescriptorViewerAndEditor() - .AddOpcUaChannelDescriptorViewerAndEditor(); - - config?.Invoke(builder); - }); - return services; - } - - - -} diff --git a/src/StdUnit.Tags.BlazorLib/StdUnit.Tags.BlazorLib.csproj b/src/StdUnit.Tags.BlazorLib/StdUnit.Tags.BlazorLib.csproj deleted file mode 100644 index 66567c2..0000000 --- a/src/StdUnit.Tags.BlazorLib/StdUnit.Tags.BlazorLib.csproj +++ /dev/null @@ -1,23 +0,0 @@ - - - - Blazor 组件库:各驱动的通道描述符查看器与编辑器 - net8.0 - Library - - false - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/src/StdUnit.Tags.BlazorLib/paket.references b/src/StdUnit.Tags.BlazorLib/paket.references deleted file mode 100644 index ae3d4c2..0000000 --- a/src/StdUnit.Tags.BlazorLib/paket.references +++ /dev/null @@ -1,2 +0,0 @@ -MudBlazor -Microsoft.AspNetCore.Components.Web \ No newline at end of file diff --git a/src/StdUnit.Tags.BlazorLib/wwwroot/background.png b/src/StdUnit.Tags.BlazorLib/wwwroot/background.png deleted file mode 100644 index e15a3bde6e2bdb380df6a0b46d7ed00bdeb0aaa8..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 378 zcmeAS@N?(olHy`uVBq!ia0vp^x**KK1SGdsl%54rjKx9jP7LeL$-D$|SkfJR9T^xl z_H+M9WCij$3p^r=85sBugD~Uq{1qucLCF%=h?3y^w370~qEv>0#LT=By}Z;C1rt33 zJwr2>%=KS^ie7oTIEF;HpS|GCbyPusHSqiXaCu3qf)82(9Gq&mZq2{Kq}M*X&MWtJ zSi1Jo7ZzfImg%g=t(qo=wsSR2lZoP(Rj#3wacN=q0?Br(rXzgZEGK2$ID{|A=5S{xJEuzSH>!M+7wSY6hB<=-E^*n0W7 S8wY^CX7F_Nb6Mw<&;$S{dxtsz diff --git a/src/StdUnit.Tags.BlazorLib/wwwroot/tags.JsInterop.js b/src/StdUnit.Tags.BlazorLib/wwwroot/tags.JsInterop.js deleted file mode 100644 index 7311c64..0000000 --- a/src/StdUnit.Tags.BlazorLib/wwwroot/tags.JsInterop.js +++ /dev/null @@ -1,20 +0,0 @@ -// This is a JavaScript module that is loaded on demand. It can export any number of -// functions, and may import other JavaScript modules if required. - -export function showPrompt(message) { - return prompt(message, 'Type anything here'); -} - -export function downloadTextFile(fileName, text) { - const blob = new Blob([text], { type: 'text/xml;charset=utf-8;' }); - const link = document.createElement('a'); - const url = URL.createObjectURL(blob); - link.href = url; - link.download = fileName; - document.body.appendChild(link); - link.click(); - setTimeout(function () { - document.body.removeChild(link); - window.URL.revokeObjectURL(url); - }, 0); -} \ No newline at end of file From 0e41f3cbbaa577023a74810673a20bfe8e2284f8 Mon Sep 17 00:00:00 2001 From: newbienewbie Date: Wed, 11 Nov 2026 18:56:10 +0800 Subject: [PATCH 03/17] =?UTF-8?q?=E9=A9=B1=E5=8A=A8=E9=87=8A=E6=94=BE?= =?UTF-8?q?=E8=B7=AF=E5=BE=84=E6=94=B6=E6=95=9B=EF=BC=8C=E6=96=AD=E5=BC=80?= =?UTF-8?q?=E5=A4=B1=E8=B4=A5=E4=B8=8D=E5=86=8D=E8=A2=AB=E9=9D=99=E9=BB=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - ModbusTcp/OpcUa:Dispose 与 DisconnectAsync 收敛到同一条释放路径,并去掉 Connected 守卫(它只是上次 I/O 的快照,半死连接会被漏掉) - ModbusTcp:去掉 DisconnectAsync 里用 Thread 包装同步 Close 的残留 - DefaultTagGrpRunnerDisconnectStrategy:已完成的断开任务补一次 await, 故障才能冒到清理路径(此前故障 Task 无人观察,DisconnectAllAsync 的 catch 永远不会触发) - ITagChannel:把"DisconnectAsync 抛、Dispose 只留痕"写进公开契约 - src/:开启 TreatWarningsAsErrors(整解 0 警告) - 测试:断开策略 4 个用例 + Dispose 幂等用例 --- src/StdUnit.Tags.Core/Channels/ITagChannel.cs | 4 +- .../Channels/ModbusTcpChannel.cs | 79 +++++++++---------- .../Channels/OpcUaClientTagChannel.cs | 70 +++++++++++----- .../DefaultTagGrpRunnerDisconnectStrategy.cs | 7 ++ ...aultTagGrpRunnerDisconnectStrategyTests.cs | 59 ++++++++++++++ .../ModbusTcpChannelConnectionTests.cs | 19 +++++ 6 files changed, 178 insertions(+), 60 deletions(-) create mode 100644 tests/StdUnit.Tags.Tests/Core/TagGrpRunners/DefaultTagGrpRunnerDisconnectStrategyTests.cs diff --git a/src/StdUnit.Tags.Core/Channels/ITagChannel.cs b/src/StdUnit.Tags.Core/Channels/ITagChannel.cs index 58ef0b1..ff37c48 100644 --- a/src/StdUnit.Tags.Core/Channels/ITagChannel.cs +++ b/src/StdUnit.Tags.Core/Channels/ITagChannel.cs @@ -17,7 +17,9 @@ public interface ITagChannel : IDisposable Task EnsureConnectedAsync(bool force, CancellationToken ct); /// - /// 关闭 + /// 关闭连接。
+ /// 约定:失败时抛出——调用方是运行器的清理路径,会按通道名记 Warning,也不会阻断其它通道的清理; + /// 而 不抛。即"显式方法报告失败,释放方法只做尽力清理并留痕"。 ///
/// Task DisconnectAsync(CancellationToken ct); diff --git a/src/StdUnit.Tags.ModbusTcp/Channels/ModbusTcpChannel.cs b/src/StdUnit.Tags.ModbusTcp/Channels/ModbusTcpChannel.cs index 8e37a02..e06b20e 100644 --- a/src/StdUnit.Tags.ModbusTcp/Channels/ModbusTcpChannel.cs +++ b/src/StdUnit.Tags.ModbusTcp/Channels/ModbusTcpChannel.cs @@ -179,34 +179,16 @@ public async Task EnsureConnectedAsync(bool force, CancellationToken ct) } /// - /// 断开连接 + /// 断开连接。
+ /// 不阻塞,所以这里不再用 把同步调用伪装成异步; + /// 只为接口一致,不参与等待(清理路径本来就该用 )。
+ /// 关闭失败时以故障 Task 返回(与 S7 / OpcUa / ComScanner 一致,见 ), + /// 而 只记日志、不抛。 ///
- /// - /// public Task DisconnectAsync(CancellationToken ct) { - if (_tcpClient == null) - return Task.CompletedTask; - - var tcs = new TaskCompletionSource(); - var th = new Thread(() => - { - try - { - _tcpClient.Close(); - _tcpClient = null; - tcs.SetResult(null); - } - catch (Exception ex) - { - _logger.LogWarning(ex, "通道{ChannelName}断开连接失败", this.ChannelName()); - _tcpClient = null; - tcs.SetException(ex); - } - }); - th.IsBackground = true; - th.Start(); - return tcs.Task; + var error = this.TryCloseConnection(); + return error is null ? Task.CompletedTask : Task.FromException(error); } #endregion @@ -365,23 +347,40 @@ private static ushort[] GetArray(ReadOnlyMemory memory) /// public void Dispose() { - var channelName = this.ChannelName(); - if (_tcpClient != null && _tcpClient.Connected) + var error = this.TryCloseConnection(); + if (error is not null) { - try - { - _logger.LogInformation("通道={ChannelName} 正在断开连接...", channelName); - _tcpClient.Close(); - _logger.LogInformation("通道={ChannelName} 断开连接完成!", channelName); - } - catch (Exception e) - { - _logger.LogWarning(e, "通道={ChannelName} 释放异常", channelName); - } - finally - { + // Dispose 只留痕、不外抛(.NET 的释放惯例)。 + _logger.LogWarning(error, "通道={ChannelName} 释放异常", this.ChannelName()); + } + } - } + /// + /// 关闭并清空底层连接——唯一的释放路径, 与 都走它。
+ /// 有意不用 当守卫:它只是上次 I/O 的快照,半死连接上返回 false, + /// 恰好会把最该关的 socket 留下来。
+ /// 失败时把异常返回而不是吞掉或抛出:由调用方决定是记日志(Dispose)还是外抛(DisconnectAsync)。 + ///
+ private Exception? TryCloseConnection() + { + var client = Interlocked.Exchange(ref _tcpClient, null); + this.ModbusMaster = null; + if (client is null) + { + return null; + } + + var channelName = this.ChannelName(); + try + { + _logger.LogInformation("通道={ChannelName} 正在断开连接...", channelName); + client.Close(); + _logger.LogInformation("通道={ChannelName} 断开连接完成!", channelName); + return null; + } + catch (Exception e) + { + return e; } } } \ No newline at end of file diff --git a/src/StdUnit.Tags.OpcUaClient/Channels/OpcUaClientTagChannel.cs b/src/StdUnit.Tags.OpcUaClient/Channels/OpcUaClientTagChannel.cs index 1deafdc..231d2cd 100644 --- a/src/StdUnit.Tags.OpcUaClient/Channels/OpcUaClientTagChannel.cs +++ b/src/StdUnit.Tags.OpcUaClient/Channels/OpcUaClientTagChannel.cs @@ -208,22 +208,23 @@ public async Task EnsureConnectedAsync(bool force, CancellationToken ct) /// /// 断开连接 /// - /// - /// public async Task DisconnectAsync(CancellationToken ct) { + var session = this.OpcSession; + this.OpcSession = null; + if (session is null) + { + return; + } + try { - if (this.OpcSession != null) - { - await OpcSession.CloseAsync(ct); - } + await session.CloseAsync(ct); } finally { - this.OpcSession = null; + this.ReleaseSession(session); } - } #endregion @@ -376,23 +377,54 @@ public virtual async Task WriteValueAsync(NodeId nodeId, DataValue value, Cancel /// public void Dispose() { - if (OpcSession != null && OpcSession.Connected) + var session = this.OpcSession; + this.OpcSession = null; + if (session is null) + { + return; + } + + var channelName = this.ChannelName(); + try { - var channelName = this.ChannelName(); - try + // 已断开的会话不必再 Close(Stack 侧会因此抛错),但**必须** Dispose—— + // 这与 ModbusTcpChannel 的"无条件 Close"不同:那边 Connected==false 意味着句柄还活着。 + if (session.Connected) { _logger.LogInformation("通道={ChannelName} 正在断开连接...", channelName); - OpcSession.Close(); + session.Close(); _logger.LogInformation("通道={ChannelName} 断开连接完成!", channelName); } - catch (Exception e) - { - _logger.LogWarning(e, "通道={ChannelName} 释放异常", channelName); - } - finally - { + } + catch (Exception e) + { + _logger.LogWarning(e, "通道={ChannelName} 释放异常", channelName); + } + finally + { + this.ReleaseSession(session); + } + } - } + /// + /// 释放 身上由 负责的那部分资源(订阅、传输句柄等)。 + /// Close/CloseAsync 只负责"关闭会话",不释放它们;漏掉这一下,反复启停会攒下没人认领的对象。
+ /// 这里只记日志、不抛:它是 finally 里的收尾,抛出来会盖掉真正的原因(关闭失败)。 + ///
+ private void ReleaseSession(ISession session) + { + if (session is not IDisposable disposable) + { + return; + } + + try + { + disposable.Dispose(); + } + catch (Exception e) + { + _logger.LogWarning(e, "通道={ChannelName} 释放会话异常", this.ChannelName()); } } } diff --git a/src/StdUnit.Tags/TagGrpRunners/DefaultTagGrpRunnerDisconnectStrategy.cs b/src/StdUnit.Tags/TagGrpRunners/DefaultTagGrpRunnerDisconnectStrategy.cs index 6a65ee8..43c1095 100644 --- a/src/StdUnit.Tags/TagGrpRunners/DefaultTagGrpRunnerDisconnectStrategy.cs +++ b/src/StdUnit.Tags/TagGrpRunners/DefaultTagGrpRunnerDisconnectStrategy.cs @@ -23,5 +23,12 @@ public async Task WaitDisconnectAsync(ITagChannel? channel, Task? disconnect) // 超时定时器不用 CancellationToken——断开本身是 CancellationToken.None 发起的, // 超时定时器若被取消会立即抛 OCE,退化成"不等待"。 await Task.WhenAny(disconnect, Task.Delay(Timeout)); + + // 超时未完成就放弃等待(后台仍会继续清理);但"已经失败"必须让调用方看见—— + // 否则故障任务永远没人 await(UnobservedTaskException),谁也不知道连接没断干净。 + if (disconnect.IsCompleted) + { + await disconnect; + } } } diff --git a/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/DefaultTagGrpRunnerDisconnectStrategyTests.cs b/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/DefaultTagGrpRunnerDisconnectStrategyTests.cs new file mode 100644 index 0000000..735e965 --- /dev/null +++ b/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/DefaultTagGrpRunnerDisconnectStrategyTests.cs @@ -0,0 +1,59 @@ +using System; +using System.Threading.Tasks; +using Xunit; + +namespace StdUnit.Tags.Tests.Core.TagGrpRunners; + +/// +/// :有限超时等待,且"已经失败的断开"必须让调用方看见。 +/// +public class DefaultTagGrpRunnerDisconnectStrategyTests +{ + private static DefaultTagGrpRunnerDisconnectStrategy NewStrategy(TimeSpan? timeout = null) => new() + { + Timeout = timeout ?? TimeSpan.FromSeconds(5) + }; + + /// 无需断开时立即返回 + [Fact] + public async Task WaitDisconnectAsync_WhenDisconnectIsNull_Completes() + { + var strategy = NewStrategy(); + + await strategy.WaitDisconnectAsync(null, null); + } + + /// 断开正常完成时透传完成状态 + [Fact] + public async Task WaitDisconnectAsync_WhenDisconnectSucceeds_Completes() + { + var strategy = NewStrategy(); + + await strategy.WaitDisconnectAsync(null, Task.CompletedTask); + } + + /// + /// 断开失败必须外抛:否则故障 Task 永远没人 await(UnobservedTaskException), + /// 运行器也不会记下"连接没断干净"。 + /// + [Fact] + public async Task WaitDisconnectAsync_WhenDisconnectFaulted_Propagates() + { + var strategy = NewStrategy(); + var faulted = Task.FromException(new InvalidOperationException("boom")); + + await Assert.ThrowsAsync(() => strategy.WaitDisconnectAsync(null, faulted)); + } + + /// 断开迟迟不完成时按超时返回,不无限阻塞清理路径 + [Fact] + public async Task WaitDisconnectAsync_WhenDisconnectHangs_ReturnsAfterTimeout() + { + var strategy = NewStrategy(TimeSpan.FromMilliseconds(20)); + var neverCompletes = new TaskCompletionSource().Task; + + await strategy.WaitDisconnectAsync(null, neverCompletes); + + Assert.False(neverCompletes.IsCompleted); + } +} diff --git a/tests/StdUnit.Tags.Tests/ModbusTags/Channels/ModbusTcpChannelConnectionTests.cs b/tests/StdUnit.Tags.Tests/ModbusTags/Channels/ModbusTcpChannelConnectionTests.cs index 7351371..efd38f0 100644 --- a/tests/StdUnit.Tags.Tests/ModbusTags/Channels/ModbusTcpChannelConnectionTests.cs +++ b/tests/StdUnit.Tags.Tests/ModbusTags/Channels/ModbusTcpChannelConnectionTests.cs @@ -82,4 +82,23 @@ public async Task Dispose_ThenEnsureConnected_Reconnects() Assert.Equal(new ushort[] { 0x9ABC }, regs); channel.Dispose(); } + + /// + /// Dispose() 与 DisconnectAsync() 是同一条释放路径:不拿 Connected 当守卫、 + /// 释放后把 master 一并清空,且重复释放幂等。 + /// + [Fact] + public async Task Dispose_ReleasesConnectionAndIsIdempotent() + { + using var server = new FakeModbusTcpServer(); + using var channel = NewChannel(server); + await channel.EnsureConnectedAsync(false, CancellationToken.None); + Assert.NotNull(channel.ModbusMaster); + + channel.Dispose(); + + Assert.Null(channel.ModbusMaster); + channel.Dispose(); + channel.Dispose(); + } } From e532428c526390d8b8ebd4d7af93797021a3f7e5 Mon Sep 17 00:00:00 2001 From: newbienewbie Date: Wed, 11 Nov 2026 20:28:42 +0800 Subject: [PATCH 04/17] =?UTF-8?q?=E5=B7=A5=E7=A8=8B=E9=97=A8=E7=A6=81?= =?UTF-8?q?=EF=BC=9ACI=20=E8=A1=A5=E8=B7=91=20net8.0-only=20=E6=B5=8B?= =?UTF-8?q?=E8=AF=95=EF=BC=8Csrc=20=E5=BC=80=E5=90=AF=20TreatWarningsAsErr?= =?UTF-8?q?ors?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - dotnet.yml:`build` job 增加 `Tests.NetCoreOnly` - src/Directory.Build.props:开启 TreatWarningsAsErrors ,tests/ 与 samples/ 有意不加——AOT 冒烟的 publish 会带出第三方 IL2104/IL3053 噪声。 --- .github/workflows/dotnet.yml | 10 +++++++++- src/Directory.Build.props | 7 +++++++ 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/.github/workflows/dotnet.yml b/.github/workflows/dotnet.yml index b307bc6..a2fc699 100644 --- a/.github/workflows/dotnet.yml +++ b/.github/workflows/dotnet.yml @@ -47,6 +47,14 @@ jobs: - name: Test with Coverage (net8.0) run: dotnet test tests/StdUnit.Tags.Tests/StdUnit.Tags.Tests.csproj -f net8.0 -c Release --no-build --nologo --collect:"XPlat Code Coverage" --results-directory ./TestResults + # net8.0 专属的测试(BlazorLib.Core / WebUi / ASP.NET Core)不在上面那个项目里。 + # 它们此前只在 release 工作流里跑 —— 于是 2.0 的主打新增(WebUi)在 PR 阶段只能保证"编译通过", + # 回归要等发版当天才发现。AOT job 已在 Linux 上跑 AspNetCore,因此这里放 ubuntu 没有平台障碍。 + # 与主测试**分两步顺序跑**(理由同 release 工作流):`dotnet test` 直接打解决方案会并行拉起多个 testhost, + # 4 vCPU 的 CI runner 上会把"机器忙"变成随机红。 + - name: Test with Coverage (net8.0-only: BlazorLib.Core / WebUi) + run: dotnet test tests/StdUnit.Tags.Tests.NetCoreOnly/StdUnit.Tags.Tests.NetCoreOnly.csproj -f net8.0 -c Release --no-build --nologo --collect:"XPlat Code Coverage" --results-directory ./TestResults + - name: Upload Coverage to Codecov uses: codecov/codecov-action@v4 env: @@ -58,7 +66,7 @@ jobs: fail_ci_if_error: true verbose: true - # 迭代产物通道:这**不是**发布,只是把每次构建的 13 个包传上来,好让现场用户/公测者提前试。 + # 迭代产物通道:这**不是**发布,只是把每次构建的包全部传上来(清单见 src/publish-packages.ps1),好让现场用户/公测者提前试。 # 版本号故意写成"构建号"(<基础版本>-dev..),它不是语义化版本: # * 落在"下一个计划发布的正式号"的预发布位上 ⇒ 排序上低于该正式号(正式版一发就自然覆盖), # 又高于此前任何正式版(装了它还能正常往前走,不会出现版本降级); diff --git a/src/Directory.Build.props b/src/Directory.Build.props index 95af005..9cd2e26 100644 --- a/src/Directory.Build.props +++ b/src/Directory.Build.props @@ -15,6 +15,13 @@ enable enable true + + true From 418f52bc2362a7d7490f173ec617de911cfd1ebf Mon Sep 17 00:00:00 2001 From: newbienewbie Date: Wed, 11 Nov 2026 21:05:32 +0800 Subject: [PATCH 05/17] =?UTF-8?q?S7:=20=E7=AE=80=E5=8C=96=E9=80=9A?= =?UTF-8?q?=E9=81=93=E7=9A=84=E8=BF=9E=E6=8E=A5=E5=92=8C=E6=96=AD=E5=BC=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 8 + src/StdUnit.Tags.S7/Channels/S7TagChannel.cs | 197 ++++++++---------- .../S7Tags/S7TagChannelTests.cs | 7 +- 3 files changed, 98 insertions(+), 114 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5b796ff..620e5fa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,14 @@ 同时**只有 `StartPollAsync` 的 finally 能释放门**,`StopAsync` 不再碰它 (超时兜底后旧循环仍活着时,门保持关闭,新的启动会被 `OnStartingException` 拒绝,而不是并发出第二个运行)。 +StdUnit.Tags.S7: **通道内部简化**(公开行为不变) + - `S7TagChannel.CreateClientAndConnectAsync(ct)` → **`CreateClientAndConnect(channelName)`**:`protected virtual`, + 返回 `S7Client`、失败即抛 `InvalidOperationException`,不再泄露 F# 类型到通道代码里。 + - `Dispose()` 与 `DisconnectAsync()` 收敛为**同一条释放路径**,且不再用 `S7Client.Connected` 当守卫—— + 它是底层 Socket 的快照,半死连接上返回 `false`,恰好会把最该关的连接留下来。 + 报告方式仍按既有约定:`DisconnectAsync` 失败抛出,`Dispose` 只记日志。 + - 连接/断开不再用 `Thread` 把同步调用伪装成异步;读/写本就是"调用方提供缓冲区"的同步实现,限制条件不变。 + ## 2.0.0-beta8 > 本批仍是 `2.0.0` 的预发布——`2.0.0` 正式版保持未发布。 diff --git a/src/StdUnit.Tags.S7/Channels/S7TagChannel.cs b/src/StdUnit.Tags.S7/Channels/S7TagChannel.cs index 9c8907b..ef97cfc 100644 --- a/src/StdUnit.Tags.S7/Channels/S7TagChannel.cs +++ b/src/StdUnit.Tags.S7/Channels/S7TagChannel.cs @@ -1,7 +1,5 @@ -using Microsoft.Extensions.Logging; +using Microsoft.Extensions.Logging; using StdUnit.Sharp7; -using Microsoft.FSharp.Core; - namespace StdUnit.Tags.S7; @@ -32,7 +30,7 @@ public S7TagChannel(S7TagChannelDescriptor descriptor, ILogger log /// /// S7Client 工厂。 - /// 如果不为 null,则在 被调用; + /// 如果不为 null,则在 里被调用; /// 如果返回null,则会直接使用默认的构造 /// public Func? ClientFactory { get; set; } @@ -52,112 +50,63 @@ public S7TagChannel(S7TagChannelDescriptor descriptor, ILogger log /// public virtual async Task DisconnectAsync(CancellationToken ct) { - await this.ExecuteOneByOneAsync( - async ct => - { - if (this.Client == null) - return; - - var tcs = new TaskCompletionSource(); - var th = new Thread(() => - { - try - { - this.Client?.Disconnect(); - this.Client = null; - tcs.SetResult(null); - } - catch (Exception ex) - { - this._logger.LogWarning(ex, "通道{ChannelName}断开连接失败", this.ChannelName()); - this.Client = null; - tcs.SetException(ex); - } - }); - th.IsBackground = true; - th.Start(); - await tcs.Task; - }, - ct - ); + await this.RunExclusiveAsync(() => + { + // 先摘引用再断开:断开失败也不留下状态未知的 Client;异常原样抛出,堆栈天然完整。 + var client = this.DetachClient(); + client?.Disconnect(); + }, ct); } /// public virtual async Task EnsureConnectedAsync(bool force, CancellationToken ct) { - await this.ExecuteOneByOneAsync( - async ct => + await this.RunExclusiveAsync(() => + { + //当前client存在并且连接有效 + if (!force && this.Client != null && !this.Client.IsDead()) { - //当前client存在并且连接有效 - if (!force && Client != null && !Client.IsDead()) - { - return; - } - var channelName = this.ChannelName(); + return; + } - // 如果要强制连接,先清理当前的连接 - if (force && Client != null) + var channelName = this.ChannelName(); + + // 如果要强制连接,先清理当前的连接 + if (force && this.Client != null) + { + this._logger.LogInformation("通道={ChannelName} 强制断开连接中...", channelName); + try { - try - { - this._logger.LogInformation("通道={ChannelName} 强制断开连接中...", channelName); - this.Client.Disconnect(); - } - catch (Exception ex) - { - this._logger.LogError(ex, "通道={ChannelName} 强制断开异常", channelName); - } - finally - { - this.Client = null; - } + this.DetachClient()?.Disconnect(); } - - var result = await this.CreateClientAndConnectAsync(ct); - if (result.IsError) + catch (Exception ex) { - var err = result.ErrorValue; - throw new InvalidOperationException($"通道({channelName}) 连接PLC失败:{this.PlcItem.IpAddr} Rack={this.PlcItem.Rack} Slot={this.PlcItem.Slot};{err.Text}({err.Error})"); + this._logger.LogError(ex, "通道={ChannelName} 强制断开异常", channelName); } - this.Client = result.ResultValue; - }, - ct - ); + } + + this.Client = this.CreateClientAndConnect(channelName); + }, ct); } /// - /// 创建客户端并连接PLC + /// 创建客户端并连接PLC。失败时抛 (消息带 Sharp7 的 ApiError 文案与错误码)。 /// - /// - /// - protected virtual Task> CreateClientAndConnectAsync(CancellationToken ct) + /// 通道名,仅用于错误消息 + protected virtual S7Client CreateClientAndConnect(string channelName) { - var tcs = new TaskCompletionSource>(); - var th = new Thread(() => + var client = this.ClientFactory?.Invoke(this.PlcItem) ?? new S7Client(); + client.SetConnectionType(this.PlcItem.ConnectionType); + + var code = client.ConnectTo(this.PlcItem.IpAddr, this.PlcItem.Rack, this.PlcItem.Slot); + if (code != 0) { - var client = ClientFactory?.Invoke(this.PlcItem) ?? new S7Client(); - client.SetConnectionType(this.PlcItem.ConnectionType); - try - { - var code = client.ConnectTo(this.PlcItem.IpAddr, this.PlcItem.Rack, this.PlcItem.Slot); - if (code == 0) - { - tcs.SetResult(FSharpResult.NewOk(client)); - } - else - { - tcs.SetResult(FSharpResult.NewError(S7ErrorCodeHelper.GenerateApiError(this.ChannelName(), code))); - } - } - catch (Exception ex) - { - tcs.SetException(ex); - } - }); - th.IsBackground = true; - th.Start(); - return tcs.Task; + var err = S7ErrorCodeHelper.GenerateApiError(channelName, code); + throw new InvalidOperationException($"通道({channelName}) 连接PLC失败:{this.PlcItem.IpAddr} Rack={this.PlcItem.Rack} Slot={this.PlcItem.Slot};{err.Text}({err.Error})"); + } + + return client; } @@ -246,36 +195,57 @@ public virtual void Write(string address, Span buffer, CancellationToken c /// public virtual void Dispose() { - var client = this.Client; - if (client != null && client.Connected) + try { - var channelName = this.ChannelName(); - try + this.RunExclusive(() => { - this._logger.LogInformation("通道={ChannelName} 正在释放: 断开连接中...", channelName); + var client = this.DetachClient(); + if (client is null) + { + return; + } - this.ExecuteOneByOne(() => + var channelName = this.ChannelName(); + try { client.Disconnect(); - this._logger.LogInformation("通道={ChannelName} 正在释放: 断开连接完成!", channelName); - }); - } - catch (Exception e) - { - this._logger.LogWarning("通道={ChannelName} 释放异常:{exception}", channelName, e.Message); - } + this._logger.LogInformation("通道={ChannelName} 释放完成(已断开连接)", channelName); + } + catch (Exception e) + { + // Dispose 只留痕、不外抛(.NET 的释放惯例)。 + this._logger.LogWarning(e, "通道={ChannelName} 释放异常", channelName); + } + }); + } + finally + { + this._rw.Dispose(); } - this.Client = null; - this._rw.Dispose(); } + /// + /// 把当前连接摘下来并清空 。不做断开动作——由调用方决定怎么处理: + /// 让它抛(显式方法报告失败), 与强制重连只记日志。
+ /// 有意不判 :它是底层 Socket 的快照,半死连接上返回 false, + /// 恰好会把最该关的 socket 留下来。 + ///
+ private S7Client? DetachClient() + { + var client = this.Client; + this.Client = null; + return client; + } - private async Task ExecuteOneByOneAsync(Func action, CancellationToken ct) + /// + /// 独占 I/O 互斥体执行一段同步工作(读/写直接用 ,因为 不能进闭包)。 + /// + private void RunExclusive(Action action, CancellationToken ct = default) { - await this._rw.WaitAsync(ct); + this._rw.Wait(ct); try { - await action(ct); + action(); } finally { @@ -283,9 +253,12 @@ private async Task ExecuteOneByOneAsync(Func action, Ca } } - private void ExecuteOneByOne(Action action) + /// + /// 同 ,差别只在"等待互斥体时可取消"——连接/断开这类可能长时间持锁的操作走这个。 + /// + private async Task RunExclusiveAsync(Action action, CancellationToken ct) { - this._rw.Wait(); + await this._rw.WaitAsync(ct); try { action(); diff --git a/tests/StdUnit.Tags.Tests/S7Tags/S7TagChannelTests.cs b/tests/StdUnit.Tags.Tests/S7Tags/S7TagChannelTests.cs index fa824f9..d27253a 100644 --- a/tests/StdUnit.Tags.Tests/S7Tags/S7TagChannelTests.cs +++ b/tests/StdUnit.Tags.Tests/S7Tags/S7TagChannelTests.cs @@ -357,15 +357,18 @@ public void Dispose_WhenClientConnected_ShouldDisconnect() Assert.Null(channel.Client); } + /// + /// 不判 Connected:它是底层 Socket 的快照,半死连接上返回 false,恰好会把最该关的连接留下来。 + /// [Fact] - public void Dispose_WhenClientNotConnected_ShouldNotDisconnect() + public void Dispose_WhenClientNotConnected_ShouldStillDisconnect() { var (channel, mock) = CreateChannel(connected: false); channel.Client = mock; channel.Dispose(); - Assert.Equal(0, mock.DisconnectCallCount); + Assert.Equal(1, mock.DisconnectCallCount); Assert.Null(channel.Client); } From b9898d4d970c416f06dd1a8f26d5ad6f39d1b437 Mon Sep 17 00:00:00 2001 From: newbienewbie Date: Wed, 11 Nov 2026 21:38:58 +0800 Subject: [PATCH 06/17] =?UTF-8?q?=E8=BF=90=E8=A1=8C=E6=9C=9F=E6=8C=87?= =?UTF-8?q?=E6=A0=87=EF=BC=8C=E5=B9=B6=E8=AE=A9=E7=A8=8B=E5=BA=8F=E9=9B=86?= =?UTF-8?q?=E5=B8=A6=E4=B8=8A=E7=9C=9F=E5=AE=9E=E7=89=88=E6=9C=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - StdUnit.Tags:用 System.Diagnostics.Metrics 暴露 4 个入口级指标 turns / turn.duration(单位 s) / failures / reconnects,维度只有 entry(入口定位路径); 无监听者时零分配、无开关;net472 因此引入 System.Diagnostics.DiagnosticSource(仅该 TFM) - 契约常量集中在公开的 TagsMetricContract(名称/单位/tag 键),由 MetricsContractTests 与字面量比对钉住;实现(Meter/instrument/记录)在 internal 的 TagsMetric - ITagGrpExtensions.GetLocationPath() 改为 public:加载期错误消息与指标 entry 维度共用同一格式 - publish-packages.ps1 额外注入 -p:InformationalVersion:此前每个版本的程序集都自称 1.0.0; AssemblyVersion 仍保持 1.0.0.0 --- CHANGELOG.md | 11 ++ README.md | 45 ++++- paket.lock | 22 +-- .../TagGrps/ITagGrpExtensions.cs | 7 +- .../TagGrpRunners/TagGrpRunner.cs | 16 +- src/StdUnit.Tags/TagGrpRunners/TagsMetric.cs | 76 ++++++++ src/StdUnit.Tags/TagsMetricContract.cs | 45 +++++ src/StdUnit.Tags/paket.references | 3 +- src/publish-packages.ps1 | 12 +- .../TagGrpRunners/MetricsContractTests.cs | 174 ++++++++++++++++++ .../Core/TagGrpRunners/TagGrpRunnerTests.cs | 51 +++++ 11 files changed, 438 insertions(+), 24 deletions(-) create mode 100644 src/StdUnit.Tags/TagGrpRunners/TagsMetric.cs create mode 100644 src/StdUnit.Tags/TagsMetricContract.cs create mode 100644 tests/StdUnit.Tags.Tests/Core/TagGrpRunners/MetricsContractTests.cs diff --git a/CHANGELOG.md b/CHANGELOG.md index 620e5fa..9702ed4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,6 +28,17 @@ StdUnit.Tags.S7: **通道内部简化**(公开行为不变) 报告方式仍按既有约定:`DisconnectAsync` 失败抛出,`Dispose` 只记日志。 - 连接/断开不再用 `Thread` 把同步调用伪装成异步;读/写本就是"调用方提供缓冲区"的同步实现,限制条件不变。 +StdUnit.Tags: **新增运行期指标(`System.Diagnostics.Metrics`)** + - Meter 名 `StdUnit.Tags`,四个指标:`stdunit.tags.turns`、`stdunit.tags.turn.duration`(单位 `s`)、 + `stdunit.tags.failures`、`stdunit.tags.reconnects`;维度只有 `entry`(入口定位路径)。 + 指标名 / 单位 / tag 键属于对外契约,只增不改;无监听者时零分配,也没有开关。 + - 新增**公开静态类 `TagsMetricContract`**:上述契约(名称 / 单位 / tag 键)以常量形式集中暴露 + (`MeterName` / `Turns` / `TurnDurationUnit` / `EntryTag` …),订阅与建视图时不用抄字面量。 + - **net472 因此多一个依赖** `System.Diagnostics.DiagnosticSource`(net8.0 由共享框架提供); + `StdUnit.Tags.Core` 仍然零外部依赖。 + - 新增公开扩展 `ITagGrpExtensions.GetLocationPath()`:返回 `TagGrp(a)/TagGrp(b)` 形式的定位路径。 + 它此前只是加载期错误消息的内部工具,现在错误消息与指标的 `entry` 维度共用这一种格式。 + ## 2.0.0-beta8 > 本批仍是 `2.0.0` 的预发布——`2.0.0` 正式版保持未发布。 diff --git a/README.md b/README.md index ee61f48..02f6749 100644 --- a/README.md +++ b/README.md @@ -100,11 +100,11 @@ dotnet new tags.driver -n your-project.name -D YourDriver 扩展包: - `StdUnit.Tags.RxExtensions`: `dotnet/reactive`扩展,只依赖于`StdUnit.Tags.Core` - `StdUnit.Tags.R3Extensions`: `Cysharp/R3`扩展,只依赖于`StdUnit.Tags.Core` -- `StdUnit.Tags.BlazorLib.Core`: Blazor 类库,包含核心功能抽象,以及一个极简的监控页面。 - `StdUnit.Tags.McpServer`: 这是一个把`StdUnit.Tags`暴露成 [Model Context Protocol Server](https://modelcontextprotocol.io/) 的类库。 - `StdUnit.Tags.WebUi`: 测点项目的 **Web 界面**(ASP.NET Core,不依赖 Blazor / SignalR,可在 NativeAOT 宿主下使用)。监控侧:结构树走一次性 `GET`、值按"入口 + 轮次"以 SSE(`text/event-stream`)推送,内置极简监控页(`GET /stdunit.tags/ui`);设计器侧:把核心 + 各驱动 schema 内省成元数据(`GET /stdunit.tags/catalog`),通道/测点设计器据此渲染表单、导入既有项目 XML 并导出(`GET /stdunit.tags/designer`,未知驱动/元素/属性原样保留)。页面都是单文件 HTML + 内嵌 JS,无需 npm 工程。另有两个写命令(`POST /stdunit.tags/value` 改值、`POST /stdunit.tags/rescan` 标记未扫描)。端点只允许改**路由前缀**(`app.MapTagsStream("/internal/tags")`),相对路径是线协议的一部分;**不内置任何鉴权**,暴露到非受信网络前请对返回的路由组加策略,例如 `app.MapTagsStream().RequireAuthorization()`。 +- `StdUnit.Tags.BlazorLib.Core`: Blazor 类库,**2.0 起进入维护模式**:不再新增功能,新的界面能力(监控 + 设计器)都做在 `StdUnit.Tags.WebUi` 上。 -> 备注:源码目录中还有一个 `StdUnit.Tags.BlazorLib`(不是 `StdUnit.Tags.BlazorLib.Core`),放的是常用硬件设备的编辑器和设计器实现。这些只是我把脑子里的片段随手写下来的实验性代码——因为将来可能做成类库,里面不少东西被标成了`public`——目前它只是实验场,不对外发布。 +> 备注:2.0 起移除了实验性的 `StdUnit.Tags.BlazorLib`(各驱动通道描述符的查看器/编辑器)。它从未对外发布,功能已由 `StdUnit.Tags.WebUi` 的设计器覆盖;需要图形化配置请用 WebUi。 相关测试统一放在 `tests/` 下的两个测试项目中: - `StdUnit.Tags.Tests`: 上述子项目的自动化测试(多目标 `net8.0` + `net472`)。 @@ -126,20 +126,53 @@ dotnet new tags.driver -n your-project.name -D YourDriver | Rx扩展 | `StdUnit.Tags.RxExtensions` | ✅ 支持 | | R3扩展 | `StdUnit.Tags.R3Extensions` | ✅ 支持 | | McpServer扩展 | `StdUnit.Tags.McpServer` | ✅ 支持 | -| BlazorLibCore扩展 | `StdUnit.Tags.BlazorLib.Core` | ✅ 支持 | | Web 界面(监控 + 设计器) | `StdUnit.Tags.WebUi` | 🧪 实验 | +| BlazorLib扩展 | `StdUnit.Tags.BlazorLib.Core` | ✅ 支持(维护模式) | -上表列出的包中,标记为“实验”的,`..` 里的 `` 跳变可能包含破坏性更新;标记为“支持”的,只有 `` 跳变才可能包含破坏性更新。核心包(`StdUnit.Tags`、`StdUnit.Tags.Core`)不属于驱动/扩展、因此不在此表内,按语义化版本处理——同样只有 `` 跳变才可能包含破坏性更新。 +上表列出的包中,标记为“实验”的,`..` 里的 `` 跳变可能包含破坏性更新; +标记为“支持”的,只有 `` 跳变才可能包含破坏性更新。核心包(`StdUnit.Tags`、`StdUnit.Tags.Core`)不属于驱动/扩展、因此不在此表内,按语义化版本处理——同样只有 `` 跳变才可能包含破坏性更新。 > 警告:有一些未在本仓库中列出的驱动及扩展,却由我发布到公开的`nuget.org`上以及私有的测试源上(比如[`StdUnit.Tags.LinuxFs.ProcInfo`](https://www.nuget.org/packages/StdUnit.Tags.LinuxFs.ProcInfo)、[`StdUnit.Tags.WinUsbKeyboardCodeScanners`](https://www.nuget.org/packages/StdUnit.Tags.WinUsbKeyboardCodeScanners/)),只供内部使用——那部分包不对外提供任何质量保证,请谨慎使用。 +### 运行期观测(Metrics) + +`StdUnit.Tags` 用 `System.Diagnostics.Metrics` 暴露入口的运行期指标。net8.0 用共享框架里的实现; +**net472 会因此引入 `System.Diagnostics.DiagnosticSource` 依赖**(`StdUnit.Tags.Core` 仍是零外部依赖)。 + +| 指标 | 类型 | 单位 | 维度 | +|---|---|---|---| +| `stdunit.tags.turns` | `Counter` | `{turn}` | `entry` | +| `stdunit.tags.turn.duration` | `Histogram` | `s` | `entry` | +| `stdunit.tags.failures` | `Counter` | `{failure}` | `entry` | +| `stdunit.tags.reconnects` | `Counter` | `{reconnect}` | `entry` | + +- Meter 名固定为 `StdUnit.Tags`。 +- `entry` 是入口的定位路径(`TagGrp(a)/TagGrp(b)`,与加载期错误消息、`ITagGrpExtensions.GetLocationPath()` 同格式)。 +- **不**带测点名/地址维度(无界基数),也不带 `driver`(失败可能来自入口下的辅通道,标主通道会算错责任人)。 +- 指标名、单位与 tag 键属于对外契约:只会新增,不会改名。它们集中暴露在公开静态类 + `TagsMetricContract`(`MeterName` / `Turns` / `TurnDurationUnit` / `EntryTag` …)里,订阅与建视图时直接引用即可。 +- 没人订阅时记录是零分配、纳秒级的,所以没有“是否启用”的开关。 + +订阅方式二选一: + +```csharp +// OpenTelemetry +builder.Services.AddOpenTelemetry() + .WithMetrics(m => m.AddMeter(TagsMetricContract.MeterName)); +``` + +```powershell +# 或直接用 dotnet-counters 观察 +dotnet-counters monitor --counters StdUnit.Tags -p +``` + ### 给人类的 0. 我们为本类库编写了专门的文档和教程,部署在[https://tags.doc.stdunit.com](https://tags.doc.stdunit.com)。其中由浅入深地讲解了基本概念、常用写法、设计思路和驱动专题,也穿插了不少常见故障与排错手法。 1. 仓库内 [`docs/`](docs/) 放**框架性**内容:[核心模型](docs/核心模型.md)、[外部意图与死锁](docs/外部意图.md)、[扩展点](docs/扩展点.md)、[错误处理](docs/异常处理.md)、[设计决策与边界](docs/设计决策与边界/)(范围与运行期契约、[CI 取舍](docs/设计决策与边界/1.%20CI.md)、[兼容与命名](docs/设计决策与边界/2.%20兼容与命名.md)、[打包与发布](docs/设计决策与边界/3.%20打包与发布.md));详细使用说明见上一点。 2. 本仓库自带的 [Samples](https://github.com/StdUnit/StdUnit.Tags/tree/dev/samples):主要用于开发验证+喂狗。AOT 冒烟程序(`AotSmokeTest.*`)已挪到 [`tests/`](https://github.com/StdUnit/StdUnit.Tags/tree/dev/tests)。(其中 `samples/WpfDemo` 是 WPF 示例,依赖 Windows SDK,所以有意**不纳入到解决方案内**;有需要时,在本地`windows`上用 `dotnet build samples/WpfDemo/WpfDemo.csproj` 单独构建。) 3. 供新手熟悉功能的 [WPFDemo](https://github.com/StdUnit/StdUnit.Tags.WPFDemo):按分支演示功能。 -4. 对于已经开放给公众使用的包,每一个公开的接口、类、方法、属性都写了`XML`注释,所以通过`*.nupkg`安装后即有完整的智能提示,也就没必要另外再提供在线版的`API`文档了,有需要的可以自己用 [`docfx`](https://github.com/dotnet/docfx) 生成(唯一的例外是 `StdUnit.Tags.BlazorLib`:它是只是实验性的代码片段,只对团队内部开放,暂时不发布到公开源上)。 +4. 对于已经开放给公众使用的包,每一个公开的接口、类、方法、属性都写了`XML`注释,所以通过`*.nupkg`安装后即有完整的智能提示,也就没必要另外再提供在线版的`API`文档了,有需要的可以自己用 [`docfx`](https://github.com/dotnet/docfx) 生成。 ### 给AI的 @@ -156,7 +189,7 @@ AI 可以直接参考 [StdUnit.Tags —— 给 AI 的参考手册](https://tags. | `StdUnit.Tags.RxExtensions` / `StdUnit.Tags.R3Extensions` | `net8.0` + `net472` | | `StdUnit.Tags.S7` / `ModbusTcp` / `Hjzk` / `ZLan` / `OpcUaClient` / `ComScanner` / `SimpleFiles` | `net8.0` + `net472` | | `StdUnit.Tags.McpServer` | `net8.0` + `net472`(经 `ModelContextProtocol` 核心包的 `netstandard2.0` 资产) | -| `StdUnit.Tags.BlazorLib` / `BlazorLib.Core` | 仅 `net8.0` | +| `StdUnit.Tags.BlazorLib.Core` | 仅 `net8.0` | | `StdUnit.Tags.WebUi` | 仅 `net8.0`(ASP.NET Core;依赖 `Microsoft.AspNetCore.App` 框架引用) | | `StdUnit.Tags.SchemaGenerator` | `netstandard2.0`(源生成器) | diff --git a/paket.lock b/paket.lock index 3df0526..02ec515 100644 --- a/paket.lock +++ b/paket.lock @@ -5,9 +5,9 @@ NUGET remote: https://api.nuget.org/v3/index.json BouncyCastle.Cryptography (2.4) Castle.Core (5.2.1) - System.Diagnostics.EventLog (>= 4.7) - restriction: || (&& (== net472) (< net462)) (&& (== net472) (>= netstandard2.1)) (&& (== net8.0) (< net6.0)) (&& (== net8.0) (< netstandard2.1)) (&& (== net8.0-windows7.0) (< net6.0)) (&& (== net8.0-windows7.0) (< netstandard2.1)) (== netstandard2.0) + System.Diagnostics.EventLog (>= 4.7) - restriction: || (&& (== net472) (== net8.0)) (&& (== net472) (== net8.0-windows7.0)) (&& (== net472) (< net462)) (&& (== net472) (>= netstandard2.1)) (&& (== net8.0) (< net6.0)) (&& (== net8.0) (< netstandard2.1)) (&& (== net8.0-windows7.0) (< net6.0)) (&& (== net8.0-windows7.0) (< netstandard2.1)) (== netstandard2.0) System.Diagnostics.EventLog (>= 6.0) - restriction: || (&& (== net472) (>= net6.0)) (== net8.0) (== net8.0-windows7.0) (&& (== netstandard2.0) (>= net6.0)) - System.Reflection.Emit (>= 4.7) - restriction: || (&& (== net472) (< net462)) (&& (== net8.0) (< netstandard2.1)) (&& (== net8.0-windows7.0) (< netstandard2.1)) (== netstandard2.0) + System.Reflection.Emit (>= 4.7) - restriction: || (&& (== net472) (== net8.0)) (&& (== net472) (== net8.0-windows7.0)) (&& (== net472) (< net462)) (&& (== net8.0) (< netstandard2.1)) (&& (== net8.0-windows7.0) (< netstandard2.1)) (== netstandard2.0) coverlet.collector (6.0) FSharp.Core (8.0.100) IsExternalInit (1.0.3) - restriction: == net472 @@ -115,7 +115,7 @@ NUGET Microsoft.Extensions.Options (8.0.2) Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0) Microsoft.Extensions.Primitives (>= 8.0) - System.ComponentModel.Annotations (>= 5.0) - restriction: || (&& (== net472) (< net462)) (&& (== net472) (>= netstandard2.1)) (&& (== net8.0) (< net6.0)) (&& (== net8.0) (< netstandard2.1)) (&& (== net8.0-windows7.0) (< net6.0)) (&& (== net8.0-windows7.0) (< netstandard2.1)) (== netstandard2.0) + System.ComponentModel.Annotations (>= 5.0) - restriction: || (&& (== net472) (== net8.0)) (&& (== net472) (== net8.0-windows7.0)) (&& (== net472) (< net462)) (&& (== net472) (>= netstandard2.1)) (&& (== net8.0) (< net6.0)) (&& (== net8.0) (< netstandard2.1)) (&& (== net8.0-windows7.0) (< net6.0)) (&& (== net8.0-windows7.0) (< netstandard2.1)) (== netstandard2.0) System.ValueTuple (>= 4.5) - restriction: || (== net472) (&& (== net8.0) (>= net462)) (&& (== net8.0-windows7.0) (>= net462)) (&& (== netstandard2.0) (>= net462)) Microsoft.Extensions.Primitives (8.0) Microsoft.JSInterop (8.0.12) - restriction: || (&& (== net472) (>= net8.0)) (== net8.0) (== net8.0-windows7.0) (&& (== netstandard2.0) (>= net8.0)) @@ -206,8 +206,8 @@ NUGET OPCFoundation.NetStandard.Opc.Ua.Core (>= 1.5.374.126) OPCFoundation.NetStandard.Opc.Ua.Core (1.5.374.126) Microsoft.Bcl.HashCode (>= 1.1.1) - restriction: || (== net472) (&& (== net8.0) (>= net472)) (&& (== net8.0) (< netstandard2.1)) (&& (== net8.0-windows7.0) (>= net472)) (&& (== net8.0-windows7.0) (< netstandard2.1)) (== netstandard2.0) - Microsoft.Extensions.Logging.Abstractions (>= 3.1.32) - restriction: || (&& (== net472) (>= netstandard2.1)) (&& (== net8.0) (< net6.0)) (&& (== net8.0) (< netstandard2.1)) (&& (== net8.0-windows7.0) (< net6.0)) (&& (== net8.0-windows7.0) (< netstandard2.1)) (== netstandard2.0) - Microsoft.Extensions.Logging.Abstractions (>= 6.0.4) - restriction: || (== net472) (&& (== net8.0) (>= net472)) (&& (== net8.0-windows7.0) (>= net472)) (&& (== net8.0-windows7.0) (< net8.0)) (&& (== netstandard2.0) (>= net472)) (&& (== netstandard2.0) (>= net6.0)) + Microsoft.Extensions.Logging.Abstractions (>= 3.1.32) - restriction: || (&& (== net472) (== net8.0)) (&& (== net472) (== net8.0-windows7.0)) (&& (== net472) (>= netstandard2.1)) (&& (== net8.0) (< net6.0)) (&& (== net8.0) (< netstandard2.1)) (&& (== net8.0-windows7.0) (< net6.0)) (&& (== net8.0-windows7.0) (< netstandard2.1)) (== netstandard2.0) + Microsoft.Extensions.Logging.Abstractions (>= 6.0.4) - restriction: || (== net472) (&& (== net8.0) (== netstandard2.0)) (&& (== net8.0) (>= net472)) (&& (== net8.0-windows7.0) (== netstandard2.0)) (&& (== net8.0-windows7.0) (>= net472)) (&& (== net8.0-windows7.0) (< net8.0)) (&& (== netstandard2.0) (>= net472)) (&& (== netstandard2.0) (>= net6.0)) Microsoft.Extensions.Logging.Abstractions (>= 8.0.1) - restriction: || (&& (== net472) (>= net8.0)) (== net8.0) (== net8.0-windows7.0) (&& (== netstandard2.0) (>= net8.0)) Newtonsoft.Json (>= 13.0.3) OPCFoundation.NetStandard.Opc.Ua.Security.Certificates (>= 1.5.374.126) @@ -477,7 +477,7 @@ NUGET System.Reflection.Primitives (>= 4.3) - restriction: || (&& (== net472) (< net45)) (== net8.0) (== net8.0-windows7.0) (== netstandard2.0) System.Runtime (>= 4.3) - restriction: || (&& (== net472) (< net45)) (== net8.0) (== net8.0-windows7.0) (== netstandard2.0) System.Reflection.Emit (4.7) - restriction: || (&& (== net472) (< net45)) (&& (== net472) (< net462)) (== net8.0) (== net8.0-windows7.0) (== netstandard2.0) - System.Reflection.Emit.ILGeneration (>= 4.7) - restriction: || (&& (== net472) (< net45)) (&& (== net472) (< netstandard1.1)) (&& (== net472) (< netstandard2.0) (>= wpa81)) (&& (== net472) (>= uap10.1)) (&& (== net8.0) (< netcoreapp2.0) (< netstandard2.1)) (&& (== net8.0) (< netstandard1.1)) (&& (== net8.0) (< netstandard2.0)) (&& (== net8.0) (>= uap10.1)) (&& (== net8.0-windows7.0) (< netcoreapp2.0) (< netstandard2.1)) (&& (== net8.0-windows7.0) (< netstandard1.1)) (&& (== net8.0-windows7.0) (< netstandard2.0)) (&& (== net8.0-windows7.0) (>= uap10.1)) (== netstandard2.0) + System.Reflection.Emit.ILGeneration (>= 4.7) - restriction: || (&& (== net472) (== net8.0)) (&& (== net472) (== net8.0-windows7.0)) (&& (== net472) (< net45)) (&& (== net472) (< netstandard1.1)) (&& (== net472) (< netstandard2.0) (>= wpa81)) (&& (== net472) (>= uap10.1)) (&& (== net8.0) (< netcoreapp2.0) (< netstandard2.1)) (&& (== net8.0) (< netstandard1.1)) (&& (== net8.0) (< netstandard2.0)) (&& (== net8.0) (>= uap10.1)) (&& (== net8.0-windows7.0) (< netcoreapp2.0) (< netstandard2.1)) (&& (== net8.0-windows7.0) (< netstandard1.1)) (&& (== net8.0-windows7.0) (< netstandard2.0)) (&& (== net8.0-windows7.0) (>= uap10.1)) (== netstandard2.0) System.Reflection.Emit.ILGeneration (4.7) - restriction: || (&& (== net472) (< net45)) (&& (== net472) (< netstandard1.1)) (&& (== net472) (< netstandard2.0) (>= wpa81)) (&& (== net472) (>= uap10.1)) (== net8.0) (== net8.0-windows7.0) (== netstandard2.0) System.Reflection.Emit.Lightweight (4.3) - restriction: || (&& (== net472) (< net45)) (== net8.0) (== net8.0-windows7.0) (== netstandard2.0) System.Reflection (>= 4.3) - restriction: || (&& (== net472) (< net45)) (== net8.0) (== net8.0-windows7.0) (== netstandard2.0) @@ -665,12 +665,12 @@ NUGET System.Threading.Tasks.Extensions (>= 4.5.4) - restriction: || (== net472) (&& (== net8.0) (>= net462)) (&& (== net8.0) (< net6.0)) (&& (== net8.0-windows7.0) (>= net462)) (&& (== net8.0-windows7.0) (< net6.0)) (== netstandard2.0) System.ValueTuple (>= 4.5) - restriction: || (== net472) (&& (== net8.0) (>= net462)) (&& (== net8.0-windows7.0) (>= net462)) (&& (== netstandard2.0) (>= net462)) System.Text.RegularExpressions (4.3) - restriction: || (&& (== net472) (< net452)) (== net8.0) (== net8.0-windows7.0) (== netstandard2.0) - System.Collections (>= 4.3) - restriction: || (&& (== net472) (< net45)) (&& (== net8.0) (< netcoreapp1.1)) (&& (== net8.0-windows7.0) (< netcoreapp1.1)) (== netstandard2.0) - System.Globalization (>= 4.3) - restriction: || (&& (== net472) (< net45)) (&& (== net8.0) (< netcoreapp1.1)) (&& (== net8.0-windows7.0) (< netcoreapp1.1)) (== netstandard2.0) - System.Resources.ResourceManager (>= 4.3) - restriction: || (&& (== net472) (< net45)) (&& (== net8.0) (< netcoreapp1.1)) (&& (== net8.0-windows7.0) (< netcoreapp1.1)) (== netstandard2.0) + System.Collections (>= 4.3) - restriction: || (&& (== net472) (== net8.0)) (&& (== net472) (== net8.0-windows7.0)) (&& (== net472) (< net45)) (&& (== net8.0) (< netcoreapp1.1)) (&& (== net8.0-windows7.0) (< netcoreapp1.1)) (== netstandard2.0) + System.Globalization (>= 4.3) - restriction: || (&& (== net472) (== net8.0)) (&& (== net472) (== net8.0-windows7.0)) (&& (== net472) (< net45)) (&& (== net8.0) (< netcoreapp1.1)) (&& (== net8.0-windows7.0) (< netcoreapp1.1)) (== netstandard2.0) + System.Resources.ResourceManager (>= 4.3) - restriction: || (&& (== net472) (== net8.0)) (&& (== net472) (== net8.0-windows7.0)) (&& (== net472) (< net45)) (&& (== net8.0) (< netcoreapp1.1)) (&& (== net8.0-windows7.0) (< netcoreapp1.1)) (== netstandard2.0) System.Runtime (>= 4.3) - restriction: || (&& (== net472) (< net45)) (&& (== net472) (>= netcoreapp1.1)) (== net8.0) (== net8.0-windows7.0) (== netstandard2.0) - System.Runtime.Extensions (>= 4.3) - restriction: || (&& (== net472) (< net45)) (&& (== net8.0) (< netcoreapp1.1)) (&& (== net8.0-windows7.0) (< netcoreapp1.1)) (== netstandard2.0) - System.Threading (>= 4.3) - restriction: || (&& (== net472) (< net45)) (&& (== net8.0) (< netcoreapp1.1)) (&& (== net8.0-windows7.0) (< netcoreapp1.1)) (== netstandard2.0) + System.Runtime.Extensions (>= 4.3) - restriction: || (&& (== net472) (== net8.0)) (&& (== net472) (== net8.0-windows7.0)) (&& (== net472) (< net45)) (&& (== net8.0) (< netcoreapp1.1)) (&& (== net8.0-windows7.0) (< netcoreapp1.1)) (== netstandard2.0) + System.Threading (>= 4.3) - restriction: || (&& (== net472) (== net8.0)) (&& (== net472) (== net8.0-windows7.0)) (&& (== net472) (< net45)) (&& (== net8.0) (< netcoreapp1.1)) (&& (== net8.0-windows7.0) (< netcoreapp1.1)) (== netstandard2.0) System.Threading (4.3) - restriction: || (&& (== net472) (< net45)) (&& (== net472) (< net452)) (== net8.0) (== net8.0-windows7.0) (== netstandard2.0) System.Runtime (>= 4.3) - restriction: || (&& (== net472) (< net45)) (== net8.0) (== net8.0-windows7.0) (== netstandard2.0) System.Threading.Tasks (>= 4.3) - restriction: || (&& (== net472) (< net45)) (== net8.0) (== net8.0-windows7.0) (== netstandard2.0) diff --git a/src/StdUnit.Tags.Core/TagGrps/ITagGrpExtensions.cs b/src/StdUnit.Tags.Core/TagGrps/ITagGrpExtensions.cs index 394defc..55d2660 100644 --- a/src/StdUnit.Tags.Core/TagGrps/ITagGrpExtensions.cs +++ b/src/StdUnit.Tags.Core/TagGrps/ITagGrpExtensions.cs @@ -264,12 +264,13 @@ public static TagAccessMode SearchAccessMode(this ITagGrp tagGrp) #endregion /// - /// 生成测点组的定位路径(TagGrp(a)/TagGrp(b)),用于加载期错误消息。
+ /// 生成测点组的定位路径(TagGrp(a)/TagGrp(b))。
/// 分隔符与 的路径语法一致(都是 /),便于对照与复制。
- /// 承载项目根的内部节点 __main__ 会被省略,因此顶层组的路径就是它自己。 + /// 承载项目根的内部节点 __main__ 会被省略,因此顶层组的路径就是它自己。
+ /// 加载期错误消息与运行期指标(stdunit.tags.* 的 entry 维度)都用它,格式因此是对外契约。 ///
/// 起始组(含自身),可为 null - internal static string GetLocationPath(this ITagGrp? tagGrp) + public static string GetLocationPath(this ITagGrp? tagGrp) { var parts = new List(); for (var cur = tagGrp; cur is not null; cur = cur.Parent) diff --git a/src/StdUnit.Tags/TagGrpRunners/TagGrpRunner.cs b/src/StdUnit.Tags/TagGrpRunners/TagGrpRunner.cs index 03e06a3..aac631d 100644 --- a/src/StdUnit.Tags/TagGrpRunners/TagGrpRunner.cs +++ b/src/StdUnit.Tags/TagGrpRunners/TagGrpRunner.cs @@ -1,4 +1,4 @@ -using Microsoft.Extensions.Logging; +using Microsoft.Extensions.Logging; using System.Diagnostics; namespace StdUnit.Tags; @@ -48,6 +48,11 @@ public TagGrpRunner( /// public virtual async Task StartAsync(ITagGrp entry, CancellationToken ct) { + // 指标维度只随入口变化,建一次、每轮复用(每轮新建 tag 数组会让"指标零分配"失效)。 + var metricTags = TagsMetric.TagsFor(entry); + // 上一轮是否以崩溃收场?用于把"崩溃后的重新建连"记成一次 reconnect。 + var recovering = false; + while (!ct.IsCancellationRequested) { // 入口主通道。各回调中的 channel 参数恒为它。 @@ -90,6 +95,12 @@ public virtual async Task StartAsync(ITagGrp entry, CancellationToken ct) await ch.EnsureConnectedAsync(force: false, ct); } + if (recovering) + { + recovering = false; + TagsMetric.RecordReconnect(metricTags); + } + await this.DrainWriteIntentsAsync(entry, ct); if (entry.IsDirty()) { @@ -104,6 +115,7 @@ public virtual async Task StartAsync(ITagGrp entry, CancellationToken ct) await entry.WriteAsync(TraversalMode.RespectEnabled, ct); sw.Stop(); + TagsMetric.RecordTurn(metricTags, sw.Elapsed); var span = TimeSpan.FromMilliseconds(entry.SearchScanInterval() ?? 0); var delay = this._pollDelayStrategy.GetDelay(span, sw.Elapsed); if (delay > TimeSpan.Zero) @@ -128,6 +140,8 @@ public virtual async Task StartAsync(ITagGrp entry, CancellationToken ct) { aborted = true; _consecutiveFailures++; + recovering = true; + TagsMetric.RecordFailure(metricTags); var onCrashed = this.RunnerCrashed; if (onCrashed is not null) diff --git a/src/StdUnit.Tags/TagGrpRunners/TagsMetric.cs b/src/StdUnit.Tags/TagGrpRunners/TagsMetric.cs new file mode 100644 index 0000000..67387c2 --- /dev/null +++ b/src/StdUnit.Tags/TagGrpRunners/TagsMetric.cs @@ -0,0 +1,76 @@ +using System.Diagnostics.Metrics; + +namespace StdUnit.Tags; + +/// +/// 指标的实现:创建 、持有各 instrument、提供给运行器调用的记录方法。
+/// 名称 / 单位 / tag 键的契约常量统一在公开的 里,这里只引用、不重复定义。
+/// 无监听者时 Counter.Add / Histogram.Record 是零分配、纳秒级,所以没有"是否启用"的开关。 +///
+internal static class TagsMetric +{ + private static readonly Meter Meter = CreateMeter(); + + /// + /// 有意不传 version:AOT/裁剪下用反射读程序集自定义特性不可靠(元数据可能被裁掉,结果静默退化成 0.0.0)。
+ /// 打包脚本现在会注入 InformationalVersion,但零反射的读取方式(构建期生成常量)还没做, + /// 所以这里先不报版本,而不是用反射凑一个可能错误的值。 + ///
+ private static Meter CreateMeter() => new(TagsMetricContract.MeterName); + + /// + /// 入口维度:位置路径——唯一且基数有界。
+ /// 有意不带测点名/地址(无界基数);也不带 driver——失败可能来自入口下的辅通道, + /// 拿主通道去标注会把责任算错,宁可少一个维度也不要错误的数据。
+ /// 为什么返回数组而不是单个键值对:Counter.Add / Histogram.Record 的入参就是 + /// KeyValuePair<string, object?>[](或它的 span),而 TagList 是 ref struct, + /// 不能存进字段。数组是唯一“建一次、每轮复用、零额外分配”的形状;将来加维度也只改这里。 + ///
+ public static KeyValuePair[] TagsFor(ITagGrp entry) => + new[] { + new KeyValuePair(TagsMetricContract.EntryTag, entry.GetLocationPath()) + }; + + private static readonly Counter Turns = + Meter.CreateCounter( + TagsMetricContract.Turns, + TagsMetricContract.TurnsUnit, + "入口完整走完的轮次数(读入 → 逻辑 → 刷写)" + ); + + private static readonly Histogram TurnDuration = + Meter.CreateHistogram( + TagsMetricContract.TurnDuration, + TagsMetricContract.TurnDurationUnit, + "每轮耗时:从 EnsureConnected 到刷写输出(不含轮间等待)" + ); + + private static readonly Counter Failures = + Meter.CreateCounter( + TagsMetricContract.Failures, + TagsMetricContract.FailuresUnit, + "入口轮次崩溃次数(停机引起的取消不计)" + ); + + private static readonly Counter Reconnects = + Meter.CreateCounter( + TagsMetricContract.Reconnects, + TagsMetricContract.ReconnectsUnit, + "入口崩溃后重新建连并成功走完建连阶段的次数" + ); + + /// + /// 记录一轮完成。调用方必须传入复用的 tag 数组(每轮新建会抵消"指标本身零分配"的意义)。 + /// + public static void RecordTurn(KeyValuePair[] tags, TimeSpan elapsed) + { + Turns.Add(1, tags); + TurnDuration.Record(elapsed.TotalSeconds, tags); + } + + /// 记录一次崩溃。 + public static void RecordFailure(KeyValuePair[] tags) => Failures.Add(1, tags); + + /// 记录一次崩溃后的恢复(重新走完建连阶段)。 + public static void RecordReconnect(KeyValuePair[] tags) => Reconnects.Add(1, tags); +} \ No newline at end of file diff --git a/src/StdUnit.Tags/TagsMetricContract.cs b/src/StdUnit.Tags/TagsMetricContract.cs new file mode 100644 index 0000000..298decb --- /dev/null +++ b/src/StdUnit.Tags/TagsMetricContract.cs @@ -0,0 +1,45 @@ +namespace StdUnit.Tags; + +/// +/// 本库运行期指标的**契约**:Meter 名、指标名、单位与 tag 键。
+/// 使用方按这些字面量订阅与查询,因此它们不会改名——改名等于让对方的 dashboard 静默变空, +/// 把单位从 s 改成 ms 会让曲线错 1000 倍,而两边都不会有编译错误。只会新增,不会重命名。
+/// 改动流程:先改 CHANGELOG(按破坏性变更写)+ README 的指标表,再改这里,最后同步 +/// MetricsContractTests 里的"字面量钉子"——那条测试故意与字面量比对,就是为了拦住"顺手改名"。 +///
+public static class TagsMetricContract +{ + /// Meter 名,使用方按它订阅:AddMeter(TagsMetricContract.MeterName)。 + /// + /// 固定为全家族共用的名字,不要按运行器/子系统拆 Meter:使用方订阅一次即可覆盖将来新增的所有指标, + /// 而 dotnet-counters --counters StdUnit.Tags 是精确匹配,拆细之后就看不到了。 + /// + public const string MeterName = "StdUnit.Tags"; + + /// 指标名:入口完整走完的轮次数(读入 → 逻辑 → 刷写)。 + public const string Turns = "stdunit.tags.turns"; + + /// 指标单位:轮次。 + public const string TurnsUnit = "{turn}"; + + /// 指标名:每轮耗时(从 EnsureConnected 到刷写输出,不含轮间等待)。 + public const string TurnDuration = "stdunit.tags.turn.duration"; + + /// 指标单位:秒。不要改成 ms——OTel 约定与既有 dashboard 都按秒。 + public const string TurnDurationUnit = "s"; + + /// 指标名:入口轮次崩溃次数(停机引起的取消不计)。 + public const string Failures = "stdunit.tags.failures"; + + /// 指标单位:次(失败)。 + public const string FailuresUnit = "{failure}"; + + /// 指标名:入口崩溃后重新建连并成功走完建连阶段的次数。 + public const string Reconnects = "stdunit.tags.reconnects"; + + /// 指标单位:次(重连)。 + public const string ReconnectsUnit = "{reconnect}"; + + /// 唯一的 tag 键:入口的定位路径 + public const string EntryTag = "entry"; +} \ No newline at end of file diff --git a/src/StdUnit.Tags/paket.references b/src/StdUnit.Tags/paket.references index 6bd6c8c..d56ca22 100644 --- a/src/StdUnit.Tags/paket.references +++ b/src/StdUnit.Tags/paket.references @@ -6,4 +6,5 @@ FSharp.Core # net8.0 相关框架由共享框架提供;net472 需要包引用, System.Threading.Channels framework: net472 -IsExternalInit framework: net472 \ No newline at end of file +IsExternalInit framework: net472 +System.Diagnostics.DiagnosticSource framework: net472 \ No newline at end of file diff --git a/src/publish-packages.ps1 b/src/publish-packages.ps1 index 417e315..ea9e2df 100644 --- a/src/publish-packages.ps1 +++ b/src/publish-packages.ps1 @@ -109,8 +109,16 @@ $projects | ForEach-Object -Process{ try{ Write-Host "[-] current location: $distPath" - # 用数组 splat,避免 -OutputDir 带空格时被拆成多个参数 - $packArgs = @("-c", "Release", "-p:PackageVersion=$($packageVersion)") + # 用数组 splat,避免 -OutputDir 带空格时被拆成多个参数。 + # 同时注入 InformationalVersion:它默认派生自 $(Version)(恒为 1.0.0),不注入的话每个版本发布出去的 + # 程序集都自称 1.0.0——崩溃日志、dotnet-counters / OTel 的 scope 版本、以及任何读 AssemblyInformationalVersion + # 的地方都会拿到错值。只设 InformationalVersion、不动 Version,是为了让 AssemblyVersion 稳定在 1.0.0.0 + # (程序集身份不随补丁版跳动,net472 的绑定重定向也不用跟着改)。 + $packArgs = @( + "-c", "Release", + "-p:PackageVersion=$($packageVersion)", + "-p:InformationalVersion=$($packageVersion)" + ) if (-not [String]::IsNullOrEmpty($OutputDir)) { $packArgs += @("-o", $OutputDir) diff --git a/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/MetricsContractTests.cs b/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/MetricsContractTests.cs new file mode 100644 index 0000000..4ae287b --- /dev/null +++ b/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/MetricsContractTests.cs @@ -0,0 +1,174 @@ +using System; +using System.Collections.Generic; +using System.Diagnostics.Metrics; +using System.Threading.Tasks; +using Xunit; + +namespace StdUnit.Tags.Tests.Core.TagGrpRunners; + +/// +/// (公开契约:名称/单位/tag 键)与 (实际注册与记录)的固化测试: +/// Meter 名、指标名、单位、tag 键一旦改名,使用方的 dashboard 会静默变空,所以用字面量钉住; +/// 同时验证这些常量确实被传给了 Meter.CreateCounter/CreateHistogram,而不只是两个字符串相等。 +/// +public class MetricsContractTests +{ + private static bool HasEntryTag(ReadOnlySpan> tags, string expected) + { + foreach (var tag in tags) + { + if (tag.Key == "entry" && Equals(tag.Value, expected)) + { + return true; + } + } + + return false; + } + + [Fact] + public void Meter_Name_IsStable() + { + Assert.Equal("StdUnit.Tags", TagsMetricContract.MeterName); + } + + /// + /// 把每个契约字符串钉在字面量上。
+ /// 常量本身改起来毫无编译阻力,但使用方的 dashboard 会静默变空——这条测试就是那道阻力: + /// 谁改了常量,这里先红;要放行就得连同 CHANGELOG / README 一起改(见 的契约区注释)。 + ///
+ [Fact] + public void ContractStrings_ArePinned() + { + Assert.Equal("stdunit.tags.turns", TagsMetricContract.Turns); + Assert.Equal("{turn}", TagsMetricContract.TurnsUnit); + + Assert.Equal("stdunit.tags.turn.duration", TagsMetricContract.TurnDuration); + Assert.Equal("s", TagsMetricContract.TurnDurationUnit); + + Assert.Equal("stdunit.tags.failures", TagsMetricContract.Failures); + Assert.Equal("{failure}", TagsMetricContract.FailuresUnit); + + Assert.Equal("stdunit.tags.reconnects", TagsMetricContract.Reconnects); + Assert.Equal("{reconnect}", TagsMetricContract.ReconnectsUnit); + + Assert.Equal("entry", TagsMetricContract.EntryTag); + } + + /// 四个指标的名称与单位(单位属于契约:`s` 而不是 `ms`) + [Fact] + public void Instruments_HaveStableNamesAndUnits() + { + var units = new Dictionary(); + using var listener = new MeterListener + { + InstrumentPublished = (instrument, l) => + { + if (instrument.Meter.Name != TagsMetricContract.MeterName) + { + return; + } + + units[instrument.Name] = instrument.Unit; + l.EnableMeasurementEvents(instrument); + } + }; + listener.Start(); + + // 触发静态构造(指标在静态 ctor 里创建) + TagsMetric.RecordTurn( + new[] { new KeyValuePair("entry", "unit-test") }, + TimeSpan.FromMilliseconds(1)); + + Assert.Equal("s", units["stdunit.tags.turn.duration"]); + Assert.Equal("{turn}", units["stdunit.tags.turns"]); + Assert.Equal("{failure}", units["stdunit.tags.failures"]); + Assert.Equal("{reconnect}", units["stdunit.tags.reconnects"]); + } + + /// 一次轮次记录 = counter +1、histogram 记秒数,且都带 entry 维度 + [Fact] + public void RecordTurn_RecordsCounterAndHistogram_WithEntryTag() + { + var entry = "record-turn-" + Guid.NewGuid().ToString("N"); + var tags = new[] { new KeyValuePair("entry", entry) }; + + long turns = -1; + double seconds = double.NaN; + using var listener = new MeterListener + { + InstrumentPublished = (instrument, l) => + { + if (instrument.Meter.Name == TagsMetricContract.MeterName) + { + l.EnableMeasurementEvents(instrument); + } + } + }; + listener.SetMeasurementEventCallback((instrument, value, tagList, state) => + { + if (instrument.Name == "stdunit.tags.turns" && HasEntryTag(tagList, entry)) + { + turns = value; + } + }); + listener.SetMeasurementEventCallback((instrument, value, tagList, state) => + { + if (instrument.Name == "stdunit.tags.turn.duration" && HasEntryTag(tagList, entry)) + { + seconds = value; + } + }); + listener.Start(); + + TagsMetric.RecordTurn(tags, TimeSpan.FromSeconds(1.5)); + + Assert.Equal(1, turns); + Assert.Equal(1.5, seconds, 9); + } + + /// + /// 崩溃与恢复各自 +1,且只带 entry 维度(不带 driver——失败可能来自辅通道,标注主通道会算错责任人)。 + /// + [Fact] + public void RecordFailureAndReconnect_OnlyCarryEntryTag() + { + var entry = "record-failure-" + Guid.NewGuid().ToString("N"); + var tags = new[] { new KeyValuePair("entry", entry) }; + + var seen = new Dictionary(); + var tagKeys = new List(); + using var listener = new MeterListener + { + InstrumentPublished = (instrument, l) => + { + if (instrument.Meter.Name == TagsMetricContract.MeterName) + { + l.EnableMeasurementEvents(instrument); + } + } + }; + listener.SetMeasurementEventCallback((instrument, value, tagList, state) => + { + if (!HasEntryTag(tagList, entry)) + { + return; + } + + seen.TryGetValue(instrument.Name, out var current); + seen[instrument.Name] = current + (int)value; + foreach (var tag in tagList) + { + tagKeys.Add(tag.Key); + } + }); + listener.Start(); + + TagsMetric.RecordFailure(tags); + TagsMetric.RecordReconnect(tags); + + Assert.Equal(1, seen["stdunit.tags.failures"]); + Assert.Equal(1, seen["stdunit.tags.reconnects"]); + Assert.All(tagKeys, key => Assert.Equal("entry", key)); + } +} diff --git a/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/TagGrpRunnerTests.cs b/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/TagGrpRunnerTests.cs index 06d833a..dd8eb72 100644 --- a/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/TagGrpRunnerTests.cs +++ b/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/TagGrpRunnerTests.cs @@ -1,6 +1,7 @@ using System; using System.Collections.Concurrent; using System.Collections.Generic; +using System.Diagnostics.Metrics; using System.Threading; using System.Threading.Channels; using System.Threading.Tasks; @@ -818,6 +819,56 @@ public async Task StartAsync_WithRealTagGrp_RespectsIsEnabledOfChildren() Assert.Equal(1, enabled.WriteCount); } + /// + /// 运行器把每轮记进 Metrics:stdunit.tags.turns 至少有一条带该入口路径的测量。 + /// 用 MeterListener 的完成信号而不是"等一会儿再断言",避免机器忙时的随机红。 + /// + [Fact] + public async Task StartAsync_RecordsTurnMetrics() + { + var (runner, entry, _, _) = CreateRunner(); + entry.Descriptor!.Name = "metrics-" + Guid.NewGuid().ToString("N"); + entry.Descriptor!.ScanInterval = 10; + entry.IsEnabled = true; + var expectedEntry = entry.GetLocationPath(); + + var turnRecorded = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); + using var listener = new MeterListener(); + listener.InstrumentPublished = (instrument, l) => + { + if (instrument.Meter.Name == TagsMetricContract.MeterName) + { + l.EnableMeasurementEvents(instrument); + } + }; + listener.SetMeasurementEventCallback((instrument, value, tagList, state) => + { + if (instrument.Name != "stdunit.tags.turns") + { + return; + } + + foreach (var tag in tagList) + { + if (tag.Key == "entry" && Equals(tag.Value, expectedEntry)) + { + turnRecorded.TrySetResult(true); + return; + } + } + }); + listener.Start(); + + using var cts = new CancellationTokenSource(); + var runTask = RunUntilCancelled(runner, entry, cts.Token); + + var completed = await Task.WhenAny(turnRecorded.Task, Task.Delay(TimeSpan.FromSeconds(15))); + Assert.Same(turnRecorded.Task, completed); + + cts.Cancel(); + await runTask; + } + #region Mocks /// From 0f9753dd111075a5c9645279700e287764ec5eb5 Mon Sep 17 00:00:00 2001 From: newbienewbie Date: Wed, 11 Nov 2026 22:01:43 +0800 Subject: [PATCH 07/17] =?UTF-8?q?=E5=A2=9E=E5=8A=A0benchmark?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 3 + StdUnit.Tags.sln | 11 +- benchmarks/Directory.Build.props | 17 ++ benchmarks/README.md | 199 ++++++++++++++++++ .../StdUnit.Tags.Benchmarks/BenchFakes.cs | 35 +++ .../CbntFanOutBenchmarks.cs | 78 +++++++ .../MemoryFootprintReport.cs | 119 +++++++++++ .../MetricRecordingBenchmarks.cs | 50 +++++ .../ModbusCbntReadBenchmarks.cs | 79 +++++++ benchmarks/StdUnit.Tags.Benchmarks/Program.cs | 24 +++ .../S7ChannelReadBenchmarks.cs | 49 +++++ .../StdUnit.Tags.Benchmarks.csproj | 25 +++ .../TagTreeTraversalBenchmarks.cs | 52 +++++ .../TraversalBreakdownBenchmarks.cs | 137 ++++++++++++ .../StdUnit.Tags.Benchmarks/paket.references | 2 + paket.dependencies | 13 ++ paket.lock | 175 +++++++++++++++ .../TagCbnts/ITagCbntExtensions.cs | 6 +- .../TagContainers/TagContainer.cs | 6 +- .../TagContainers/TagContainerExtensions.cs | 13 ++ src/StdUnit.Tags.Core/TagGrps/TagGrp.cs | 12 +- src/StdUnit.Tags.Core/TagUnions/TagUnion.cs | 7 + .../TagUnions/TagUnionExtensions.cs | 145 ++++++++----- src/StdUnit.Tags.Core/Tags/ITagExtensions.cs | 13 +- src/StdUnit.Tags.Core/attribs.cs | 3 +- src/StdUnit.Tags.ModbusTcp/attribs.cs | 3 +- src/StdUnit.Tags.S7/S7Address.cs | 11 +- src/StdUnit.Tags.S7/attribs.cs | 3 +- src/StdUnit.Tags/TagCbnt.cs | 10 +- src/StdUnit.Tags/attribs.cs | 3 +- .../Core/AccessModeInheritanceTests.cs | 117 ++++++++++ 31 files changed, 1336 insertions(+), 84 deletions(-) create mode 100644 benchmarks/Directory.Build.props create mode 100644 benchmarks/README.md create mode 100644 benchmarks/StdUnit.Tags.Benchmarks/BenchFakes.cs create mode 100644 benchmarks/StdUnit.Tags.Benchmarks/CbntFanOutBenchmarks.cs create mode 100644 benchmarks/StdUnit.Tags.Benchmarks/MemoryFootprintReport.cs create mode 100644 benchmarks/StdUnit.Tags.Benchmarks/MetricRecordingBenchmarks.cs create mode 100644 benchmarks/StdUnit.Tags.Benchmarks/ModbusCbntReadBenchmarks.cs create mode 100644 benchmarks/StdUnit.Tags.Benchmarks/Program.cs create mode 100644 benchmarks/StdUnit.Tags.Benchmarks/S7ChannelReadBenchmarks.cs create mode 100644 benchmarks/StdUnit.Tags.Benchmarks/StdUnit.Tags.Benchmarks.csproj create mode 100644 benchmarks/StdUnit.Tags.Benchmarks/TagTreeTraversalBenchmarks.cs create mode 100644 benchmarks/StdUnit.Tags.Benchmarks/TraversalBreakdownBenchmarks.cs create mode 100644 benchmarks/StdUnit.Tags.Benchmarks/paket.references create mode 100644 tests/StdUnit.Tags.Tests/Core/AccessModeInheritanceTests.cs diff --git a/README.md b/README.md index 02f6749..646d6e5 100644 --- a/README.md +++ b/README.md @@ -78,6 +78,9 @@ dotnet new tags.driver -n your-project.name -D YourDriver - `src/`: 源码,主要包括核心包、驱动包和扩展包 - `tests/`: 自动化测试项目(`StdUnit.Tags.Tests` / `StdUnit.Tags.Tests.NetCoreOnly`)与 AOT 冒烟程序(`AotSmokeTest.*`) - `samples/`:放示例与喂狗程序 +- `benchmarks/`:性能基准(BenchmarkDotNet,`net8.0`)。在解决方案内,所以 `dotnet build` 会编译它以防 API 漂移; + **不**参与 CI 的测试与 AOT 冒烟。最新数据与解读见 [benchmarks/README.md](benchmarks/README.md)。 + 本地跑:`dotnet run -c Release --project benchmarks/StdUnit.Tags.Benchmarks -- --filter *`。 - `.config/` - `dotnet-tools.json`: 本项目用到的 dotnet tools 配置 - `paket.dependencies`: 用 [`paket`](https://github.com/fsprojects/Paket)管理的依赖声明 diff --git a/StdUnit.Tags.sln b/StdUnit.Tags.sln index 0827511..714db31 100644 --- a/StdUnit.Tags.sln +++ b/StdUnit.Tags.sln @@ -1,4 +1,4 @@ -Microsoft Visual Studio Solution File, Format Version 12.00 +Microsoft Visual Studio Solution File, Format Version 12.00 # Visual Studio Version 18 VisualStudioVersion = 18.8.12023.21 MinimumVisualStudioVersion = 10.0.40219.1 @@ -66,6 +66,10 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "AotSmokeTest.WebUi", "tests EndProject Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "WebMonitor", "samples\WebMonitor\WebMonitor.csproj", "{018E69DC-830B-4DD4-BC68-7716821226E0}" EndProject +Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "benchmarks", "benchmarks", "{DFF2F2C3-1DDD-4DD3-B74C-1070B5EC17A0}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "StdUnit.Tags.Benchmarks", "benchmarks\StdUnit.Tags.Benchmarks\StdUnit.Tags.Benchmarks.csproj", "{BC9D591B-BE00-422E-AE36-FD8FF31EE66B}" +EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution Debug|Any CPU = Debug|Any CPU @@ -168,6 +172,10 @@ Global {018E69DC-830B-4DD4-BC68-7716821226E0}.Debug|Any CPU.Build.0 = Debug|Any CPU {018E69DC-830B-4DD4-BC68-7716821226E0}.Release|Any CPU.ActiveCfg = Release|Any CPU {018E69DC-830B-4DD4-BC68-7716821226E0}.Release|Any CPU.Build.0 = Release|Any CPU + {BC9D591B-BE00-422E-AE36-FD8FF31EE66B}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {BC9D591B-BE00-422E-AE36-FD8FF31EE66B}.Debug|Any CPU.Build.0 = Debug|Any CPU + {BC9D591B-BE00-422E-AE36-FD8FF31EE66B}.Release|Any CPU.ActiveCfg = Release|Any CPU + {BC9D591B-BE00-422E-AE36-FD8FF31EE66B}.Release|Any CPU.Build.0 = Release|Any CPU EndGlobalSection GlobalSection(SolutionProperties) = preSolution HideSolutionNode = FALSE @@ -196,6 +204,7 @@ Global {1B85FF35-7A81-4CB7-924A-441EC3DA9218} = {2215F920-F9B4-4801-88A1-5F3E3E65B9CA} {87CBE561-3796-48DE-B121-E7534B49FE45} = {B9E1E3A0-6B7E-4A15-AB8C-CB5E3FFB29C8} {018E69DC-830B-4DD4-BC68-7716821226E0} = {02EA681E-C7D8-13C7-8484-4AC65E1B71E8} + {BC9D591B-BE00-422E-AE36-FD8FF31EE66B} = {DFF2F2C3-1DDD-4DD3-B74C-1070B5EC17A0} EndGlobalSection GlobalSection(ExtensibilityGlobals) = postSolution SolutionGuid = {6FF52024-3F01-4AC2-B991-CEE89ACF9FFC} diff --git a/benchmarks/Directory.Build.props b/benchmarks/Directory.Build.props new file mode 100644 index 0000000..81b268d --- /dev/null +++ b/benchmarks/Directory.Build.props @@ -0,0 +1,17 @@ + + + + + latest + enable + enable + false + false + + + diff --git a/benchmarks/README.md b/benchmarks/README.md new file mode 100644 index 0000000..1025cea --- /dev/null +++ b/benchmarks/README.md @@ -0,0 +1,199 @@ +# 性能基准(StdUnit.Tags.Benchmarks) + +> 本目录是**开发期工具**,不进入任何 NuGet 包(Paket 的 `Benchmarks` 组是 `storage: none`,工程 `IsPackable=false`)。 +> 它在解决方案内,所以 `dotnet build` 会编译它(防止 API 漂移后悄悄腐烂),但**不**参与 CI 的测试与 AOT 冒烟。 + +## 这份报告怎么读 + +- **只用于改动前后对比**:绝对耗时会随机器、runtime、编译选项变化,任何一行都不能当作对外性能承诺。 +- 全部为 `-c Release` 构建,开启 `[MemoryDiagnoser]`;`Allocated` 是单次操作的托管分配量。 +- 采集环境: + + | 项 | 值 | + |---|---| + | 日期 | 2026-11-11 | + | BenchmarkDotNet | v0.15.8 | + | .NET SDK | 8.0.129(`net8.0`) | + | OS | Windows 10 22H2 (10.0.19045) | + | CPU | Intel Core i7-8700 3.20 GHz,6 物理 / 12 逻辑核 | + +## 怎么跑 + +```powershell +# 全部 +dotnet run -c Release --project benchmarks/StdUnit.Tags.Benchmarks -- --filter * + +# 单个类 +dotnet run -c Release --project benchmarks/StdUnit.Tags.Benchmarks -- --filter "*TagTree*" + +# 只验证"能编译、能跑一次"(秒级,不产生测量意义的数据) +dotnet run -c Release --project benchmarks/StdUnit.Tags.Benchmarks -- --filter "*" --job dry + +# 常驻内存(对象图)报告:BDN 不测这个,走单独模式 +dotnet run -c Release --project benchmarks/StdUnit.Tags.Benchmarks -- --footprint +``` + +--- + +## 1. `TagTreeTraversalBenchmarks` — 框架自身开销 + +一棵 N 个测点的树(均分到 10 个子组),叶子是纯内存假测点、通道是空实现,所以测到的只有遍历、 +使能/脏标记判断与派发,与硬件、网络无关。 + +| 方法 | 点位 | Mean | Allocated | +|---|---|---|---| +| `NoOp`(基线) | — | 0.24 ns | 0 B | +| `ReadAsync` | 1 000 | 8.45 µs | **0 B** | +| `ReadAsync` | 10 000 | 94.15 µs | **0 B** | + +**结论**:每点耗时约 **8.4–9.4 ns**(1k 与 10k 同量级,线性),**整轮零分配**。 +1 万点位的框架开销约 0.094 ms,相对一轮真实采集(设备往返 ms 级)可以忽略。 + +### 1.1 时间花在哪(`TraversalBreakdownBenchmarks`,10 000 个扁平叶子) + +| 逐层加回成本 | 每点耗时 | 说明 | +|---|---|---| +| 纯数组遍历 | 0.47 ns | 基线 | +| + 访问模式解析(`SearchAccessMode`,**未走缓存**) | 6.2 ns | 逐级冒泡的裸成本:自身 → 父级 Cbnt → 各级 Grp → 兜底 RW | +| + 派发 + 完成检查 | 1.8 ns | 一次接口调用 + `Task.Status` | +| + 策略判断(R1W/WO)与派发 | 6.6 ns | 上面两项组合(有重叠) | +| `TagUnionExtensions.IsDirty`(每轮另一次全树扫描) | 5.0 ns | 全树干净时走完所有节点 | +| **实际遍历(`TagUnion.ReadAsync`,含缓存命中)** | **8.4–9.4 ns** | 见上表;比"裸解析"低,因为每节点一生只解析一次 | + +**瓶颈与结论**:逐级冒泡的**裸解析**是 6.2 ns/点,但**热路径上不会重复付这个钱**——访问模式是配置期属性, +解析结果缓存在 `TagUnion.CachedAccessMode` 上,之后只剩空值检查。所以剩下的就是一次派发 + 策略判断 + 状态回写, +已经接近"每个节点必须做的记账"的下限。要再快就只剩 `IsDirty` 全树扫描改成增量脏标记(语义改动大,暂不做)。 + +> 历史(2026-11 三轮修复): +> 1. `1 000 → 72.41 µs / 221.54 KB`、`10 000 → 775.93 µs / 2190.29 KB`: +> `TagUnionExtensions.ReadAsync/WriteAsync` 通过 `TagUnion.Map` 传三个 `async` 闭包, +> **每个节点**都要构造闭包 + 委托 + 异步状态机(≈220 B)。改为手动 `switch` 后降到 616 B / 轮。 +> 2. `616 B → 0 B`:`TagGrp.Children` / `TagCbnt.Children` 是 `IDictionary`,`foreach` 走接口会**装箱 +> `Dictionary.Enumerator`**(每次遍历一个分配),而它出现在每轮的读、写、判脏与通知路径上。 +> 改存具体 `Dictionary`、只让公开属性保持 `IDictionary` 后,分配归零; +> 同一改动把组合分发从 `9.88 µs / 128 B`(1 000 子测点)压到 `2.00 µs / 72 B`。 +> 3. `37.47 µs → 12.85 µs`(1 000 点):`SearchAccessMode` 原来用 `TagContainer.Map` + 两个委托, +> 每点位要查 **两次**(R1W 判定 + `IsWriteOnly`);改为 `TagContainer.AccessMode` 的 `switch`、 +> 只查一次,并给 `ReadAsync` 加了"读同步完成就不进 async 机制"的快路径。 +> 4. `12.85 µs → 8.45 µs`(1 000 点):访问模式改为**逐级冒泡**(修正 `ITag`/`ITagCbnt` 只查一层的旧缺陷), +> 同时按"访问模式是配置期属性"把它缓存在 `TagUnion.CachedAccessMode` 上——每个节点一生只解析一次, +> 之后是空值检查。正确性与速度同时拿到。 +> 前两条已写进 `docs/设计决策与边界/0. 设计决策与边界.md` §三:热点路径不要用 `Map` + 闭包, +> 也不要用 `IDictionary` 接口去 `foreach`。 + +## 2. `CbntFanOutBenchmarks` — “数千点位”的现实形态 + +真实的场景往往要组合多个测点成为一个`TagCbnt`,从而把N次读写合并成一次`IO`。这个测试正是为这个场景准备的。一次硬件读之后,把值分发给 N 个子测点(组合式测点)。这是 5 000 点位项目的真实形状;而“N 个独立测点各读一次”是 N 次设备往返,现实中不存在,因此不作为基准。 + +| 子测点数 | Mean | Allocated | +|---|---|---| +| 1 000 | 2.00 µs | 72 B | +| 5 000 | 12.79 µs | 72 B | + +**结论**:每点约 **2.6 ns**,逐点零分配(那 72 B 是基准桩里 `Task.FromResult` 的固定开销,不是框架的)。 +组合式的分发成本远低于遍历,说明“点位多”本身不是瓶颈。 + +## 3. `S7ChannelReadBenchmarks` — 读一块 DB + +用桩 `S7Client`(只占位、立即返回 0),测的是**我们这层**:地址解析、互斥体、`Span` 传递、错误码检查。 + +| 字节数 | Mean | Allocated | +|---|---|---| +| 1 000 | 588.9 ns | 832 B | +| 20 000 | 588.0 ns | 832 B | + +**结论**:单次读,内存分配与字节数无关(零拷贝,缓冲区是调用方提供的)。 +**真实耗时里 PLC 响应占绝对多数**,这组数字的用途是确认“我们不是瓶颈”。 + +> 历史(2026-11 修复前):`6.2 µs / 10.49 KB`(两种大小相同)。原因是 `S7AddressParser` 每次 `Parse` +> 都 `new Regex(...)`;提升为 `static readonly` 后降到现在这个水平。剩下的 832 B 来自 `Match`/`S7Address` 的分配, +> 要再压需改成 span 手写解析——目前不值得,已记录为“不做”。 + +## 4. `ModbusCbntReadBenchmarks` — cache 复用是否值得 + +组合式测点每轮读;用桩通道对比“每轮返回新数组”(现状)与“写入调用方预分配数组”(需要改公开接口)。 + +| 寄存器数 | 现状 | 复用 Cache | 耗时 | +|---|---|---|---| +| 32 | 160 B | 72 B | ~32 ns(无可测差异) | +| 125 | 352 B | 72 B | ~31–40 ns(抖动大于差距) | + +**结论:不做**。省下 9–28 KB/s(按 100 Hz 单入口估算),代价是 `IModbusRegisterChannel` / +`IModbusBitsChannel` 的公开签名变更(net472 没有默认接口方法兜底)。已记入 +`docs/设计决策与边界/0. 设计决策与边界.md` §五“已评估、决定不做”。 + +## 5. `MetricRecordingBenchmarks` — 打点开销 + +| 场景 | Mean | Allocated | +|---|---|---| +| 无监听者(默认部署) | 3.64 ns | 0 B | +| 有 `MeterListener` | 5.77 ns | 0 B | + +**结论**:验证了 README 的承诺——“没人订阅时零分配、纳秒级,所以不需要开关”。开启采集后每轮也只多 ~2 ns。 + +## 6. 内存:1000 个点和 10000 个点,有影响吗? + +要分两种"内存"看,它们经常被混为一谈: + +| | 是什么 | 与点位数的关系 | +|---|---|---| +| **每轮分配** | 每轮采集新产生的垃圾(`[MemoryDiagnoser]` 的 `Allocated`) | **无关**:1k 与 10k 完全相同 | +| **常驻内存** | 加载后一直活着的对象图(测点、组合子、描述符) | **线性**:点位数 × 每点约 350–390 B | + +### 6.1 每轮分配:与点位数无关(且已是 0) + +| 形态 | 1 000 点 | 10 000 点 | +|---|---|---| +| 遍历 | **0 B / 轮** | **0 B / 轮** | +| 组合式分发 | **0 B / 轮**(基准表里的 72 B 来自桩通道) | 同左 | + +也就是说:**高频采集时的 GC 压力与点位数无关,而且框架层当前是零分配**。 +2026-11 的两轮修复(`Map`+闭包 → `switch`;`IDictionary` 遍历 → 具体字典)把这件事从 +"每节点 220 B"做到了"每轮 0 B"。 + +### 6.2 常驻内存:严格线性 + +用 `--footprint` 模式测量(构建对象图前后各一次 full GC,取 `GC.GetTotalMemory(true)` 差值): + +| 形态 | 1 000 点 | 10 000 点 | 50 000 点 | 每点 | +|---|---|---|---|---| +| 树形(10 个子组) | 0.41 MB | 3.73 MB | 18.27 MB | ~383–432 B | +| 组合式(1 Cbnt + N 子测点) | 0.34 MB | 3.31 MB | 16.53 MB | ~347 B | + +**结论**: + +- 常驻内存是**一次性、线性**的:1 万点位约 **3.3–3.7 MB**,5 万点位约 **16–18 MB**(托管对象图,不含 XML 源文本与业务数据)。 + 这个量级对现代进程很小,**不构成部署障碍**。 +- 组合式比树形略省(少一层测点对象、`TagUnion` 包装与描述符),所以在点位密集时优先用组合式测点, + 内存与遍历成本都更低。 +- 这里是**下限**:真实项目还会持有 XML、字符串与业务侧对象;基准只量"本库自己的对象图"。 + +> 判断标准:**看"每轮分配"决定要不要优化**(它影响 GC 频率),**看"常驻内存"决定能装多少点**(它只影响一次性的堆占用)。 +> 两者都不是"点位数越多每轮越慢"的原因——每轮成本是线性的 ns/点,而分配是常数。 + +--- + +## 结论速览 + +| 关注点 | 数字 | 含义 | +|---|---|---| +| 框架遍历 | **8.4–9.4 ns/点、每轮 0 B** | 1 万点约 0.094 ms/轮,且不产生垃圾 | +| 判脏扫描(每轮一次) | 5 ns/点 | 全树干净时走完全部节点;10k ≈ 50 µs | +| 组合分发 | 2.6 ns/点、逐点零分配 | 点位多本身不是问题 | +| **常驻内存** | **~350–390 B/点;1k≈0.4 MB、10k≈3.5 MB、50k≈17 MB** | 与点位数线性,一次性占用,不构成部署障碍 | +| **每轮分配** | **1k 与 10k 都是 0 B** | 高频采集的 GC 压力与点位数无关 | +| S7 通道读 | 0.59 µs/次、832 B(与数据量无关) | 仅影响直读点位(兜底用法),PLC 决定实际耗时 | +| Modbus cache 复用 | 每轮省 88–280 B | 不值得改公开接口 | +| 指标记录 | 3.6 ns / 0 B;订阅后 5.8 ns | 可以放心常开 | + +> 分配**按点位线性放大**只发生在"直读点位"(DirectTag)形态:S7 每点一次地址解析 ≈832 B。 +> 但 DirectTag 是兜底用法,正常应把点位组织成 `TagCbnt`——那时一次硬件读 + 零分配分发,没有这个问题。 + +## 维护约定 + +- 新增基准:一个类一个关注点,`[MemoryDiagnoser]` 必开;**必须**能说明“这组数字能/不能得出什么结论”, + 避免把桩实现或回环网络的结果当成端到端性能。 +- 基准结果不设门槛(机器差异会让它变成随机红);它只用来做改动前后对比。 +- 改动热路径(遍历、组合通知、驱动读写)时,请顺手在本文件更新对应表格——**数字过期比没有更糟**。 +- 改了点位的对象结构(新增字段/包装层)时,记得重跑 `--footprint`:常驻内存是**每点 ~350 B** 的线性量, + 多一个字段就是几十 B × 点位数。 diff --git a/benchmarks/StdUnit.Tags.Benchmarks/BenchFakes.cs b/benchmarks/StdUnit.Tags.Benchmarks/BenchFakes.cs new file mode 100644 index 0000000..eed26a3 --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/BenchFakes.cs @@ -0,0 +1,35 @@ +using System.Threading; +using System.Threading.Tasks; + +namespace StdUnit.Tags.Benchmarks; + +/// 空实现通道:只为了让测点能挂上,不做任何 IO。 +internal sealed class BenchChannel : ITagChannel +{ + public TagChannelDescriptor Descriptor { get; } = new() { Name = "bench", Driver = "Bench" }; + + public Task EnsureConnectedAsync(bool force, CancellationToken ct) => Task.CompletedTask; + + public Task DisconnectAsync(CancellationToken ct) => Task.CompletedTask; + + public void Dispose() + { + } +} + +/// 纯内存测点:Read/Write 立即完成,只留下遍历与判定的成本。 +internal sealed class BenchLeafTag : Tag +{ + public BenchLeafTag(TagDescriptor descriptor, BenchChannel channel, ITagGrp parent) + : base(descriptor, channel, TagContainer.From(parent)) + { + } + + public override Task ReadAsync(CancellationToken ct) => Task.CompletedTask; + + public override Task WriteAsync(CancellationToken ct) + { + IsDirty = false; + return Task.CompletedTask; + } +} diff --git a/benchmarks/StdUnit.Tags.Benchmarks/CbntFanOutBenchmarks.cs b/benchmarks/StdUnit.Tags.Benchmarks/CbntFanOutBenchmarks.cs new file mode 100644 index 0000000..ab3ecf7 --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/CbntFanOutBenchmarks.cs @@ -0,0 +1,78 @@ +using System; +using System.Threading; +using System.Threading.Tasks; +using BenchmarkDotNet.Attributes; +using StdUnit.Tags.ModbusTcp; + +namespace StdUnit.Tags.Benchmarks; + +/// +/// "数千点位"的真实形态:一次硬件读(组合式测点)之后,把值分发给 N 个子测点。
+/// 这与"N 个独立测点各读一次"完全不同——那是 N 次设备往返,现实中不会这么用; +/// 框架真正花时间的地方在遍历、通知与脏标记,也正是容易被写成 O(n²) 的地方。
+/// 通道返回复用缓冲区(不分配),所以测到的就是分发成本;硬件读本身由 量。 +///
+[MemoryDiagnoser] +[SimpleJob(warmupCount: 3, iterationCount: 5)] +public class CbntFanOutBenchmarks +{ + /// 组合下的子测点数(每个 Int16 占 1 个寄存器)。 + [Params(1_000, 5_000)] + public int ChildCount { get; set; } + + private ModbusRegisterTagCbnt _cbnt = null!; + + [GlobalSetup] + public void Setup() + { + var channel = new ReusingStubChannel(); + _cbnt = new ModbusRegisterTagCbnt(new TagCbntDescriptor + { + Name = "bench", + StartAddress = "40001", + }) + { + Channel = channel, + }; + _cbnt.ResizeCache(ChildCount * sizeof(ushort)); + + for (var i = 0; i < ChildCount; i++) + { + var child = new ModbusRegisterInt16Cbntor( + new TagDescriptor { TagName = $"t{i}" }, + _cbnt, + tagOffset: i * sizeof(ushort), + isReadOnly: false); + // 组合子不会自己挂进 Children,必须显式登记(与 OpcUa 等驱动的做法一致)。 + _cbnt.Children.Add(child.TagName(), child); + } + + // 构造方式写错(子节点没挂上)会让基准变成"测一个空组合",直接失败比输出假数据好。 + if (_cbnt.Children.Count != ChildCount) + { + throw new InvalidOperationException($"预期挂上 {ChildCount} 个子测点,实际 {_cbnt.Children.Count}"); + } + } + + [Benchmark] + public Task ReadAsync() => _cbnt.ReadAsync(CancellationToken.None); + + private sealed class ReusingStubChannel : IModbusRegisterChannel { + private readonly ushort[] _buffer = new ushort[5_000]; + + public TagChannelDescriptor Descriptor { get; } = new() { Name = "bench", Driver = "ModbusTcp" }; + + public Task EnsureConnectedAsync(bool force, CancellationToken ct) => Task.CompletedTask; + + public Task DisconnectAsync(CancellationToken ct) => Task.CompletedTask; + + public void Dispose() + { + } + + public Task ReadRegistersAsync(string address, int registerCount, CancellationToken ct) + => Task.FromResult(_buffer); + + public Task WriteRegistersAsync(string address, ReadOnlyMemory registers, CancellationToken ct) => Task.CompletedTask; + } +} diff --git a/benchmarks/StdUnit.Tags.Benchmarks/MemoryFootprintReport.cs b/benchmarks/StdUnit.Tags.Benchmarks/MemoryFootprintReport.cs new file mode 100644 index 0000000..7e607bb --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/MemoryFootprintReport.cs @@ -0,0 +1,119 @@ +using System; +using StdUnit.Tags.ModbusTcp; + +namespace StdUnit.Tags.Benchmarks; + +/// +/// 常驻内存报告:点位数从 1k 增到 10k 时,对象图增长多少。
+/// 这与 `[MemoryDiagnoser]` 的 `Allocated` 是两件事:后者是"每轮产生的垃圾",前者是"进程里一直占着的东西"。 +/// BenchmarkDotNet 不测后者的差值,所以这里单独跑一遍(--footprint 模式)。
+/// 测量方式:构建对象图前后各做一次完整 GC + ,取差值。 +///
+internal static class MemoryFootprintReport +{ + private static readonly int[] TagCounts = { 1_000, 10_000, 50_000 }; + + public static void Run() + { + Console.WriteLine("常驻内存(对象图)报告 —— 构建前后各一次 full GC 后取 GC.GetTotalMemory(true) 的差值"); + Console.WriteLine(); + Console.WriteLine("| 形态 | 点位数 | 常驻增量 | 每点 |"); + Console.WriteLine("|---|---|---|---|"); + + foreach (var count in TagCounts) + { + Report("树形(10 个子组)", count, () => BuildTree(count)); + } + + foreach (var count in TagCounts) + { + Report("组合式(1 个 Cbnt + N 子测点)", count, () => BuildCbnt(count)); + } + } + + private static void Report(string shape, int count, Func build) + { + // 先 GC 一次把前面迭代的残留清掉,再取基线。 + GC.Collect(); + GC.WaitForPendingFinalizers(); + GC.Collect(); + var before = GC.GetTotalMemory(forceFullCollection: true); + + var graph = build(); + + GC.Collect(); + GC.WaitForPendingFinalizers(); + GC.Collect(); + var after = GC.GetTotalMemory(forceFullCollection: true); + + GC.KeepAlive(graph); + + var delta = after - before; + var perTag = (double)delta / count; + Console.WriteLine($"| {shape} | {count:N0} | {ToMb(delta)} | {perTag:F0} B |"); + } + + private static string ToMb(long bytes) => $"{bytes / 1024.0 / 1024.0:F2} MB"; + + private static object BuildTree(int tagCount) + { + var channel = new BenchChannel(); + var root = new TagGrp(new TagGrpDescriptor { Name = "root" }, channel); + const int groupCount = 10; + var perGroup = tagCount / groupCount; + for (var g = 0; g < groupCount; g++) + { + var group = new TagGrp(new TagGrpDescriptor { Name = $"g{g}" }, channel); + for (var i = 0; i < perGroup; i++) + { + group.AddTag(new BenchLeafTag(new TagDescriptor { TagName = $"t{i}" }, channel, group)); + } + + root.AddTag(group); + } + + return root; + } + + private static object BuildCbnt(int childCount) + { + var cbnt = new ModbusRegisterTagCbnt(new TagCbntDescriptor { Name = "bench", StartAddress = "40001" }) + { + Channel = new NullModbusChannel(), + }; + cbnt.ResizeCache(childCount * sizeof(ushort)); + + for (var i = 0; i < childCount; i++) + { + var child = new ModbusRegisterInt16Cbntor( + new TagDescriptor { TagName = $"t{i}" }, + cbnt, + tagOffset: i * sizeof(ushort), + isReadOnly: false); + cbnt.Children.Add(child.TagName(), child); + } + + return cbnt; + } + + private sealed class NullModbusChannel : IModbusRegisterChannel + { + private static readonly ushort[] Buffer = new ushort[50_000]; + + public TagChannelDescriptor Descriptor { get; } = new() { Name = "bench", Driver = "ModbusTcp" }; + + public Task EnsureConnectedAsync(bool force, System.Threading.CancellationToken ct) => System.Threading.Tasks.Task.CompletedTask; + + public Task DisconnectAsync(System.Threading.CancellationToken ct) => System.Threading.Tasks.Task.CompletedTask; + + public void Dispose() + { + } + + public Task ReadRegistersAsync(string address, int registerCount, System.Threading.CancellationToken ct) + => System.Threading.Tasks.Task.FromResult(Buffer); + + public Task WriteRegistersAsync(string address, ReadOnlyMemory registers, System.Threading.CancellationToken ct) + => System.Threading.Tasks.Task.CompletedTask; + } +} diff --git a/benchmarks/StdUnit.Tags.Benchmarks/MetricRecordingBenchmarks.cs b/benchmarks/StdUnit.Tags.Benchmarks/MetricRecordingBenchmarks.cs new file mode 100644 index 0000000..72a91e5 --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/MetricRecordingBenchmarks.cs @@ -0,0 +1,50 @@ +using System.Collections.Generic; +using System.Diagnostics.Metrics; +using BenchmarkDotNet.Attributes; + +namespace StdUnit.Tags.Benchmarks; + +/// +/// 指标记录本身的开销——验证 README 里那句"没人订阅时零分配、纳秒级"。
+/// 两个参数只差一件事:是否有人 订阅。若两者差距显著, +/// 就说明"打点"在热路径上是有代价的,设计需要重新评估。 +///
+[MemoryDiagnoser] +[SimpleJob(warmupCount: 3, iterationCount: 5)] +public class MetricRecordingBenchmarks +{ + /// true = 挂一个 MeterListener(真实采集);false = 没人订阅(默认部署形态)。 + [Params(false, true)] + public bool WithListener { get; set; } + + private KeyValuePair[] _tags = null!; + private MeterListener? _listener; + private readonly System.TimeSpan _elapsed = System.TimeSpan.FromMilliseconds(1); + + [GlobalSetup] + public void Setup() + { + _tags = new[] { new KeyValuePair(TagsMetricContract.EntryTag, "TagGrp(bench)") }; + + if (WithListener) + { + _listener = new MeterListener + { + InstrumentPublished = (instrument, l) => + { + if (instrument.Meter.Name == TagsMetricContract.MeterName) + { + l.EnableMeasurementEvents(instrument); + } + } + }; + _listener.Start(); + } + } + + [GlobalCleanup] + public void Cleanup() => _listener?.Dispose(); + + [Benchmark] + public void RecordTurn() => TagsMetric.RecordTurn(_tags, _elapsed); +} diff --git a/benchmarks/StdUnit.Tags.Benchmarks/ModbusCbntReadBenchmarks.cs b/benchmarks/StdUnit.Tags.Benchmarks/ModbusCbntReadBenchmarks.cs new file mode 100644 index 0000000..5af3ebc --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/ModbusCbntReadBenchmarks.cs @@ -0,0 +1,79 @@ +using System; +using System.Threading; +using System.Threading.Tasks; +using BenchmarkDotNet.Attributes; +using StdUnit.Tags.ModbusTcp; + +namespace StdUnit.Tags.Benchmarks; + +/// +/// Modbus 组合式测点(TagCbnt<ushort>)每轮读的分配与耗时。
+/// 它回答 backlog 里"cache 复用值不值得改公开接口":对比"通道每轮返回新数组"(现状)与 +/// "通道写入调用方预分配数组"(需要改 )。
+/// 用桩通道而不是真 socket:网络往返的噪声与分配量无关,而结论要的正是分配量。 +///
+[MemoryDiagnoser] +[SimpleJob(warmupCount: 3, iterationCount: 5)] +public class ModbusCbntReadBenchmarks +{ + /// 每次读的寄存器数(125 是 FC03/FC04 的单帧上限)。 + [Params(32, 125)] + public int RegisterCount { get; set; } + + /// true = 模拟"通道写入调用方数组"(cache 复用后的形态)。 + [Params(false, true)] + public bool ReuseCache { get; set; } + + private ModbusRegisterTagCbnt _cbnt = null!; + + [GlobalSetup] + public void Setup() + { + var channel = new StubChannel(ReuseCache); + _cbnt = new ModbusRegisterTagCbnt(new TagCbntDescriptor + { + Name = "bench", + StartAddress = "40001", + }) + { + Channel = channel, + }; + _cbnt.ResizeCache(RegisterCount * sizeof(ushort)); + } + + [Benchmark] + public Task ReadAsync() => _cbnt.ReadAsync(CancellationToken.None); + + private sealed class StubChannel : IModbusRegisterChannel + { + private readonly bool _reuse; + private readonly ushort[] _buffer = new ushort[128]; + + public StubChannel(bool reuse) => _reuse = reuse; + + public TagChannelDescriptor Descriptor { get; } = new() { Name = "bench", Driver = "ModbusTcp" }; + + public Task EnsureConnectedAsync(bool force, CancellationToken ct) => Task.CompletedTask; + + public Task DisconnectAsync(CancellationToken ct) => Task.CompletedTask; + + public void Dispose() + { + } + + public Task ReadRegistersAsync(string address, int registerCount, CancellationToken ct) + { + // 现状:每轮一个新数组(NModbus 的 ReadHoldingRegistersAsync 就是这个形状)。 + // 复用:把值写进同一块缓冲区再返回——这正是"改接口"之后能省下的那块分配。 + if (!_reuse) + { + return Task.FromResult(new ushort[registerCount]); + } + + Array.Clear(_buffer, 0, registerCount); + return Task.FromResult(_buffer); + } + + public Task WriteRegistersAsync(string address, ReadOnlyMemory registers, CancellationToken ct) => Task.CompletedTask; + } +} diff --git a/benchmarks/StdUnit.Tags.Benchmarks/Program.cs b/benchmarks/StdUnit.Tags.Benchmarks/Program.cs new file mode 100644 index 0000000..ac1cf57 --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/Program.cs @@ -0,0 +1,24 @@ +using BenchmarkDotNet.Running; + +namespace StdUnit.Tags.Benchmarks; + +/// +/// 基准入口。
+/// 本地跑:dotnet run -c Release --project benchmarks/StdUnit.Tags.Benchmarks -- --filter *
+/// 只做冒烟(每个基准执行一次,秒级):追加 --job dry。
+/// 常驻内存报告(对象图大小,BDN 不测这个):-- --footprint。
+/// 基准不进 CI 的测试步骤:完整测量需要几分钟且依赖机器状态,只作为改动前后的对比工具。 +///
+public static class Program +{ + public static void Main(string[] args) + { + if (args.Length > 0 && args[0] == "--footprint") + { + MemoryFootprintReport.Run(); + return; + } + + BenchmarkSwitcher.FromAssembly(typeof(Program).Assembly).Run(args); + } +} diff --git a/benchmarks/StdUnit.Tags.Benchmarks/S7ChannelReadBenchmarks.cs b/benchmarks/StdUnit.Tags.Benchmarks/S7ChannelReadBenchmarks.cs new file mode 100644 index 0000000..97edebf --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/S7ChannelReadBenchmarks.cs @@ -0,0 +1,49 @@ +using System; +using System.Threading; +using BenchmarkDotNet.Attributes; +using Microsoft.Extensions.Logging.Abstractions; +using StdUnit.Sharp7; +using StdUnit.Tags.S7; + +namespace StdUnit.Tags.Benchmarks; + +/// +/// S7 通道层读一块 DB 的开销(20 000 字节 ≈ 现场常见的整块采集)。
+/// 用桩 (只把数据搬进缓冲区、立即返回 0),所以测到的是我们这层的 +/// 地址解析、互斥体、Span 传递与错误码检查;真实耗时里 PLC 的响应时间占绝对多数, +/// 这组数字的用途是确认"我们不是瓶颈",以及防止将来在这条路径上引入拷贝/分配。 +///
+[MemoryDiagnoser] +[SimpleJob(warmupCount: 3, iterationCount: 5)] +public class S7ChannelReadBenchmarks +{ + /// 每次读的字节数。 + [Params(1_000, 20_000)] + public int ByteCount { get; set; } + + private S7TagChannel _channel = null!; + private byte[] _buffer = null!; + + [GlobalSetup] + public void Setup() + { + _channel = new S7TagChannel( + new S7TagChannelDescriptor { Name = "bench", IpAddr = "127.0.0.1" }, + NullLogger.Instance) + { + Client = new CopyingS7Client(), + }; + _buffer = new byte[ByteCount]; + } + + [Benchmark] + public void Read() => _channel.Read("DB1.100", _buffer, CancellationToken.None); + + /// 真实 S7Client 的替代品:只做一次内存拷贝,用来隔离"我们这层"的成本。 + private sealed class CopyingS7Client : S7Client + { + public override int DBRead(int dbNumber, int start, int size, Span buffer) => 0; + + public override int MBRead(int start, int size, Span buffer) => 0; + } +} diff --git a/benchmarks/StdUnit.Tags.Benchmarks/StdUnit.Tags.Benchmarks.csproj b/benchmarks/StdUnit.Tags.Benchmarks/StdUnit.Tags.Benchmarks.csproj new file mode 100644 index 0000000..f352083 --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/StdUnit.Tags.Benchmarks.csproj @@ -0,0 +1,25 @@ + + + + Exe + + net8.0 + + true + + $(NoWarn);CS9057 + + + + + + + + + + + \ No newline at end of file diff --git a/benchmarks/StdUnit.Tags.Benchmarks/TagTreeTraversalBenchmarks.cs b/benchmarks/StdUnit.Tags.Benchmarks/TagTreeTraversalBenchmarks.cs new file mode 100644 index 0000000..f7070d7 --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/TagTreeTraversalBenchmarks.cs @@ -0,0 +1,52 @@ +using System.Threading; +using System.Threading.Tasks; +using BenchmarkDotNet.Attributes; + +namespace StdUnit.Tags.Benchmarks; + +/// +/// "框架自身"的每轮开销:一棵 N 个测点的树,叶子全是纯内存假测点、通道也是空实现, +/// 因此测到的只有遍历、使能/脏标记判断与派发——与硬件、网络无关。
+/// 用途:给"每轮框架开销"一个数量级(例如"1 万点位的框架开销是几百 µs 还是几十 ms"), +/// 并作为回归基线;真实吞吐永远由设备与会话决定,不要用这组数字对外承诺端到端性能。 +///
+[MemoryDiagnoser] +[SimpleJob(warmupCount: 3, iterationCount: 5)] +public class TagTreeTraversalBenchmarks +{ + /// 叶子测点总数(均分到 10 个子组里)。 + [Params(1_000, 10_000)] + public int TagCount { get; set; } + + private TagGrp _root = null!; + + [GlobalSetup] + public void Setup() + { + var channel = new BenchChannel(); + _root = new TagGrp(new TagGrpDescriptor { Name = "root" }, channel); + + const int groupCount = 10; + var perGroup = TagCount / groupCount; + for (var g = 0; g < groupCount; g++) + { + var group = new TagGrp(new TagGrpDescriptor { Name = $"g{g}" }, channel); + for (var i = 0; i < perGroup; i++) + { + group.AddTag(new BenchLeafTag(new TagDescriptor { TagName = $"t{i}" }, channel, group)); + } + + _root.AddTag(group); + } + } + + /// + /// 基准框架的自身开销基线:返回已完成 Task,不做任何事。
+ /// `Allocated` 若与真实调用相同,说明那点分配来自"BDN 等待一个 Task 返回的测量装置",不是被测代码。 + ///
+ [Benchmark(Baseline = true)] + public Task NoOp() => Task.CompletedTask; + + [Benchmark] + public Task ReadAsync() => _root.ReadAsync(TraversalMode.IgnoreEnabled, CancellationToken.None); +} diff --git a/benchmarks/StdUnit.Tags.Benchmarks/TraversalBreakdownBenchmarks.cs b/benchmarks/StdUnit.Tags.Benchmarks/TraversalBreakdownBenchmarks.cs new file mode 100644 index 0000000..883de78 --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/TraversalBreakdownBenchmarks.cs @@ -0,0 +1,137 @@ +using System.Threading; +using System.Threading.Tasks; +using BenchmarkDotNet.Attributes; + +namespace StdUnit.Tags.Benchmarks; + +/// +/// 把一个"每点位 ~38 ns"拆开:纯循环 / 访问模式查询 / 同步派发 / 全部组合 / 真实的 TagUnion 异步遍历。
+/// 目的是回答"瓶颈在哪"——不是猜,而是逐层加回成本,看每层增加多少 ns。
+/// 全部用扁平数组(10 000 个叶子),避免树形与字典开销混进来;叶子是纯内存假测点。 +///
+[MemoryDiagnoser] +[SimpleJob(warmupCount: 3, iterationCount: 5)] +public class TraversalBreakdownBenchmarks +{ + private const int NodeCount = 10_000; + + private ITag[] _tags = null!; + private TagUnion[] _unions = null!; + + [GlobalSetup] + public void Setup() + { + var channel = new BenchChannel(); + var root = new TagGrp(new TagGrpDescriptor { Name = "root" }, channel); + _tags = new ITag[NodeCount]; + _unions = new TagUnion[NodeCount]; + for (var i = 0; i < NodeCount; i++) + { + var tag = new BenchLeafTag(new TagDescriptor { TagName = $"t{i}" }, channel, root); + _tags[i] = tag; + _unions[i] = new TagUnion.TagUnit(tag); + } + } + + /// 基线:数组遍历本身(+ 一次空判断),不含任何框架调用。 + [Benchmark(Baseline = true)] + public int Loop_Only() + { + var n = 0; + foreach (var t in _tags) + { + if (t is not null) + { + n++; + } + } + + return n; + } + + /// 只加"访问模式解析"(每次读要做两次:R1W 判定 + IsWriteOnly)。 + [Benchmark] + public int SearchAccessMode_Only() + { + var n = 0; + foreach (var t in _tags) + { + n += (int)t.SearchAccessMode(); + } + + return n; + } + + /// 只加"派发 + 完成检查"(理想快路径:同步完成时不进 async 机制)。 + [Benchmark] + public int SyncDispatch_Only() + { + var n = 0; + foreach (var t in _tags) + { + if (t.ReadAsync(CancellationToken.None).IsCompletedSuccessfully) + { + n++; + } + } + + return n; + } + + /// 把上面几层按真实顺序组合起来——这就是"最优实现"能到的上界。 + [Benchmark] + public int SyncDispatch_WithPolicy() + { + var n = 0; + foreach (var t in _tags) + { + var mode = t.SearchAccessMode(); + if (mode == TagAccessMode.R1W && t.IsScanned) + { + continue; + } + + if (mode == TagAccessMode.WO) + { + continue; + } + + if (t.ReadAsync(CancellationToken.None).IsCompletedSuccessfully) + { + t.IsScanned = true; + n++; + } + } + + return n; + } + + /// 现状:走 的异步遍历(每个节点一次 async 包装 + switch)。 + [Benchmark] + public async Task UnionReadAsync() + { + foreach (var union in _unions) + { + await union.ReadAsync(TraversalMode.IgnoreEnabled, CancellationToken.None).ConfigureAwait(false); + } + } + + /// + /// 每轮开头运行器还会调一次 entry.IsDirty():全树干净时要走完所有子节点。 + /// 这是"每轮固定成本"里除读之外的另一大块,所以单独量。 + /// + [Benchmark] + public int IsDirty_All() + { + var n = 0; + foreach (var union in _unions) + { + if (union.IsDirty()) + { + n++; + } + } + + return n; + } +} diff --git a/benchmarks/StdUnit.Tags.Benchmarks/paket.references b/benchmarks/StdUnit.Tags.Benchmarks/paket.references new file mode 100644 index 0000000..7fbc6e7 --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/paket.references @@ -0,0 +1,2 @@ +group Benchmarks + BenchmarkDotNet \ No newline at end of file diff --git a/paket.dependencies b/paket.dependencies index d0cffb8..77d68a9 100644 --- a/paket.dependencies +++ b/paket.dependencies @@ -90,3 +90,16 @@ group SchemaGenerator # 用独立 group 隔离,避免主 group 的 Microsoft.CodeAnalysis.CSharp.Scripting >= 5.0(ComScanner 用)拉高版本。 nuget Microsoft.CodeAnalysis.CSharp >= 4.8 lowest_matching: true +group Benchmarks + # 只给 benchmarks/ 用:BenchmarkDotNet 是开发期工具,绝不应出现在任何发布包的依赖里。 + source https://api.nuget.org/v3/index.json + source https://baget.stdunit.com/v3/index.json + + cache ./nuget-package-caches + storage: none + # strategy: min 与 Main 组一致:否则传递依赖会解析到最新的 Azure.Core / Microsoft.Extensions 11.x, + # 在 net8.0 基准工程里刷出一堆"不支持当前 TFM"的警告。 + strategy: min + framework: net8.0 + + nuget BenchmarkDotNet >= 0.15.8 lowest_matching: true \ No newline at end of file diff --git a/paket.lock b/paket.lock index 02ec515..e36dcb7 100644 --- a/paket.lock +++ b/paket.lock @@ -737,6 +737,181 @@ NUGET xunit.runner.visualstudio (2.5.3) Microsoft.TestPlatform.ObjectModel (>= 17.7.2) - restriction: || (== net472) (&& (== net8.0) (>= net462)) (&& (== net8.0-windows7.0) (>= net462)) (&& (== netstandard2.0) (>= net462)) +GROUP Benchmarks +STORAGE: NONE +STRATEGY: MIN +RESTRICTION: == net8.0 +NUGET + remote: https://api.nuget.org/v3/index.json + Azure.Core (1.65) + Microsoft.Bcl.AsyncInterfaces (>= 10.0.10) + Microsoft.Extensions.Configuration.Abstractions (>= 10.0.10) + Microsoft.Extensions.Hosting.Abstractions (>= 10.0.10) + Microsoft.Identity.Client (>= 4.92) + Microsoft.Identity.Client.Extensions.Msal (>= 4.92) + System.ClientModel (>= 1.17) + System.Diagnostics.DiagnosticSource (>= 10.0.10) + System.Memory.Data (>= 10.0.10) + System.Text.Encodings.Web (>= 10.0.10) + System.Text.Json (>= 10.0.10) + Azure.Identity (1.21) + Azure.Core (>= 1.53) + BenchmarkDotNet (0.15.8) + BenchmarkDotNet.Annotations (>= 0.15.8) + CommandLineParser (>= 2.9.1) + Gee.External.Capstone (>= 2.3) + Iced (>= 1.21) + Microsoft.CodeAnalysis.CSharp (>= 4.14) + Microsoft.Diagnostics.Runtime (>= 3.1.512801) + Microsoft.Diagnostics.Tracing.TraceEvent (>= 3.1.21) + Microsoft.DotNet.PlatformAbstractions (>= 3.1.6) + Perfolizer (0.6.1) + System.Management (>= 9.0.5) + BenchmarkDotNet.Annotations (0.15.8) + CommandLineParser (2.9.1) + Gee.External.Capstone (2.3) + Iced (1.22) + Microsoft.Bcl.AsyncInterfaces (11.0) + Microsoft.CodeAnalysis.Analyzers (5.9) + Microsoft.CodeAnalysis.Common (5.9) + Microsoft.CodeAnalysis.Analyzers (>= 5.9.0-1.26328.17) + System.Buffers (>= 4.6.1) + System.Collections.Immutable (>= 10.0.1) + System.Memory (>= 4.6.3) + System.Numerics.Vectors (>= 4.6.1) + System.Reflection.Metadata (>= 10.0.1) + System.Runtime.CompilerServices.Unsafe (>= 6.1.2) + System.Text.Encoding.CodePages (>= 8.0) + System.Threading.Tasks.Extensions (>= 4.6.3) + Microsoft.CodeAnalysis.CSharp (5.9) + Microsoft.CodeAnalysis.Analyzers (>= 5.9.0-1.26328.17) + Microsoft.CodeAnalysis.Common (5.9) + System.Buffers (>= 4.6.1) + System.Collections.Immutable (>= 10.0.1) + System.Memory (>= 4.6.3) + System.Numerics.Vectors (>= 4.6.1) + System.Reflection.Metadata (>= 10.0.1) + System.Runtime.CompilerServices.Unsafe (>= 6.1.2) + System.Text.Encoding.CodePages (>= 8.0) + System.Threading.Tasks.Extensions (>= 4.6.3) + Microsoft.Diagnostics.NETCore.Client (0.2.750501) + Microsoft.Extensions.Logging.Abstractions (>= 8.0.3) + Microsoft.Diagnostics.Runtime (4.2.751201) + Azure.Identity (>= 1.21) + Microsoft.Diagnostics.NETCore.Client (>= 0.2.661903) + Microsoft.Security.AntiSSRF (>= 1.0) + System.Collections.Immutable (>= 10.0.7) + System.Runtime.CompilerServices.Unsafe (>= 6.1.2) + Microsoft.Diagnostics.Tracing.TraceEvent (4.0) + Microsoft.Diagnostics.NETCore.Client (>= 0.2.661903) + Microsoft.Win32.Registry (>= 5.0) + System.Collections.Immutable (>= 10.0.7) + System.Reflection.Metadata (>= 9.0.8) + System.Reflection.TypeExtensions (>= 4.7) + System.Runtime.CompilerServices.Unsafe (>= 6.1.2) + System.Text.Json (>= 10.0.3) + Microsoft.DotNet.PlatformAbstractions (3.1.6) + Microsoft.Extensions.Configuration.Abstractions (11.0) + Microsoft.Extensions.Primitives (>= 11.0) + Microsoft.Extensions.DependencyInjection.Abstractions (11.0) + Microsoft.Extensions.Diagnostics.Abstractions (11.0) + Microsoft.Extensions.DependencyInjection.Abstractions (>= 11.0) + Microsoft.Extensions.Options (>= 11.0) + System.Buffers (>= 4.6.1) + System.Diagnostics.DiagnosticSource (>= 11.0) + System.Memory (>= 4.6.3) + Microsoft.Extensions.FileProviders.Abstractions (11.0) + Microsoft.Extensions.Primitives (>= 11.0) + Microsoft.Extensions.Hosting.Abstractions (11.0) + Microsoft.Extensions.Configuration.Abstractions (>= 11.0) + Microsoft.Extensions.DependencyInjection.Abstractions (>= 11.0) + Microsoft.Extensions.Diagnostics.Abstractions (>= 11.0) + Microsoft.Extensions.FileProviders.Abstractions (>= 11.0) + Microsoft.Extensions.Logging.Abstractions (>= 11.0) + Microsoft.Extensions.Logging.Abstractions (11.0) + Microsoft.Extensions.DependencyInjection.Abstractions (>= 11.0) + System.Buffers (>= 4.6.1) + System.Diagnostics.DiagnosticSource (>= 11.0) + System.Memory (>= 4.6.3) + Microsoft.Extensions.Options (11.0) + Microsoft.Extensions.DependencyInjection.Abstractions (>= 11.0) + Microsoft.Extensions.Primitives (>= 11.0) + System.ComponentModel.Annotations (>= 5.0) + Microsoft.Extensions.Primitives (11.0) + System.Memory (>= 4.6.3) + System.Runtime.CompilerServices.Unsafe (>= 6.1.2) + Microsoft.Identity.Client (4.92) + Microsoft.IdentityModel.Abstractions (>= 8.14) + System.Diagnostics.DiagnosticSource (>= 6.0.1) + Microsoft.Identity.Client.Extensions.Msal (4.92) + Microsoft.Identity.Client (>= 4.92) + System.Security.Cryptography.ProtectedData (>= 4.5) + Microsoft.IdentityModel.Abstractions (8.23) + Microsoft.Security.AntiSSRF (1.0.1) + Microsoft.Win32.Registry (5.0) + System.Security.AccessControl (>= 5.0) + System.Security.Principal.Windows (>= 5.0) + Perfolizer (0.6.1) + Pragmastat (>= 3.2.4) + Pragmastat (3.2.4) + System.Buffers (4.6.1) + System.ClientModel (1.17) + Microsoft.Extensions.Configuration.Abstractions (>= 10.0.10) + Microsoft.Extensions.Hosting.Abstractions (>= 10.0.10) + Microsoft.Extensions.Logging.Abstractions (>= 10.0.10) + System.Diagnostics.DiagnosticSource (>= 10.0.10) + System.Memory.Data (>= 10.0.10) + System.Net.ServerSentEvents (>= 10.0.10) + System.Text.Json (>= 10.0.10) + System.CodeDom (11.0) + System.Memory (>= 4.6.3) + System.Collections.Immutable (11.0) + System.Memory (>= 4.6.3) + System.Runtime.CompilerServices.Unsafe (>= 6.1.2) + System.ComponentModel.Annotations (5.0) + System.Diagnostics.DiagnosticSource (11.0) + System.Memory (>= 4.6.3) + System.Runtime.CompilerServices.Unsafe (>= 6.1.2) + System.IO.Pipelines (11.0) + System.Buffers (>= 4.6.1) + System.Memory (>= 4.6.3) + System.Threading.Tasks.Extensions (>= 4.6.3) + System.Management (11.0) + System.CodeDom (>= 11.0) + System.Memory (4.6.3) + System.Memory.Data (11.0) + System.Memory (>= 4.6.3) + System.Text.Json (>= 11.0) + System.Net.ServerSentEvents (11.0) + Microsoft.Bcl.AsyncInterfaces (>= 11.0) + System.Memory (>= 4.6.3) + System.Threading.Tasks.Extensions (>= 4.6.3) + System.Numerics.Vectors (4.6.1) + System.Reflection.Metadata (11.0) + System.Collections.Immutable (>= 11.0) + System.Reflection.TypeExtensions (4.7) + System.Runtime.CompilerServices.Unsafe (6.1.2) + System.Security.AccessControl (6.0.1) + System.Security.Cryptography.ProtectedData (11.0) + System.Memory (>= 4.6.3) + System.Security.Principal.Windows (5.0) + System.Text.Encoding.CodePages (11.0) + System.Memory (>= 4.6.3) + System.Runtime.CompilerServices.Unsafe (>= 6.1.2) + System.Text.Encodings.Web (11.0) + System.Buffers (>= 4.6.1) + System.Memory (>= 4.6.3) + System.Runtime.CompilerServices.Unsafe (>= 6.1.2) + System.Text.Json (11.0) + Microsoft.Bcl.AsyncInterfaces (>= 11.0) + System.Buffers (>= 4.6.1) + System.IO.Pipelines (>= 11.0) + System.Memory (>= 4.6.3) + System.Runtime.CompilerServices.Unsafe (>= 6.1.2) + System.Text.Encodings.Web (>= 11.0) + System.Threading.Tasks.Extensions (>= 4.6.3) + System.Threading.Tasks.Extensions (4.6.3) + GROUP Mcp STORAGE: NONE STRATEGY: MIN diff --git a/src/StdUnit.Tags.Core/TagCbnts/ITagCbntExtensions.cs b/src/StdUnit.Tags.Core/TagCbnts/ITagCbntExtensions.cs index d6e8cd8..9154204 100644 --- a/src/StdUnit.Tags.Core/TagCbnts/ITagCbntExtensions.cs +++ b/src/StdUnit.Tags.Core/TagCbnts/ITagCbntExtensions.cs @@ -34,13 +34,13 @@ public static class ITagCbntExtensions public static ITagChannel SearchRequiredChannel(this ITagCbnt tagcbnt) => tagcbnt.SearchChannel() ?? throw new InvalidOperationException($"Channel is not configured : TagCbnt({tagcbnt.TagName()})"); /// - /// 获取解析后的访问模式。
- /// 如果自身和父级均未配置,则默认返回 。 + /// 获取解析后的访问模式(逐级冒泡:自身 → 父级 Cbnt → 各级 Grp)。
+ /// 如果自身和所有祖先均未配置,则默认返回 。 ///
/// /// public static TagAccessMode SearchAccessMode(this ITagCbnt tagcbnt) - => tagcbnt.Descriptor.AccessMode ?? tagcbnt.Parent?.Descriptor.AccessMode ?? TagAccessMode.RW; + => tagcbnt.Descriptor.AccessMode ?? tagcbnt.Parent?.SearchAccessMode() ?? TagAccessMode.RW; /// /// 只读? diff --git a/src/StdUnit.Tags.Core/TagContainers/TagContainer.cs b/src/StdUnit.Tags.Core/TagContainers/TagContainer.cs index d9cb387..5f7591d 100644 --- a/src/StdUnit.Tags.Core/TagContainers/TagContainer.cs +++ b/src/StdUnit.Tags.Core/TagContainers/TagContainer.cs @@ -11,9 +11,11 @@ public abstract record TagContainer /// private TagContainer() { } - private sealed record TagCbnt(ITagCbnt Value) : TagContainer(); + // 子类型对同程序集可见(而不是 private):让 TagContainerExtensions.SearchAccessMode 能用 switch 匹配, + // 从而避免 Map + 委托。外部仍然无法扩展——构造函数是私有的。 + internal sealed record TagCbnt(ITagCbnt Value) : TagContainer(); - private sealed record TagGrp(ITagGrp Value) : TagContainer(); + internal sealed record TagGrp(ITagGrp Value) : TagContainer(); /// /// 工厂函数 diff --git a/src/StdUnit.Tags.Core/TagContainers/TagContainerExtensions.cs b/src/StdUnit.Tags.Core/TagContainers/TagContainerExtensions.cs index 66c4250..34beeea 100644 --- a/src/StdUnit.Tags.Core/TagContainers/TagContainerExtensions.cs +++ b/src/StdUnit.Tags.Core/TagContainers/TagContainerExtensions.cs @@ -5,6 +5,19 @@ /// public static class TagContainerExtensions { + /// + /// (冒泡式)获取访问模式(逐级冒泡:容器自身 → 各级祖先 → 默认 )。
+ /// 与 同族:由容器节点继续向上追溯,而不是只看直接父级。 + ///
+ /// + /// + public static TagAccessMode SearchAccessMode(this TagContainer tagContainer) => tagContainer switch + { + TagContainer.TagCbnt cbnt => cbnt.Value.SearchAccessMode(), + TagContainer.TagGrp grp => grp.Value.SearchAccessMode(), + _ => throw new NotImplementedException($"未预料到的{nameof(TagContainer)}子类型: {tagContainer.GetType()}") + }; + /// /// (冒泡式)获取 。
/// 如果没有找到,返回 null。
diff --git a/src/StdUnit.Tags.Core/TagGrps/TagGrp.cs b/src/StdUnit.Tags.Core/TagGrps/TagGrp.cs index dae2215..07ae553 100644 --- a/src/StdUnit.Tags.Core/TagGrps/TagGrp.cs +++ b/src/StdUnit.Tags.Core/TagGrps/TagGrp.cs @@ -32,7 +32,11 @@ public TagGrp(TagGrpDescriptor descriptor, ITagChannel? channel) #region 子节点 /// - public IDictionary Children { get; } = new Dictionary(); + public IDictionary Children => _children; + + // 存具体类型:公开属性是 IDictionary(API 不变),但遍历时走具体类型的结构体枚举器。 + // 走接口 foreach 会装箱 Dictionary.Enumerator(每次遍历一个分配),而这发生在每一轮的读/写/判脏路径上。 + private readonly Dictionary _children = new(); /// /// 指定的子测点名不存在 @@ -131,7 +135,7 @@ public async Task ReadAsync(TraversalMode mode, CancellationToken ct) return; } - foreach (var kvp in Children) + foreach (var kvp in _children) { var tagunion = kvp.Value; await tagunion.ReadAsync(mode, ct); @@ -147,7 +151,7 @@ public async Task WriteAsync(TraversalMode mode, CancellationToken ct) return; } - foreach (var kvp in Children) + foreach (var kvp in _children) { var tagunion = kvp.Value; await tagunion.WriteAsync(mode, ct); @@ -157,7 +161,7 @@ public async Task WriteAsync(TraversalMode mode, CancellationToken ct) /// public bool IsDirty() { - foreach (var kvp in Children) + foreach (var kvp in _children) { var child = kvp.Value; if (child.IsDirty()) diff --git a/src/StdUnit.Tags.Core/TagUnions/TagUnion.cs b/src/StdUnit.Tags.Core/TagUnions/TagUnion.cs index 793ca91..2d66a83 100644 --- a/src/StdUnit.Tags.Core/TagUnions/TagUnion.cs +++ b/src/StdUnit.Tags.Core/TagUnions/TagUnion.cs @@ -7,6 +7,13 @@ ///
public abstract record TagUnion { + /// + /// 运行期缓存:解析后的访问模式()。
+ /// 访问模式是配置期属性——加载完成后再改 Descriptor.AccessMode 不会反映到这里, + /// 需要重新加载项目。正因为它是配置期的,缓存才是安全的;命中时省掉逐级冒泡的接口跳转。 + ///
+ internal TagAccessMode? CachedAccessMode; + /// /// 接收一个访问者 /// diff --git a/src/StdUnit.Tags.Core/TagUnions/TagUnionExtensions.cs b/src/StdUnit.Tags.Core/TagUnions/TagUnionExtensions.cs index 0f851fa..b2801f0 100644 --- a/src/StdUnit.Tags.Core/TagUnions/TagUnionExtensions.cs +++ b/src/StdUnit.Tags.Core/TagUnions/TagUnionExtensions.cs @@ -1,4 +1,4 @@ -namespace StdUnit.Tags; +namespace StdUnit.Tags; /// /// extensions for @@ -24,45 +24,80 @@ public static Task ReadAsync(this TagUnion tagunion, CancellationToken ct) => /// 遍历模式 /// /// - public static async Task ReadAsync(this TagUnion tagunion, TraversalMode mode, CancellationToken ct) + public static Task ReadAsync(this TagUnion tagunion, TraversalMode mode, CancellationToken ct) { - await tagunion.Map( - async tag => + // 不要改回 TagUnion.Map:每个分支都会构造闭包 + 委托 + 异步状态机(分配)。 + // 另外这里**不是** async 方法:常见路径(读同步完成)直接返回已完成 Task; + // 只有真正异步(设备 I/O)时才走下面的两个辅助方法。 + switch (tagunion) + { + case TagUnion.TagUnit unit: { - if (tag.SearchAccessMode() == TagAccessMode.R1W && tag.IsScanned) + var tag = unit.Value; + var access = tagunion.CachedAccessMode ??= tag.SearchAccessMode(); + if (access == TagAccessMode.R1W && tag.IsScanned) { - return; + return Task.CompletedTask; } - if (tag.IsWriteOnly()) + if (access == TagAccessMode.WO) { - return; + return Task.CompletedTask; } - await tag.ReadAsync(ct); - tag.IsScanned = true; - }, - async cbnt => + + var task = tag.ReadAsync(ct); + if (task.Status == TaskStatus.RanToCompletion) + { + tag.IsScanned = true; + return Task.CompletedTask; + } + + return MarkScannedAfterReadAsync(tag, task); + } + case TagUnion.TagCbnt cbntUnion: { + var cbnt = cbntUnion.Value; // 是否短路? if (mode == TraversalMode.RespectEnabled && !cbnt.IsEnabled) { - return; + return Task.CompletedTask; } - if (cbnt.SearchAccessMode() == TagAccessMode.R1W && cbnt.IsScanned) + + var access = tagunion.CachedAccessMode ??= cbnt.SearchAccessMode(); + if (access == TagAccessMode.R1W && cbnt.IsScanned) { - return; + return Task.CompletedTask; } - if (cbnt.IsWriteOnly()) + if (access == TagAccessMode.WO) { - return; + return Task.CompletedTask; } - await cbnt.ReadAsync(ct); - cbnt.IsScanned = true; - }, - async grp => - { - await grp.ReadAsync(mode, ct); + + var task = cbnt.ReadAsync(ct); + if (task.Status == TaskStatus.RanToCompletion) + { + cbnt.IsScanned = true; + return Task.CompletedTask; + } + + return MarkScannedAfterReadAsync(cbnt, task); } - ); + case TagUnion.TagGrp grpUnion: + return grpUnion.Value.ReadAsync(mode, ct); + default: + return Task.FromException(new NotImplementedException($"unknown types: {tagunion.GetType()}")); + } + } + + private static async Task MarkScannedAfterReadAsync(ITag tag, Task readTask) + { + await readTask.ConfigureAwait(false); + tag.IsScanned = true; + } + + private static async Task MarkScannedAfterReadAsync(ITagCbnt cbnt, Task readTask) + { + await readTask.ConfigureAwait(false); + cbnt.IsScanned = true; } /// @@ -82,42 +117,45 @@ await tagunion.Map( /// 遍历模式 /// /// - public static async Task WriteAsync(this TagUnion tagunion, TraversalMode mode, CancellationToken ct) + public static Task WriteAsync(this TagUnion tagunion, TraversalMode mode, CancellationToken ct) { - await tagunion.Map( - async tag => + // 同 ReadAsync:用 switch 而非 Map,避免逐节点构造闭包/委托/状态机; + // 且本方法无需"读后再标记",所以完全不需要 async——直接把子任务的 Task 返回即可。 + switch (tagunion) + { + case TagUnion.TagUnit unit: { - if (tag.IsReadOnly()) + var tag = unit.Value; + var access = tagunion.CachedAccessMode ??= tag.SearchAccessMode(); + if (access == TagAccessMode.RO || !tag.IsDirty) { - return; + return Task.CompletedTask; } - if (tag.IsDirty) - { - await tag.WriteAsync(ct); - } - }, - async cbnt => + + return tag.WriteAsync(ct); + } + case TagUnion.TagCbnt cbntUnion: { + var cbnt = cbntUnion.Value; // 使能门控:未使能的组合整块跳过(含其下的所有测点),其脏标记会被保留到重新使能后再刷写 if (mode == TraversalMode.RespectEnabled && !cbnt.IsEnabled) { - return; - } - if (cbnt.IsReadOnly()) - { - return; + return Task.CompletedTask; } - if (cbnt.IsDirty) + var access = tagunion.CachedAccessMode ??= cbnt.SearchAccessMode(); + if (access == TagAccessMode.RO || !cbnt.IsDirty) { - await cbnt.WriteAsync(ct); + return Task.CompletedTask; } - }, - async grp => - { - await grp.WriteAsync(mode, ct); + + return cbnt.WriteAsync(ct); } - ); + case TagUnion.TagGrp grpUnion: + return grpUnion.Value.WriteAsync(mode, ct); + default: + return Task.FromException(new NotImplementedException($"unknown types: {tagunion.GetType()}")); + } } /// @@ -125,14 +163,13 @@ await tagunion.Map( /// /// /// - public static bool IsDirty(this TagUnion tagunion) + public static bool IsDirty(this TagUnion tagunion) => tagunion switch { - return tagunion.Map( - tag => tag.IsDirty, - cbnt => cbnt.IsDirty, - grp => grp.IsDirty() - ); - } + TagUnion.TagUnit unit => unit.Value.IsDirty, + TagUnion.TagCbnt cbnt => cbnt.Value.IsDirty, + TagUnion.TagGrp grp => grp.Value.IsDirty(), + _ => throw new NotImplementedException($"unknown types: {tagunion.GetType()}") + }; #endregion diff --git a/src/StdUnit.Tags.Core/Tags/ITagExtensions.cs b/src/StdUnit.Tags.Core/Tags/ITagExtensions.cs index 3b61683..ea29142 100644 --- a/src/StdUnit.Tags.Core/Tags/ITagExtensions.cs +++ b/src/StdUnit.Tags.Core/Tags/ITagExtensions.cs @@ -61,18 +61,13 @@ public static class ITagExtensions /// public static TagAccessMode SearchAccessMode(this ITag tag) { - if (tag.TagDescriptor.AccessMode.HasValue) - return tag.TagDescriptor.AccessMode.Value; - - if (tag.Parent is not null) + if (tag.TagDescriptor.AccessMode is { } configured) { - return tag.Parent.Map( - cbnt => cbnt.Descriptor.AccessMode, - grp => grp.Descriptor.AccessMode - ) ?? TagAccessMode.RW; + return configured; } - return TagAccessMode.RW; + // 父容器解析(本身即逐级冒泡) + return tag.Parent?.SearchAccessMode() ?? TagAccessMode.RW; } /// diff --git a/src/StdUnit.Tags.Core/attribs.cs b/src/StdUnit.Tags.Core/attribs.cs index 7a7e07b..1014314 100644 --- a/src/StdUnit.Tags.Core/attribs.cs +++ b/src/StdUnit.Tags.Core/attribs.cs @@ -1,3 +1,4 @@ - + using System.Runtime.CompilerServices; [assembly: InternalsVisibleTo("StdUnit.Tags.Tests")] +[assembly: InternalsVisibleTo("StdUnit.Tags.Benchmarks")] diff --git a/src/StdUnit.Tags.ModbusTcp/attribs.cs b/src/StdUnit.Tags.ModbusTcp/attribs.cs index f557330..50d12dc 100644 --- a/src/StdUnit.Tags.ModbusTcp/attribs.cs +++ b/src/StdUnit.Tags.ModbusTcp/attribs.cs @@ -1,6 +1,7 @@ - + using System.Runtime.CompilerServices; [assembly: InternalsVisibleTo("StdUnit.Tags.Tests")] +[assembly: InternalsVisibleTo("StdUnit.Tags.Benchmarks")] [assembly: InternalsVisibleTo("StdUnit.Tags.Hjzk")] [assembly: InternalsVisibleTo("StdUnit.Tags.ZLan")] diff --git a/src/StdUnit.Tags.S7/S7Address.cs b/src/StdUnit.Tags.S7/S7Address.cs index 9f406be..a357aec 100644 --- a/src/StdUnit.Tags.S7/S7Address.cs +++ b/src/StdUnit.Tags.S7/S7Address.cs @@ -114,6 +114,11 @@ public string Format() /// public static class S7AddressParser { + // 正则构造有可观开销,而解析发生在每一轮读写路径上,所以提升为静态只读(不可变、线程安全)。 + // 不可变、线程安全,提升为静态只读;匹配语义与逐次构造完全一致。 + private static readonly Regex DbWithNthBitPattern = new(@"DB(?[0-9]+)\.(?[0-9]+)\.(?[0-9]+)$"); + private static readonly Regex DbWithoutNthBitPattern = new(@"DB(?[0-9]+)\.(?[0-9]+)$"); + /// /// 把地址字符串解析成 /// @@ -159,8 +164,7 @@ public static S7Address Parse(string addr) private static FSharpResult ParseDBAddressWithNthBit(string addr) { - var regex = new Regex(@"DB(?[0-9]+)\.(?[0-9]+)\.(?[0-9]+)$"); - var match = regex.Match(addr); + var match = DbWithNthBitPattern.Match(addr); if (!match.Success) { return $"未能匹配模式 DB..的模式".ToErrResult(); @@ -200,8 +204,7 @@ private static FSharpResult ParseDBAddressWithNthBit(string a private static FSharpResult ParseDBAddressWithoutNthBit(string addr) { - var regex = new Regex(@"DB(?[0-9]+)\.(?[0-9]+)$"); - var match = regex.Match(addr); + var match = DbWithoutNthBitPattern.Match(addr); if (!match.Success) { return $"未能匹配模式 DB.的模式".ToErrResult(); diff --git a/src/StdUnit.Tags.S7/attribs.cs b/src/StdUnit.Tags.S7/attribs.cs index 6cc778d..6ce6cae 100644 --- a/src/StdUnit.Tags.S7/attribs.cs +++ b/src/StdUnit.Tags.S7/attribs.cs @@ -1,4 +1,5 @@ - + using System.Runtime.CompilerServices; [assembly: InternalsVisibleTo("StdUnit.Tags.Tests")] +[assembly: InternalsVisibleTo("StdUnit.Tags.Benchmarks")] diff --git a/src/StdUnit.Tags/TagCbnt.cs b/src/StdUnit.Tags/TagCbnt.cs index 03e6823..856cee8 100644 --- a/src/StdUnit.Tags/TagCbnt.cs +++ b/src/StdUnit.Tags/TagCbnt.cs @@ -68,7 +68,11 @@ public void ResizeCache(int cacheSize) #region 子节点 /// - public IDictionary Children { get; } = new Dictionary(); + public IDictionary Children => _children; + + // 同 TagGrp:公开属性保持 IDictionary(API 不变),但遍历走具体类型的结构体枚举器, + // 避免每次 NotifyChildrenRead/Write 都装箱一个 Dictionary.Enumerator。 + private readonly Dictionary _children = new(); /// public ITagCbntor this[string tagName] => this.Children.TryGetValue(tagName, out var tag) ? @@ -93,7 +97,7 @@ public void ResizeCache(int cacheSize) /// protected void NotifyChildrenRead() { - foreach (var kv in this.Children) + foreach (var kv in _children) { kv.Value.NotifyTagRead(); } @@ -104,7 +108,7 @@ protected void NotifyChildrenRead() /// protected void NotifyChildrenWritten() { - foreach (var kv in this.Children) + foreach (var kv in _children) { kv.Value.NotifyTagWritten(); kv.Value.IsDirty = false; diff --git a/src/StdUnit.Tags/attribs.cs b/src/StdUnit.Tags/attribs.cs index 682232a..520fbc5 100644 --- a/src/StdUnit.Tags/attribs.cs +++ b/src/StdUnit.Tags/attribs.cs @@ -1,7 +1,8 @@ - + using System.Runtime.CompilerServices; [assembly: InternalsVisibleTo("StdUnit.Tags.S7")] [assembly: InternalsVisibleTo("StdUnit.Tags.ModbusTcp")] [assembly: InternalsVisibleTo("StdUnit.Tags.Tests")] +[assembly: InternalsVisibleTo("StdUnit.Tags.Benchmarks")] diff --git a/tests/StdUnit.Tags.Tests/Core/AccessModeInheritanceTests.cs b/tests/StdUnit.Tags.Tests/Core/AccessModeInheritanceTests.cs new file mode 100644 index 0000000..f049750 --- /dev/null +++ b/tests/StdUnit.Tags.Tests/Core/AccessModeInheritanceTests.cs @@ -0,0 +1,117 @@ +using System.Threading; +using System.Threading.Tasks; +using StdUnit.Tags.Tests.Fakes; +using Xunit; + +namespace StdUnit.Tags.Tests.Core; + +/// +/// 访问模式(access)的继承语义:**逐级冒泡**——自身 → 父级 Cbnt → 各级 Grp → 默认 RW。
+/// 历史上 / 只查"直接父级自己配了没", +/// 于是 `Grp(RO) → Cbnt(未配) → Tag` 会被误判成 RW(而 `Grp(RO) → Tag` 却是 RO)。2.0 统一为逐级冒泡。 +///
+public class AccessModeInheritanceTests +{ + private static TagGrp NewGroup(string name, TagAccessMode? access = null) + => new(new TagGrpDescriptor { Name = name, AccessMode = access }, new FakedChannel(new TagChannelDescriptor { Name = "ch" })); + + private static FakedTagCbnt NewCbnt(string name, TagAccessMode? access = null) + => new(new TagCbntDescriptor { Name = name, AccessMode = access }); + + private static FakedTag NewTag(string name, ITagGrp parent, TagAccessMode? access = null) + => new(new TagDescriptor { TagName = name, AccessMode = access }, new FakedChannel(new TagChannelDescriptor { Name = "ch" }), parent); + + [Fact] + public void Tag_WithNothingConfigured_DefaultsToRW() + { + var grp = NewGroup("g"); + var tag = NewTag("t", grp); + grp.AddTag(tag); + + Assert.Equal(TagAccessMode.RW, tag.SearchAccessMode()); + } + + [Fact] + public void Tag_InheritsFromDirectParentGroup() + { + var grp = NewGroup("g", TagAccessMode.RO); + var tag = NewTag("t", grp); + grp.AddTag(tag); + + Assert.Equal(TagAccessMode.RO, tag.SearchAccessMode()); + } + + /// 核心回归:隔一层未配置的 Cbnt,也必须继承到祖先 Grp 的配置。 + [Fact] + public void Tag_InheritsThroughUnconfiguredCbntFromGrandparentGroup() + { + var grp = NewGroup("g", TagAccessMode.RO); + var cbnt = NewCbnt("c"); // 未配置 access + grp.AddTag(cbnt); + + var tag = NewTag("t", grp); + tag.Parent = TagContainer.From(cbnt); // 父容器是 Cbnt + + Assert.Equal(TagAccessMode.RO, cbnt.SearchAccessMode()); + Assert.Equal(TagAccessMode.RO, tag.SearchAccessMode()); + } + + [Fact] + public void Cbnt_OverridesAncestor() + { + var grp = NewGroup("g", TagAccessMode.RO); + var cbnt = NewCbnt("c", TagAccessMode.WO); + grp.AddTag(cbnt); + + var tag = NewTag("t", grp); + tag.Parent = TagContainer.From(cbnt); + + Assert.Equal(TagAccessMode.WO, cbnt.SearchAccessMode()); + Assert.Equal(TagAccessMode.WO, tag.SearchAccessMode()); + } + + [Fact] + public void Tag_OverridesAllAncestors() + { + var grp = NewGroup("g", TagAccessMode.RO); + var cbnt = NewCbnt("c", TagAccessMode.WO); + grp.AddTag(cbnt); + + var tag = NewTag("t", grp, TagAccessMode.R1W); + tag.Parent = TagContainer.From(cbnt); + + Assert.Equal(TagAccessMode.R1W, tag.SearchAccessMode()); + } + + [Fact] + public void Tag_InheritsThroughNestedGroups() + { + var outer = NewGroup("outer", TagAccessMode.RO); + var inner = NewGroup("inner"); // 未配置 + outer.AddTag(inner); + + var tag = NewTag("t", inner); + inner.AddTag(tag); + + Assert.Equal(TagAccessMode.RO, inner.SearchAccessMode()); + Assert.Equal(TagAccessMode.RO, tag.SearchAccessMode()); + } + + /// + /// 运行期缓存:同一 反复读取时,解析结果被缓存且值保持正确。 + /// ("访问模式是配置期属性"是缓存成立的前提,见 。) + /// + [Fact] + public async Task ReadAsync_CachesInheritedAccessMode() + { + var grp = NewGroup("g", TagAccessMode.RO); + var tag = NewTag("t", grp); + grp.AddTag(tag); + var union = grp["t"]; + + await union.ReadAsync(TraversalMode.IgnoreEnabled, CancellationToken.None); + await union.ReadAsync(TraversalMode.IgnoreEnabled, CancellationToken.None); + + Assert.Equal(TagAccessMode.RO, union.CachedAccessMode); + } +} \ No newline at end of file From 60e848f4f25d0e0256b25cd23465e3a4d4aeaffb Mon Sep 17 00:00:00 2001 From: newbienewbie Date: Wed, 11 Nov 2026 22:33:40 +0800 Subject: [PATCH 08/17] =?UTF-8?q?Modbus:=20EnsureConnected=20=E4=B8=8D?= =?UTF-8?q?=E5=86=8D=E9=A2=84=E8=AE=BE=E7=AD=89=E5=BE=851ms?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 18 +++++ benchmarks/README.md | 22 ++++++ .../EnsureConnectedBenchmarks.cs | 77 +++++++++++++++++++ .../Channels/ModbusTcpChannel.cs | 7 +- 4 files changed, 122 insertions(+), 2 deletions(-) create mode 100644 benchmarks/StdUnit.Tags.Benchmarks/EnsureConnectedBenchmarks.cs diff --git a/CHANGELOG.md b/CHANGELOG.md index 9702ed4..d89c403 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,6 +28,24 @@ StdUnit.Tags.S7: **通道内部简化**(公开行为不变) 报告方式仍按既有约定:`DisconnectAsync` 失败抛出,`Dispose` 只记日志。 - 连接/断开不再用 `Thread` 把同步调用伪装成异步;读/写本就是"调用方提供缓冲区"的同步实现,限制条件不变。 +StdUnit.Tags.ModbusTcp: **修复每轮存活探测的 15.9 ms 开销** + - `ModbusTcpChannel.Connected` 原先用 `Socket.Poll(1000, SelectRead)` 判断链路是否还活着。 + Windows 的计时器粒度约 15.6 ms,空闲连接上这一步实测 **15.9 ms/次**;而 `TagGrpRunner` + **每轮、每个通道**都会调一次 `EnsureConnectedAsync`,于是扫描周期被凭空拖长(100 ms 周期下约 16% 开销, + 多通道叠加更明显)。 + - 改为 `Poll(0)`:判定逻辑完全不变(`Poll(SelectRead) && Available == 0` 即判定为断), + 但不再阻塞;实测单次 **15.9 ms → 2.3 µs**。 + +StdUnit.Tags.Core: **`access` 的继承修正为逐级冒泡** + - 此前只有组(`ITagGrp`)沿父链递归;`ITag` 与 `ITagCbnt` 只查"直接父级自己配了没",于是 + `TagGrp(access="RO") → TagCbnt(未配)` 下的测点会被判成 `RW`——同样的意图直接挂在组下却是 `RO`。 + 2.0 统一为:自身 → 父级 Cbnt → 各级 Grp → 默认 `RW`。 + - **行为变更**:把 `access` 写在祖先上的配置现在会真正生效。原先被误判成 `RW` 的点会变成 + `RO` / `WO` / `R1W` —— 典型影响是"只读点不再被自动轮询写入"、"`R1W` 点不再每轮重复读"。 + - **访问模式是配置期属性**:加载完成后修改 `TagDescriptor.AccessMode`(或重新赋值 `access`) + 不会生效,需要重新加载项目。原文没有明说,但这是既有实现的实际行为;现在把它写成显式约束, + 运行期因此可以安全缓存解析结果(每点位只解析一次)。 + StdUnit.Tags: **新增运行期指标(`System.Diagnostics.Metrics`)** - Meter 名 `StdUnit.Tags`,四个指标:`stdunit.tags.turns`、`stdunit.tags.turn.duration`(单位 `s`)、 `stdunit.tags.failures`、`stdunit.tags.reconnects`;维度只有 `entry`(入口定位路径)。 diff --git a/benchmarks/README.md b/benchmarks/README.md index 1025cea..d4fb9f0 100644 --- a/benchmarks/README.md +++ b/benchmarks/README.md @@ -171,6 +171,27 @@ dotnet run -c Release --project benchmarks/StdUnit.Tags.Benchmarks -- --footprin > 判断标准:**看"每轮分配"决定要不要优化**(它影响 GC 频率),**看"常驻内存"决定能装多少点**(它只影响一次性的堆占用)。 > 两者都不是"点位数越多每轮越慢"的原因——每轮成本是线性的 ns/点,而分配是常数。 +## 7. `EnsureConnectedBenchmarks` — 每轮“我还活着吗”的成本 + +`TagGrpRunner` 每轮、每个通道都会 `EnsureConnectedAsync(force:false)`。Modbus 的实现里原先用 +`Socket.Poll(1000, SelectRead)` 做存活探测——**1000 微秒的超时在 Windows 上实际会阻塞约 15.9 ms** +(Windows 默认计时器粒度约 15.6 ms),而这一步发生在每轮、每个通道上。 + +| 方法 | 修复前 | 修复后 | +|---|---|---| +| `EnsureConnectedAsync`(已连接) | **15.89 ms** | **2.28 µs** | +| 原始 `Socket.Poll(1000, SelectRead)` | 15.81 ms | — | +| 原始 `Socket.Poll(0, SelectRead)` | 1.43 µs | 1.43 µs | +| 原始 `Socket.Connected` 标志 | 0.71 ns | 0.71 ns | + +**结论**:把超时从 `1000` 改成 `0`(判定逻辑 `Poll && Available == 0` 完全不变),单次探测从 **15.9 ms 降到 2.3 µs**。 +按 100 Hz、单通道估算:每轮凭空多出的 15.9 ms 变成 2.3 µs——**这是当前框架里最大的单笔开销**, +而且它不会出现在遍历类基准里(那些用桩通道,`EnsureConnectedAsync` 是空实现)。 + +> 剩下的 2.3 µs = `Poll(0)`(1.43 µs)+ `Available` 的 ioctl。若还要压,只能放弃"半死连接"检测、 +> 直接用 `Socket.Connected` 标志(0.7 ns),把连接失效交给"读失败 → 崩溃 → 重连"路径兜底—— +> 语义上可行,但会改变探测能力,暂不做。 + --- ## 结论速览 @@ -178,6 +199,7 @@ dotnet run -c Release --project benchmarks/StdUnit.Tags.Benchmarks -- --footprin | 关注点 | 数字 | 含义 | |---|---|---| | 框架遍历 | **8.4–9.4 ns/点、每轮 0 B** | 1 万点约 0.094 ms/轮,且不产生垃圾 | +| **每轮存活探测(Modbus)** | **2.3 µs/通道**(原 15.9 ms) | 曾经的 15.9 ms 来自 `Poll(1000)` 的 Windows 计时器粒度 | | 判脏扫描(每轮一次) | 5 ns/点 | 全树干净时走完全部节点;10k ≈ 50 µs | | 组合分发 | 2.6 ns/点、逐点零分配 | 点位多本身不是问题 | | **常驻内存** | **~350–390 B/点;1k≈0.4 MB、10k≈3.5 MB、50k≈17 MB** | 与点位数线性,一次性占用,不构成部署障碍 | diff --git a/benchmarks/StdUnit.Tags.Benchmarks/EnsureConnectedBenchmarks.cs b/benchmarks/StdUnit.Tags.Benchmarks/EnsureConnectedBenchmarks.cs new file mode 100644 index 0000000..d181d9a --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/EnsureConnectedBenchmarks.cs @@ -0,0 +1,77 @@ +using System; +using System.Net; +using System.Net.Sockets; +using System.Threading; +using System.Threading.Tasks; +using BenchmarkDotNet.Attributes; +using Microsoft.Extensions.Logging.Abstractions; +using StdUnit.Tags.ModbusTcp; + +namespace StdUnit.Tags.Benchmarks; + +/// +/// 每轮“我还活着吗”的成本: 在已连接时只做一次存活探测, +/// 而它的实现里有 Socket.Poll(1000, SelectRead)——链路空闲时会**阻塞满 1 ms** 才返回。
+/// 这组基准把这条路径与“读 `Socket.Connected` 标志”“Poll(0) 快检”放在一起对比, +/// 用来判断是否值得改探测策略。真实网络里 PLC 的响应时间与此无关,这里只量框架自己的开销。 +///
+[MemoryDiagnoser] +[SimpleJob(warmupCount: 3, iterationCount: 5)] +public class EnsureConnectedBenchmarks +{ + private TcpListener _listener = null!; + private Socket _serverSide = null!; + private Socket _rawClient = null!; + private ModbusTcpChannel _channel = null!; + + [GlobalSetup] + public void Setup() + { + _listener = new TcpListener(IPAddress.Loopback, 0); + _listener.Start(); + var port = ((IPEndPoint)_listener.LocalEndpoint).Port; + + // 一对裸 socket:用于对比 Poll(1000) 与 Connected 标志 + var accept1 = _listener.AcceptSocketAsync(); + _rawClient = new Socket(AddressFamily.InterNetwork, SocketType.Stream, ProtocolType.Tcp); + _rawClient.Connect(IPAddress.Loopback, port); + _serverSide = accept1.GetAwaiter().GetResult(); + + // 通道连到另一个监听端口(复用同一个 listener 再接受一次连接) + var accept2 = _listener.AcceptSocketAsync(); + _channel = new ModbusTcpChannel( + new ModbusTcpTagChannelDescriptor { Name = "bench", IpAddr = "127.0.0.1", Port = port }, + NullLogger.Instance); + _channel.EnsureConnectedAsync(force: false, CancellationToken.None).GetAwaiter().GetResult(); + _ = accept2.GetAwaiter().GetResult(); // 保住服务端 socket,避免被 GC 关掉 + + // 预热一次,确认 Connected 判定稳定 + _channel.EnsureConnectedAsync(force: false, CancellationToken.None).GetAwaiter().GetResult(); + } + + [GlobalCleanup] + public void Cleanup() + { + _channel.Dispose(); + _rawClient.Dispose(); + _serverSide.Dispose(); + _listener.Stop(); + } + + /// 热路径现状:每轮每通道调用一次(已连接时应为“无操作”)。 + [Benchmark(Baseline = true)] + public Task EnsureConnected_AlreadyConnected() + => _channel.EnsureConnectedAsync(force: false, CancellationToken.None); + + /// 现状里真正花时间的那一步:空闲连接上最多阻塞 1000 微秒。 + [Benchmark] + public bool Socket_Poll1000_SelectRead() => _rawClient.Poll(1000, SelectMode.SelectRead); + + /// 替代方案 A:只读标志位(不产生系统调用级等待)。 + [Benchmark] + public bool Socket_ConnectedFlag() => _rawClient.Connected; + + /// 替代方案 B:非阻塞快检(Poll 0 + 有无数据)。 + [Benchmark] + public bool Socket_Poll0_SelectRead() => _rawClient.Poll(0, SelectMode.SelectRead); +} diff --git a/src/StdUnit.Tags.ModbusTcp/Channels/ModbusTcpChannel.cs b/src/StdUnit.Tags.ModbusTcp/Channels/ModbusTcpChannel.cs index e06b20e..a272882 100644 --- a/src/StdUnit.Tags.ModbusTcp/Channels/ModbusTcpChannel.cs +++ b/src/StdUnit.Tags.ModbusTcp/Channels/ModbusTcpChannel.cs @@ -152,8 +152,11 @@ protected virtual bool Connected { return false; } - // see https://stackoverflow.com/a/2661876/10091607 - bool part1 = s.Poll(1000, SelectMode.SelectRead); + // 非阻塞快检:Poll(0) 立即返回,`part1 && part2` 的判定逻辑与等待版本完全一致。 + // 绝不能带超时(原先写的是 Poll(1000)):Windows 的计时器粒度约 15.6 ms, + // 空闲连接上这一步实测要 **15.9 ms**,而它发生在每轮、每个通道的 EnsureConnected 里。 + // 基准:benchmarks/StdUnit.Tags.Benchmarks 的 EnsureConnectedBenchmarks。 + bool part1 = s.Poll(0, SelectMode.SelectRead); bool part2 = s.Available == 0; if (part1 && part2) return false; From b0b6773f562ffd3e7112b7cf61eafc3298351e35 Mon Sep 17 00:00:00 2001 From: newbienewbie Date: Wed, 11 Nov 2026 23:20:14 +0800 Subject: [PATCH 09/17] =?UTF-8?q?=E8=84=8F=E8=8A=82=E7=82=B9=E5=88=A4?= =?UTF-8?q?=E5=AE=9A=E4=BC=98=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 19 +- CHANGELOG.md | 8 + README.md | 26 +- backlog.md | 59 +++-- benchmarks/README.md | 235 +++++++++--------- .../TagTreeDirtyWriteBenchmarks.cs | 70 ++++++ ...Benchmarks.cs => TagTreeReadBenchmarks.cs} | 2 +- .../TraversalBreakdownBenchmarks.cs | 19 ++ .../\346\211\251\345\261\225\347\202\271.md" | 2 +- ...26\344\270\216\350\276\271\347\225\214.md" | 62 ++++- ...71\344\270\216\345\221\275\345\220\215.md" | 10 +- ...05\344\270\216\345\217\221\345\270\203.md" | 11 +- src/StdUnit.Tags.Core/TagGrps/ITagGrp.cs | 7 +- .../TagGrpRunners/DirtyNodeIndex.cs | 79 ++++++ .../TagGrpRunners/TagGrpRunner.cs | 11 +- .../Core/TagGrpRunners/DirtyNodeIndexTests.cs | 119 +++++++++ .../Core/TagGrpRunners/TagGrpRunnerTests.cs | 38 ++- 17 files changed, 613 insertions(+), 164 deletions(-) create mode 100644 benchmarks/StdUnit.Tags.Benchmarks/TagTreeDirtyWriteBenchmarks.cs rename benchmarks/StdUnit.Tags.Benchmarks/{TagTreeTraversalBenchmarks.cs => TagTreeReadBenchmarks.cs} (98%) create mode 100644 src/StdUnit.Tags/TagGrpRunners/DirtyNodeIndex.cs create mode 100644 tests/StdUnit.Tags.Tests/Core/TagGrpRunners/DirtyNodeIndexTests.cs diff --git a/AGENTS.md b/AGENTS.md index 459ff04..4ff9357 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,7 +23,7 @@ dotnet test --no-build --collect:"XPlat Code Coverage" --results-directory ./Tes ``` CI(`.github/workflows/dotnet.yml`)有**三个 job**: -- **`build`(ubuntu-latest,权威)**:整解 `dotnet build StdUnit.Tags.sln -c Release`(含 net472 的**编译**校验——引用程序集由 SDK 隐式引入的 `Microsoft.NETFramework.ReferenceAssemblies` 提供)+ `dotnet test -f net8.0`(带覆盖率上报 codecov)。 +- **`build`(ubuntu-latest,权威)**:整解 `dotnet build StdUnit.Tags.sln -c Release`(含 net472 的**编译**校验——引用程序集由 SDK 隐式引入的 `Microsoft.NETFramework.ReferenceAssemblies` 提供)+ 两个测试项目**分两步顺序**跑 `dotnet test -f net8.0`(`StdUnit.Tags.Tests` 与 `StdUnit.Tags.Tests.NetCoreOnly`,带覆盖率上报 codecov)。 - **`net472-on-mono`(ubuntu-latest)**:`apt-get install -y mono-complete` 自己装 Mono,跑 `dotnet test -f net472`,让 net472 的**运行**测试也自动化、又不占 Windows runner 的排队时间。**mono ≠ .NET Framework**,它绿只说明"大概率没退化",(权威结果仍归发版工作流 `release-nuget.yml` / `release-baget.yml`,windows-latest 全 TFM)+ 本机 Windows。当前是**硬性把关**(未设 `continue-on-error`);万一出现 mono 专有的伪失败,可在 job 上加 `continue-on-error: true` 降级为补充信号。mono job 红时先看是不是"mono 与真框架的差异",别急着改产品代码。 - **`aot-smoke`(ubuntu-latest)**:三个示例各自 `dotnet publish ... -r linux-x64`(需 `clang` + `zlib1g-dev`)后**运行原生产物**:`AotSmokeTest.LogicetPlugins` 验证"无 `` 的正常加载 + `TryAddLogicet` + AOT 下配了 `` 必须快速失败",`AotSmokeTest.SimpleFiles` 验证"基本类型测点 + JSON 测点(源生成元数据)读写 + AOT 下缺元数据必须快速失败",`AotSmokeTest.WebUi` 验证"起 Kestrel + 结构树的多态 JSON 序列化(`[JsonDerivedType]` 源生成)+ SSE 从全量基线到增量"。改了 AOT 相关代码(`IsAotCompatible`、`[DynamicallyAccessedMembers]`、`Compat/*`、插件加载路径、WebUi 的 DTO/序列化)时以它为准;publish 输出里的 `IL2104`/`IL3053` 来自第三方 `McMaster.NETCore.Plugins`,属已知噪声。 - 两条 Linux job 统一遵循 **"`ubuntu-latest` + 依赖自装"**,不钉镜像版本:本仓库自己装依赖(mono / clang+zlib),就没有理由把 job 的寿命绑在镜像标签上——`ubuntu-22.04` 已被官方公告 2026-09-17 起弃用、2027-04-17 退役(`actions/runner-images#14254`,期间还有 brownout 会直接判红),`ubuntu-latest` 也已宣布 2026-11 起为 26.04。 @@ -40,7 +40,7 @@ CI(`.github/workflows/dotnet.yml`)有**三个 job**: ## 目标框架(多目标) -**Core / StdUnit.Tags / Rx / R3 / 全部驱动包(S7、ModbusTcp、Hjzk、ZLan、OpcUaClient、ComScanner、SimpleFiles)/ McpServer 都是 `net8.0;net472`;仅 BlazorLib(.Core) 仍是 `net8.0`。** +**Core / StdUnit.Tags / Rx / R3 / 全部驱动包(S7、ModbusTcp、Hjzk、ZLan、OpcUaClient、ComScanner、SimpleFiles)/ McpServer 都是 `net8.0;net472`;仅 BlazorLib.Core 仍是 `net8.0`。** > McpServer 走 `ModelContextProtocol`(核心包)的 `netstandard2.0` 资产。 > `ModelContextProtocol.AspNetCore` 是 net8-only,与核心包同在 `Mcp` 组,但只被 net8-only 的项目引用,因此不影响 net472。 @@ -49,7 +49,7 @@ CI(`.github/workflows/dotnet.yml`)有**三个 job**: - **有标准库就用标准库。** 跨框架差异用调用点的 `#if NETFRAMEWORK` 或项目内 `Compat/` 目录的单点垫片(如 `StdUnit.Tags.Core/Compat/ReferenceEqualityComparer.cs`、`StdUnit.Tags/Compat/DynamicLoadingCompat.cs`、各驱动的 `Compat/*.cs`)。 - **不要把 `#if` 铺到调用点满屏幕,也不要用 `#if` 去条件修饰公共 API**(那会给库使用者制造两套签名)。 -- `ImplicitUsings`/`Nullable`/`LangVersion`/`GenerateDocumentationFile` 由 `src/` 与 `tests/` 各自的 `Directory.Build.props` 统一提供(`tests/` 那份不含 NuGet 打包元数据,且已把 `GenerateDocumentationFile` 设为 `false`),新建项目不用再写这几项(net472 默认 C# 7.3,少写一次就少一次 CS8630);`TargetFrameworks` 仍写在各 csproj(存在 net8-only 项目)。`src/` 下不生成 XML 文档的项目仍要在本项目显式写 `false`(现有:BlazorLib;它是"尚未补注释"的历史包袱)。 +- `ImplicitUsings`/`Nullable`/`LangVersion`/`GenerateDocumentationFile` 由 `src/` 与 `tests/` 各自的 `Directory.Build.props` 统一提供(`tests/` 那份不含 NuGet 打包元数据,且已把 `GenerateDocumentationFile` 设为 `false`),新建项目不用再写这几项(net472 默认 C# 7.3,少写一次就少一次 CS8630);`TargetFrameworks` 仍写在各 csproj(存在 net8-only 项目)。`src/` 下不生成 XML 文档的项目仍要在本项目显式写 `false`(目前没有这种情况)。`src/Directory.Build.props` 已开启 `TreatWarningsAsErrors`(整解仍是 0 警告);`tests/` 与 `samples/` 有意不加,因为 AOT 冒烟项目的 `dotnet publish` 会带出第三方 `McMaster.NETCore.Plugins` 的 IL2104/IL3053 噪声。 - **AOT 相关**(逐包状态见 `docs/设计决策与边界/4. 目标框架差异.md` 的表,新增包记得补一行并放进对应分组): - `true` ——**TFM 下界必须写 `net8.0`**:`NETSDK1210` 的提示文本里给的是 `'net7.0'`(SDK 的通用下界),**不要照抄**—— @@ -75,6 +75,9 @@ CI(`.github/workflows/dotnet.yml`)有**三个 job**: **必须快速失败**(`TagsProjectNotSupportedException`),**不要**让它被 `LogicetLoader` 的通用 `catch` 吞掉——配了却静默不跑业务逻辑是硬红线。 `tests/AotSmokeTest.LogicetPlugins` / `tests/AotSmokeTest.SimpleFiles` / `tests/AotSmokeTest.WebUi` 是这些链路的端到端验证(CI 的 `aot-smoke` job)。 - net472 缺 init-only setter 时,在 `paket.references` 里加 `IsExternalInit`(已有先例:Core / StdUnit.Tags / ComScanner / OpcUaClient / SimpleFiles)。 +- **net8.0 共享框架里有的 API,在 net472 上一律按需补包引用,且只在 net472 生效**:`paket.references` 写 + `framework: net472`(先例:`System.Threading.Channels`、`System.Diagnostics.DiagnosticSource`——后者是 + `StdUnit.Tags` 暴露 Metrics 所需)。这样 net8.0 的 nuspec / 消费方体验完全不变,代价只落在 net472 组。 - **net472 的引用程序集没有可空标注**,`string.IsNullOrEmpty` 之类的 BCL 后置条件看不到,会出现 net472 专属的 CS8601/CS8603/CS8604 假阳性。改用语言级判空(`x is null || x.Length == 0`),**不要用 `NoWarn` 压掉**。 - 不要用 `| Select-Object -First n` 过滤 `dotnet paket`/`dotnet build` 的长输出:会在第 n 行处终止上游进程。先 `Out-File` 再 grep。 @@ -91,7 +94,7 @@ StdUnit.Tags.Core 硬件无关的核心抽象 + Schemas/tagsproje │ ├── StdUnit.Tags.ComScanner │ ├── StdUnit.Tags.SimpleFiles │ ├── StdUnit.Tags.McpServer -│ └── StdUnit.Tags.BlazorLib(.Core) +│ └── StdUnit.Tags.BlazorLib.Core 维护模式(不再加新功能,界面能力走 WebUi) └── StdUnit.Tags.RxExtensions / R3Extensions 只依赖 Core ``` @@ -100,9 +103,13 @@ StdUnit.Tags.Core 硬件无关的核心抽象 + Schemas/tagsproje 如果驱动会从 `TagDescriptor.Extras` / `TagCbntDescriptor.Extras` 里读**自己的属性**(如 S7 的 `maxlen`、SimpleFiles 的 `autoCreateFile`、ModbusTcp 的 `interpret`),还要在同一个 `appinfo` 里用 `` / `` 声明;核心 schema 因 `xs:anyAttribute` 放行这些属性,但 XSD 1.0 无法给既有类型追加属性,所以"有哪些、什么类型、什么文案"只能由驱动声明(仅供设计器,不参与校验)。详见 `Schemas/README.md`。 - 测试分两个项目(xUnit),且**主测试项目多目标 `net8.0;net472`**: - `tests/StdUnit.Tags.Tests`:主体测试,跑在两个 TFM 上; - - `tests/StdUnit.Tags.Tests.NetCoreOnly`:**仅 net8.0**,专门存放无法面向 net472 的测试(如依赖 `AssemblyLoadContext`,或将来涉及 Blazor / ASP.NET Core 的测试)。目前为空项,作占位预留。 -- **新增测试默认放 `tests/StdUnit.Tags.Tests`**(多目标,两个 TFM 都跑);只有当测试依赖 `net8.0` 专属的包/项目(如 `ModelContextProtocol.AspNetCore`、`BlazorLib`)或 `net8.0` 专属运行期 API(如 `AssemblyLoadContext`)时,才放 `tests/StdUnit.Tags.Tests.NetCoreOnly`。 + - `tests/StdUnit.Tags.Tests.NetCoreOnly`:**仅 net8.0**,专门存放无法面向 net472 的测试(如依赖 `AssemblyLoadContext`,或涉及 Blazor / ASP.NET Core 的测试)。目前承载 `StdUnit.Tags.WebUi` 与 `BlazorLib.Core` 的测试,并已在 PR CI 中执行(不要把它排除出 CI:它曾是"只在发版当天才跑一次"的盲区)。 +- **新增测试默认放 `tests/StdUnit.Tags.Tests`**(多目标,两个 TFM 都跑);只有当测试依赖 `net8.0` 专属的包/项目(如 `ModelContextProtocol.AspNetCore`、`BlazorLib.Core`、`WebUi`)或 `net8.0` 专属运行期 API(如 `AssemblyLoadContext`)时,才放 `tests/StdUnit.Tags.Tests.NetCoreOnly`。 不要在 `tests/StdUnit.Tags.Tests` 里用 `#if NETFRAMEWORK` 排除整个文件——那是编译期开关,解决不了“引用 net8-only 项目”的问题(目前仅 `Core/Logicets/LogicetPluginLifecycleTests.cs` 因这一原因用 `Compile Remove` 在 net472 下排除)。 +- `benchmarks/StdUnit.Tags.Benchmarks`:BenchmarkDotNet 基准(`net8.0`)。它在解决方案内,所以整解构建会编译它 + (防止 API 漂移后悄悄腐烂),但**不**参与 CI 的测试与 AOT 冒烟;完整测量只在本地跑 + `dotnet run -c Release --project benchmarks/StdUnit.Tags.Benchmarks -- --filter *`。 + 依赖走 Paket 的 `Benchmarks` 组(`storage: none`),**绝不能**出现在任何发布包的依赖里。 ## 不可破坏的设计约束 diff --git a/CHANGELOG.md b/CHANGELOG.md index d89c403..055b2bb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,6 +28,14 @@ StdUnit.Tags.S7: **通道内部简化**(公开行为不变) 报告方式仍按既有约定:`DisconnectAsync` 失败抛出,`Dispose` 只记日志。 - 连接/断开不再用 `Thread` 把同步调用伪装成异步;读/写本就是"调用方提供缓冲区"的同步实现,限制条件不变。 +StdUnit.Tags: **运行器判脏改用扁平索引,干净轮次不再空写** + - `TagGrpRunner` 在每次(重)启动时把入口子树中的 `ITag` / `ITagCbnt` 收集成扁平数组,每轮判脏 + 由"递归遍历 + `TagUnion` 分发"改为两次数组扫描;并在逻辑处理后判一次,**干净时整趟跳过 `WriteAsync`** + (它原本对干净节点也是空操作)。10k 点位:判脏 52 µs → 26 µs,另省掉约 81 µs/轮的空写遍历。 + - 索引的正确性依据是 `ITagGrp.IsDirty()` 与 `WriteAsync` 的一致性契约:**`IsDirty()` 为 false 时写不得有任何动作; + 只要存在待写节点(`ITag` / `ITagCbnt` 自身的 `IsDirty`)就必须为 true**。这**不是**"父脏必有脏子"—— + `ITagCbnt.IsDirty` 可以独立为 true(整块缓存重写),索引收录的正是 Tag 与组合本身,因此不会漏。 + StdUnit.Tags.ModbusTcp: **修复每轮存活探测的 15.9 ms 开销** - `ModbusTcpChannel.Connected` 原先用 `Socket.Poll(1000, SelectRead)` 判断链路是否还活着。 Windows 的计时器粒度约 15.6 ms,空闲连接上这一步实测 **15.9 ms/次**;而 `TagGrpRunner` diff --git a/README.md b/README.md index 646d6e5..ee10d39 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,31 @@ dotnet new tags.driver -n your-project.name -D YourDriver - 业务逻辑插件化:`netcore`上支持逻辑组件插件(dll),各插件的依赖相互隔离、支持卸载和热更(`netfx`上降级支持,见“netfx 的插件化限制”)。 - 支持通过MCP方式暴露给AI:把测点项目描述作为上下文,让AI可以轻松操作你的设备 +## Benchmarks + +本类库自身的开销已经量化,并作为回归基线维护在 [benchmarks/README.md](benchmarks/README.md)(含复现命令与每个数字的边界说明)。 +下面是实测基线中的一组代表性数字(i7-8700 3.20 GHz;耗时随机器变化,只看**量级**与堆分配): + +| 场景 | 开销 | 堆分配 | +|---|---|---| +| 轮询-读遍历(每点位) | **~9 ns** | **0 B** | +| 轮询-组合式测点分发(每子测点) | **~2–3 ns** | **0 B** | +| 轮询-每轮判脏(每点位) | **~2.4 ns** | **0 B** | +| 轮询-每轮通道存活探测(Modbus) | **~2.3 µs/通道** | **0 B** | +| 轮询-指标打点(无人订阅 / 有人订阅) | 3.8 ns / 5.7 ns | **0 B** | + +表中的**轮询路径**不产生托管垃圾,意味着对 `GC` 零压力;轮询循环里唯一的固定分配是轮间等待的定时器(几百字节/轮),不在本表范围内。 +而每个点位自身仍需要少量存储空间(目前约 **350–400 B/点**)——这部分属于一次性常驻内存,随点数线性增长,与是否扫描、扫描频率都无关,也不会带来 `GC` 压力。这组数字说明三点: + +- **类库不是瓶颈**:1 万点位的读遍历,在类库自身层面约 **0.09 ms/轮**,而一次 Modbus / OPC UA 往返是 ms 级。 +- **稳态零分配**:上述路径不产生托管垃圾,高频采集时的 GC 压力与点位数无关,也不是由 `StdUnit.Tags` 运行时自身产生的。 +- **常驻内存随点数线性增长**:1 万点位约 3.3–3.8 MB(托管对象图),5 万点位约 17–19 MB,不构成部署障碍。 + +> 例外:直读点位(`DirectTag`,兜底用法)每点每轮有一次地址解析(约 0.8 KB 分配);把点位组织成 `TagCbnt` 时地址只在加载期解析一次。 +> +> 这些数字只用于版本间对比,不作为对具体现场的吞吐承诺。 + + ## 文档与示例 ### 文件夹结构 @@ -181,7 +206,6 @@ dotnet-counters monitor --counters StdUnit.Tags -p AI 可以直接参考 [StdUnit.Tags —— 给 AI 的参考手册](https://tags.doc.stdunit.com/assets/999.AI.markdown)(机器可读的原始 Markdown),也可以先访问 ,那里是文档站给 AI 准备的索引。 - ## 目标框架 本项目家族同时支持 `net8.0` 与 `net472`(.NET Framework 4.7.2),以便逐步迁移中的旧系统也能用上同一套抽象: diff --git a/backlog.md b/backlog.md index 85d9e28..49bb329 100644 --- a/backlog.md +++ b/backlog.md @@ -1,23 +1,40 @@ # Backlog / 开发计划 -> **v1.0 之前的 todo 已全部完成。** 其中的决策与理由("当时为什么这么选")已按专题整理到 -> [docs/设计决策与边界/](docs/设计决策与边界/)(范围与契约、CI、兼容与命名、打包与发布、错误处理), -> 本文件此后**只保留"还要做什么"**。 - -## v1.0 之后的 todo - -- [ ] 公开面基线工具(`Microsoft.CodeAnalysis.PublicApiAnalyzers` + `PublicAPI.Shipped.txt`):留到 v1.1 之后。 -- [ ] 日志、报错提示、注释文档的多语言支持。 -- [ ] 代码评审后续项(背景与理由见 `docs/设计决策与边界/`): - - [ ] **通道的资源释放完整性**:`ModbusTcpChannel.Dispose()` 只 `Close()` 掉 `TcpClient`,没有释放 `_connSignal`(`SemaphoreSlim`);且 `DisconnectAsync()` 不参与 `_connSignal` 的互斥,`EnsureConnectedAsync` 与它并发时可能"断开后被重连"。`OpcUaClientTagChannel.Dispose()` 只 `Close()` 会话。(根因"StopAsync 与循环并发"已修,这里只剩"Dispose 不完整"的洁癖级问题。) - - [x] ~~**跨驱动一致性**:`TagChannelDescriptor_S7Extensions` 这个类名在 **Hjzk 与 ZLan** 里都是 S7 的复制粘贴残留~~ **已改**:改为 `TagChannelDescriptor_HjzkExtensions` / `TagChannelDescriptor_ZLanTcpExtensions`(1.0 未发布,此刻改名不构成破坏性变更)。 - - [ ] **重复代码收敛**(各驱动 `AddXxxSupport()` 的注册样板、`ToXxxTagChannelDescriptor` 的骨架、`FileAsyncCompat`、`FloatBitsCompat`、DI/DO 的 `Area` 谓词):建议收敛到 `StdUnit.Tags.Core` 或各驱动的公共位置。注意 `FileAsyncCompat`/`FloatBitsCompat` 是跨框架垫片,收敛时要保持"调用点无 `#if`"的既有约定。 - - [ ] **运行期观测**:用 `System.Diagnostics.Metrics` 暴露每轮耗时、失败次数、重连次数、意图被拒次数(日志对"长期趋势"无能为力)。 - - [ ] **热重载 API**(`ReloadAsync(root)`)与"写后读回校验"选项。 -- [ ] 工程化: - - [ ] 覆盖率门槛:`coverlet.collector` 已引入,但尚未设门槛; - - [ ] 启用 NetAnalyzers / `TreatWarningsAsErrors`。 -- [ ] Cache 性能优化:Modbus 读路径 cache 复用——`TagCbnt` 各驱动的 `ReadAsync` 每轮轮询换新 `Cache` 引用(如 `ModbusRegisterTagCbnt` 的 `this.Cache = regs`、位空间 `this.Cache = bits`),`CacheSize` 不变时可复用同一 `T[]` 消除每轮分配;需接口改动(`IModbusRegisterChannel.ReadRegistersAsync`/`IModbusBitsChannel.ReadBitsAsync` 改为写入预分配 buffer 返回元素数) -- [ ] S7 优化:底层基于 Sharp7 一个古老的实现,有两个优化的点: - - 底层通道基于 Sharp7 一个古老的同步实现,用了 `Thread` 伪装成异步接口。将来可以改成真异步(上层异步接口不需要变更)。说明:PLC的并发吞吐能力远小于上位机,而且目前已经在单通道做了串行轮询机制,所以这个改进的收益不大。(2026-10 更新:通道**读写**已改成诚实的同步方法,`Thread` 伪装现在只剩**连接/断开**两条路径。) - - [x] ~~底层有很多无谓的字节拷贝和内存分配操作,借助 C# 的 `Span` 和 `Memory` 可以大幅优化实现。~~ **已改**:Sharp7 0.8.x 的 `DBRead`/`MBRead`/`DBWrite`/`MBWrite` 接受 `Span`,因此通道读写改成"调用方提供缓冲区"的同步方法(`S7TagChannel.Read/Write`,带 `ct` 仅用于等待 I/O 互斥体时可取消)。缓冲区一路透到硬件层:组合式测点直接读写 `TagCbnt.Cache`,直接测点用 `stackalloc`——读/写两条路径都不再产生 `byte[]`。 +> 本文件只保留**还要做什么**;"当时为什么这么选"在 [docs/设计决策与边界/](docs/设计决策与边界/)。 +> **已评估、决定不做**的条目(公开面基线、`WriteIntent` 旧重载、热重载、S7 连接/断开真异步等)也记在那边—— +> 想推翻它们请改 `docs`,不要在本文件里重新开一条。 + +## 现状快照(2026-11-11) + +- 版本:`2.0.0-beta8` 已发布;`2.0.0-beta9` 是 2.0.0 的最后一个 beta(计划 2026-12),随后进 RC。 +- **beta9 的独占窗口已经空了**:动公开面、动驱动内部、定包清单这三件事都已完成 + (删除 `BlazorLib`、驱动释放路径收敛、S7 通道简化、包清单定稿并写明 `BlazorLib.Core` 维护模式)。 + 剩下的是 RC 期收尾与 2.1+ 的增量,**都不必挤在 beta9**。 +- 构建:整解 `dotnet build StdUnit.Tags.sln -c Release` = 0 警告 0 错误(`src/` 已开 `TreatWarningsAsErrors`); + `StdUnit.Tags.Tests`(两个 TFM)与 `Tests.NetCoreOnly`(net8.0)都绿。 +- PR/push CI:整解构建(net8.0 + net472 编译)→ net8.0 主测试 → net8.0-only 测试 → + net472-on-mono → AOT 三件套 + WebMonitor publish。 +- 发布物与包清单以 [src/publish-packages.ps1](src/publish-packages.ps1) 为唯一准绳。 +- 运行期观测:`StdUnit.Tags` 已暴露 4 个 `System.Diagnostics.Metrics` 指标(`stdunit.tags.*`,维度只到 `entry`)。 +- 性能基准:[benchmarks/StdUnit.Tags.Benchmarks](benchmarks/StdUnit.Tags.Benchmarks)(在解决方案内,CI 只**编译**不运行)。 + +--- + +## 一、RC 前(只收尾,不动公开面) + +- [ ] **2.0 迁移指南**:把各 beta 的破坏性变更汇总成"1.x → 2.0 要改什么"。现在它们散落在 CHANGELOG 的十几条 + beta 条目里,且同一处 API 常被多轮迭代(`ITagGrpRunner` 的 event→属性、`TagsProjectEventArgs.IsStarted` + →扩展方法、S7 的 `CreateClientAndConnectAsync`→`CreateClientAndConnect`),按 beta 顺序读拼不出"我现在该怎么写"。 +- [ ] **发布前复核一次**:Windows 真机全 TFM、NativeAOT 产物、WebUi 端到端(release 工作流已覆盖,要有人看结果)。 +- [ ] **首次 push 后盯一次 CI**:新增的 net8.0-only 测试步骤还没在 GitHub 上跑过——确认 `--no-build` + 两步顺序 + 在 4 vCPU runner 上真能跑通,而不只是本地通过。 +- [ ] **定覆盖率算不算硬门槛**:codecov 已有 `patch 91%` + `project: auto ±5%`,但不确定它是不是 required check。 + 要么确认它已经在拦,要么明确"不拦"——别留成"看起来有、其实靠自觉"。 +- [ ] **XML 注释抽查**:README 承诺"每个公开成员都有注释",抽查一轮,重点是本次新增与改签名的成员。 + +--- + +## 二、2.1+(增量,不阻塞 2.0) + +- [ ] 日志 / 报错 / 注释文档的多语言支持——**不做预留性重构**,真要做时按资源内嵌整体改。 +- [ ] 分析器加码(`AnalysisMode=All`);`net472-on-mono` 从"硬性把关"转正或降级。 \ No newline at end of file diff --git a/benchmarks/README.md b/benchmarks/README.md index d4fb9f0..91c1558 100644 --- a/benchmarks/README.md +++ b/benchmarks/README.md @@ -11,7 +11,8 @@ | 项 | 值 | |---|---| - | 日期 | 2026-11-11 | + | 软件版本 | `2.0.0-beta9`(首个对外发布的基线) | + | 日期 | 2026-11-12 | | BenchmarkDotNet | v0.15.8 | | .NET SDK | 8.0.129(`net8.0`) | | OS | Windows 10 22H2 (10.0.19045) | @@ -35,162 +36,160 @@ dotnet run -c Release --project benchmarks/StdUnit.Tags.Benchmarks -- --footprin --- -## 1. `TagTreeTraversalBenchmarks` — 框架自身开销 +## 1. 读遍历(`TagTreeReadBenchmarks`) -一棵 N 个测点的树(均分到 10 个子组),叶子是纯内存假测点、通道是空实现,所以测到的只有遍历、 -使能/脏标记判断与派发,与硬件、网络无关。 +一棵 N 个测点的树(均分到 10 个子组),叶子是纯内存假测点、通道是空实现,所以测到的只有读遍历、 +访问模式/使能判断与派发,与硬件、网络无关。 | 方法 | 点位 | Mean | Allocated | |---|---|---|---| | `NoOp`(基线) | — | 0.24 ns | 0 B | -| `ReadAsync` | 1 000 | 8.45 µs | **0 B** | -| `ReadAsync` | 10 000 | 94.15 µs | **0 B** | +| `ReadAsync` | 1 000 | 8.80 µs | **0 B** | +| `ReadAsync` | 10 000 | 92.22 µs | **0 B** | -**结论**:每点耗时约 **8.4–9.4 ns**(1k 与 10k 同量级,线性),**整轮零分配**。 -1 万点位的框架开销约 0.094 ms,相对一轮真实采集(设备往返 ms 级)可以忽略。 +`NoOp`(直接返回 `Task.CompletedTask`,0 B)用来证明 `Allocated` 列不是基准装置自身的开销。 -### 1.1 时间花在哪(`TraversalBreakdownBenchmarks`,10 000 个扁平叶子) +**结论**:读遍历每点约 **8.8–9.2 ns**,线性;**整轮零分配**。1 万点位的读约 0.092 ms。 +写遍历见 §2。 -| 逐层加回成本 | 每点耗时 | 说明 | +### 1.1 读遍历的成本拆解(`TraversalBreakdownBenchmarks`,10 000 个扁平叶子) + +| 逐层加回成本 | 总计 | 每点 | |---|---|---| -| 纯数组遍历 | 0.47 ns | 基线 | -| + 访问模式解析(`SearchAccessMode`,**未走缓存**) | 6.2 ns | 逐级冒泡的裸成本:自身 → 父级 Cbnt → 各级 Grp → 兜底 RW | -| + 派发 + 完成检查 | 1.8 ns | 一次接口调用 + `Task.Status` | -| + 策略判断(R1W/WO)与派发 | 6.6 ns | 上面两项组合(有重叠) | -| `TagUnionExtensions.IsDirty`(每轮另一次全树扫描) | 5.0 ns | 全树干净时走完所有节点 | -| **实际遍历(`TagUnion.ReadAsync`,含缓存命中)** | **8.4–9.4 ns** | 见上表;比"裸解析"低,因为每节点一生只解析一次 | - -**瓶颈与结论**:逐级冒泡的**裸解析**是 6.2 ns/点,但**热路径上不会重复付这个钱**——访问模式是配置期属性, -解析结果缓存在 `TagUnion.CachedAccessMode` 上,之后只剩空值检查。所以剩下的就是一次派发 + 策略判断 + 状态回写, -已经接近"每个节点必须做的记账"的下限。要再快就只剩 `IsDirty` 全树扫描改成增量脏标记(语义改动大,暂不做)。 - -> 历史(2026-11 三轮修复): -> 1. `1 000 → 72.41 µs / 221.54 KB`、`10 000 → 775.93 µs / 2190.29 KB`: -> `TagUnionExtensions.ReadAsync/WriteAsync` 通过 `TagUnion.Map` 传三个 `async` 闭包, -> **每个节点**都要构造闭包 + 委托 + 异步状态机(≈220 B)。改为手动 `switch` 后降到 616 B / 轮。 -> 2. `616 B → 0 B`:`TagGrp.Children` / `TagCbnt.Children` 是 `IDictionary`,`foreach` 走接口会**装箱 -> `Dictionary.Enumerator`**(每次遍历一个分配),而它出现在每轮的读、写、判脏与通知路径上。 -> 改存具体 `Dictionary`、只让公开属性保持 `IDictionary` 后,分配归零; -> 同一改动把组合分发从 `9.88 µs / 128 B`(1 000 子测点)压到 `2.00 µs / 72 B`。 -> 3. `37.47 µs → 12.85 µs`(1 000 点):`SearchAccessMode` 原来用 `TagContainer.Map` + 两个委托, -> 每点位要查 **两次**(R1W 判定 + `IsWriteOnly`);改为 `TagContainer.AccessMode` 的 `switch`、 -> 只查一次,并给 `ReadAsync` 加了"读同步完成就不进 async 机制"的快路径。 -> 4. `12.85 µs → 8.45 µs`(1 000 点):访问模式改为**逐级冒泡**(修正 `ITag`/`ITagCbnt` 只查一层的旧缺陷), -> 同时按"访问模式是配置期属性"把它缓存在 `TagUnion.CachedAccessMode` 上——每个节点一生只解析一次, -> 之后是空值检查。正确性与速度同时拿到。 -> 前两条已写进 `docs/设计决策与边界/0. 设计决策与边界.md` §三:热点路径不要用 `Map` + 闭包, -> 也不要用 `IDictionary` 接口去 `foreach`。 - -## 2. `CbntFanOutBenchmarks` — “数千点位”的现实形态 - -真实的场景往往要组合多个测点成为一个`TagCbnt`,从而把N次读写合并成一次`IO`。这个测试正是为这个场景准备的。一次硬件读之后,把值分发给 N 个子测点(组合式测点)。这是 5 000 点位项目的真实形状;而“N 个独立测点各读一次”是 N 次设备往返,现实中不存在,因此不作为基准。 +| 纯数组遍历 | 4.91 µs | 0.49 ns | +| + 访问模式解析(`SearchAccessMode`,**未走缓存**) | 62.26 µs | 6.23 ns | +| + 派发 + 完成检查 | 19.62 µs | 1.96 ns | +| + 策略判断(R1W/WO)与派发 | 74.46 µs | 7.45 ns | +| 实际遍历(`TagUnion.ReadAsync`,含访问模式缓存命中) | **78.50 µs** | **7.85 ns** | +| `IsDirty`(经 `TagUnion` 分发) | 50.85 µs | 5.09 ns | +| `IsDirty`(扁平数组 + 直接读 `ITag.IsDirty`) | **23.95 µs** | **2.39 ns** | + +**结论**:逐级冒泡解析访问模式本身要 6.2 ns/点,但它是**配置期属性**,解析结果缓存在 +`TagUnion.CachedAccessMode` 上,热路径只做一次空值检查——所以实际遍历低于"裸解析"。 +剩下的就是每个节点必须做的记账(一次派发 + 策略判断 + 状态回写),已经接近下限。 + +## 2. 写遍历:干净 vs 少量脏 vs 全脏(`TagTreeDirtyWriteBenchmarks`) + +叶子是纯内存假测点(写方法不做设备 IO),因此量的是**框架的派发开销**;"脏"叶子用永不自动清脏的假测点表示, +所以不需要在迭代间重置状态。「0% 脏」那一列就是运行器在"无脏数据"时**跳过**的动作(见第 9 节)。 + +| 点位 | 0% 脏 | 1% 脏 | 100% 脏 | +|---|---|---|---| +| 1 000 | 8.02 µs | 7.93 µs | 8.13 µs | +| 10 000 | 83.80 µs | 81.10 µs | 86.87 µs | + +**结论**:写遍历的成本几乎全部来自**遍历本身**(每节点约 8 ns),"有多少节点真的被写"只带来个位数百分比的差异。 +所以"干净时跳过写遍历"(第 9 节)比"让写更便宜"更有价值。真实设备的写入耗时不在本表内。 + +## 3. `CbntFanOutBenchmarks` — “数千点位”的现实形态 + +一次硬件读之后,把值分发给 N 个子测点(组合式测点)。这是 5 000 点位项目的真实形状; +“N 个独立测点各读一次”是 N 次设备往返,现实中不存在,因此不作为基准。 | 子测点数 | Mean | Allocated | |---|---|---| -| 1 000 | 2.00 µs | 72 B | -| 5 000 | 12.79 µs | 72 B | +| 1 000 | 2.12 µs | 72 B | +| 5 000 | 15.60 µs | 72 B | -**结论**:每点约 **2.6 ns**,逐点零分配(那 72 B 是基准桩里 `Task.FromResult` 的固定开销,不是框架的)。 -组合式的分发成本远低于遍历,说明“点位多”本身不是瓶颈。 +**结论**:每点 **2.1–3.1 ns**,逐点零分配(那 72 B 是基准桩里 `Task.FromResult` 的固定开销,不是框架的)。 -## 3. `S7ChannelReadBenchmarks` — 读一块 DB +## 4. `S7ChannelReadBenchmarks` — 读一块 DB 用桩 `S7Client`(只占位、立即返回 0),测的是**我们这层**:地址解析、互斥体、`Span` 传递、错误码检查。 | 字节数 | Mean | Allocated | |---|---|---| -| 1 000 | 588.9 ns | 832 B | -| 20 000 | 588.0 ns | 832 B | +| 1 000 | 606.3 ns | 832 B | +| 20 000 | 601.9 ns | 832 B | -**结论**:单次读,内存分配与字节数无关(零拷贝,缓冲区是调用方提供的)。 +**结论**:单次读 < 1 µs,分配与字节数无关(零拷贝,缓冲区由调用方提供)。 **真实耗时里 PLC 响应占绝对多数**,这组数字的用途是确认“我们不是瓶颈”。 +那 832 B 只发生在**直读点位**(`DirectTag`,兜底用法)——地址在每轮解析;组合式测点的地址只在加载期解析一次。 -> 历史(2026-11 修复前):`6.2 µs / 10.49 KB`(两种大小相同)。原因是 `S7AddressParser` 每次 `Parse` -> 都 `new Regex(...)`;提升为 `static readonly` 后降到现在这个水平。剩下的 832 B 来自 `Match`/`S7Address` 的分配, -> 要再压需改成 span 手写解析——目前不值得,已记录为“不做”。 - -## 4. `ModbusCbntReadBenchmarks` — cache 复用是否值得 +## 5. `ModbusCbntReadBenchmarks` — 通道数组的分配 -组合式测点每轮读;用桩通道对比“每轮返回新数组”(现状)与“写入调用方预分配数组”(需要改公开接口)。 +组合式测点每轮读;用桩通道对比“每轮返回新数组”(NModbus 的形状)与“写入调用方预分配数组”。 -| 寄存器数 | 现状 | 复用 Cache | 耗时 | +| 寄存器数 | 通道返回新数组 | 复用缓冲区 | 耗时 | |---|---|---|---| -| 32 | 160 B | 72 B | ~32 ns(无可测差异) | -| 125 | 352 B | 72 B | ~31–40 ns(抖动大于差距) | +| 32 | 160 B | 72 B | 30–35 ns | +| 125 | 352 B | 72 B | 30–40 ns | -**结论:不做**。省下 9–28 KB/s(按 100 Hz 单入口估算),代价是 `IModbusRegisterChannel` / -`IModbusBitsChannel` 的公开签名变更(net472 没有默认接口方法兜底)。已记入 -`docs/设计决策与边界/0. 设计决策与边界.md` §五“已评估、决定不做”。 +**结论**:每轮省 88–280 B,耗时无可测差异。按 100 Hz、单入口估算约 9–28 KB/s, +相对一次 Modbus TCP 往返可忽略;而"复用"需要改 `IModbusRegisterChannel` 的公开签名。 +**维持现状**(决策记录见 `docs/设计决策与边界/0. 设计决策与边界.md` §五)。 -## 5. `MetricRecordingBenchmarks` — 打点开销 +## 6. `MetricRecordingBenchmarks` — 打点开销 | 场景 | Mean | Allocated | |---|---|---| -| 无监听者(默认部署) | 3.64 ns | 0 B | -| 有 `MeterListener` | 5.77 ns | 0 B | +| 无监听者(默认部署) | 3.77 ns | 0 B | +| 有 `MeterListener` | 5.68 ns | 0 B | -**结论**:验证了 README 的承诺——“没人订阅时零分配、纳秒级,所以不需要开关”。开启采集后每轮也只多 ~2 ns。 +**结论**:没人订阅时零分配、纳秒级,所以指标常开没有代价;订阅后每轮多 ~2 ns。 -## 6. 内存:1000 个点和 10000 个点,有影响吗? +## 7. 内存:1000 个点和 10000 个点,有影响吗? -要分两种"内存"看,它们经常被混为一谈: +要分两种"内存"看: | | 是什么 | 与点位数的关系 | |---|---|---| -| **每轮分配** | 每轮采集新产生的垃圾(`[MemoryDiagnoser]` 的 `Allocated`) | **无关**:1k 与 10k 完全相同 | -| **常驻内存** | 加载后一直活着的对象图(测点、组合子、描述符) | **线性**:点位数 × 每点约 350–390 B | +| **每轮分配** | 每轮采集新产生的垃圾(`[MemoryDiagnoser]` 的 `Allocated`) | **无关**:都是 0 B | +| **常驻内存** | 加载后一直活着的对象图(测点、组合子、描述符) | **线性**:点位数 × 每点约 350–400 B | -### 6.1 每轮分配:与点位数无关(且已是 0) - -| 形态 | 1 000 点 | 10 000 点 | -|---|---|---| -| 遍历 | **0 B / 轮** | **0 B / 轮** | -| 组合式分发 | **0 B / 轮**(基准表里的 72 B 来自桩通道) | 同左 | +### 7.1 每轮分配:0 B,与点位数无关 -也就是说:**高频采集时的 GC 压力与点位数无关,而且框架层当前是零分配**。 -2026-11 的两轮修复(`Map`+闭包 → `switch`;`IDictionary` 遍历 → 具体字典)把这件事从 -"每节点 220 B"做到了"每轮 0 B"。 +遍历、组合分发、指标记录的 `Allocated` 都是 0(组合分发表里的 72 B 来自基准桩)。 +10 Hz × 10k 点位也不会产生可观测的 GC 压力。 -### 6.2 常驻内存:严格线性 +### 7.2 常驻内存:严格线性 -用 `--footprint` 模式测量(构建对象图前后各一次 full GC,取 `GC.GetTotalMemory(true)` 差值): +用 `--footprint` 测量(构建对象图前后各一次 full GC,取 `GC.GetTotalMemory(true)` 差值): | 形态 | 1 000 点 | 10 000 点 | 50 000 点 | 每点 | |---|---|---|---|---| -| 树形(10 个子组) | 0.41 MB | 3.73 MB | 18.27 MB | ~383–432 B | +| 树形(10 个子组) | 0.42 MB | 3.80 MB | 18.66 MB | ~391–440 B | | 组合式(1 Cbnt + N 子测点) | 0.34 MB | 3.31 MB | 16.53 MB | ~347 B | -**结论**: +- 常驻内存是**一次性、线性**的:1 万点位约 **3.3–3.8 MB**,5 万点位约 **16.5–18.7 MB**(托管对象图,不含 XML 源文本与业务数据),不构成部署障碍。 +- 组合式比树形略省(少一层测点对象与 `TagUnion` 包装),密集点位优先用组合式。 +- 这是**下限**:真实项目还会持有 XML、字符串与业务侧对象。 -- 常驻内存是**一次性、线性**的:1 万点位约 **3.3–3.7 MB**,5 万点位约 **16–18 MB**(托管对象图,不含 XML 源文本与业务数据)。 - 这个量级对现代进程很小,**不构成部署障碍**。 -- 组合式比树形略省(少一层测点对象、`TagUnion` 包装与描述符),所以在点位密集时优先用组合式测点, - 内存与遍历成本都更低。 -- 这里是**下限**:真实项目还会持有 XML、字符串与业务侧对象;基准只量"本库自己的对象图"。 +> 判断口径:**看"每轮分配"决定要不要优化**(影响 GC 频率),**看"常驻内存"决定能装多少点**(一次性的堆占用)。 -> 判断标准:**看"每轮分配"决定要不要优化**(它影响 GC 频率),**看"常驻内存"决定能装多少点**(它只影响一次性的堆占用)。 -> 两者都不是"点位数越多每轮越慢"的原因——每轮成本是线性的 ns/点,而分配是常数。 +## 8. `EnsureConnectedBenchmarks` — 每轮“我还活着吗”的成本 -## 7. `EnsureConnectedBenchmarks` — 每轮“我还活着吗”的成本 +`TagGrpRunner` 每轮、每个通道都会 `EnsureConnectedAsync(force:false)`。Modbus 的存活探测用 +`Socket.Poll(SelectRead)` + `Available == 0` 判定,当前实现用 **0 超时**(非阻塞); +下表同时给出带超时的版本作对照——`Poll(1000)` 在 Windows 上受计时器粒度影响(≈15.6 ms)实际阻塞 **15.8 ms**。 -`TagGrpRunner` 每轮、每个通道都会 `EnsureConnectedAsync(force:false)`。Modbus 的实现里原先用 -`Socket.Poll(1000, SelectRead)` 做存活探测——**1000 微秒的超时在 Windows 上实际会阻塞约 15.9 ms** -(Windows 默认计时器粒度约 15.6 ms),而这一步发生在每轮、每个通道上。 +| 方法 | Mean | +|---|---| +| `EnsureConnectedAsync`(已连接,当前实现) | **2.30 µs** | +| 原始 `Socket.Poll(0, SelectRead)` | 1.42 µs | +| 原始 `Socket.Poll(1000, SelectRead)` | 15.82 ms | +| 原始 `Socket.Connected` 标志 | 0.72 ns | -| 方法 | 修复前 | 修复后 | -|---|---|---| -| `EnsureConnectedAsync`(已连接) | **15.89 ms** | **2.28 µs** | -| 原始 `Socket.Poll(1000, SelectRead)` | 15.81 ms | — | -| 原始 `Socket.Poll(0, SelectRead)` | 1.43 µs | 1.43 µs | -| 原始 `Socket.Connected` 标志 | 0.71 ns | 0.71 ns | +**结论**:每轮每通道的存活探测固定开销约 **2.3 µs**(≈ `Poll(0)` + `Available` 的 ioctl)。 +表中 `Poll(1000)` 那一行说明"带超时的探测"在 Windows 上受计时器粒度影响(≈15.6 ms), +因此当前实现采用 0 超时——两者判定逻辑相同,差别只是否等待。 + +## 9. 运行器判脏索引(`DirtyNodeIndex`) + +运行器在每次(重)启动时把入口子树里的 `ITag` / `ITagCbnt` 收进两个扁平数组,判脏变成两次数组扫描; +干净时它还会跳过那趟必然空转的写遍历(§2 的「0% 脏」列,10k ≈ 82 µs)。 -**结论**:把超时从 `1000` 改成 `0`(判定逻辑 `Poll && Available == 0` 完全不变),单次探测从 **15.9 ms 降到 2.3 µs**。 -按 100 Hz、单通道估算:每轮凭空多出的 15.9 ms 变成 2.3 µs——**这是当前框架里最大的单笔开销**, -而且它不会出现在遍历类基准里(那些用桩通道,`EnsureConnectedAsync` 是空实现)。 +| 项目(10 000 节点) | 数值 | +|---|---| +| 判脏:`entry.IsDirty()`(递归 + `TagUnion` 分发) | 50.85 µs(5.09 ns/点) | +| 判脏:扁平索引(直接读 `ITag.IsDirty`) | **23.95 µs(2.39 ns/点)** | +| 干净树上的 `WriteAsync` | 81.36 µs —— **整趟跳过** | -> 剩下的 2.3 µs = `Poll(0)`(1.43 µs)+ `Available` 的 ioctl。若还要压,只能放弃"半死连接"检测、 -> 直接用 `Socket.Connected` 标志(0.7 ns),把连接失效交给"读失败 → 崩溃 → 重连"路径兜底—— -> 语义上可行,但会改变探测能力,暂不做。 +- 索引只收录 `ITag` / `ITagCbnt`,它们正是写单元(`WriteAsync` 只看这两类各自的 `IsDirty`); + `ITagCbnt` 可以独立为脏(整块缓存重写),所以必须收录组合本身。 +- 正确性依据是 `ITagGrp.IsDirty()` 与 `WriteAsync` 的一致性契约(见接口注释): + **返回 false 时写不得有任何动作;只要存在待写节点就必须返回 true**。它**不是**"父脏必有脏子"。 +- 等价性由 `DirtyNodeIndexTests` 保证(空树、脏 Tag、脏 Cbnt、嵌套组、混合树反复切换)。 --- @@ -198,24 +197,20 @@ dotnet run -c Release --project benchmarks/StdUnit.Tags.Benchmarks -- --footprin | 关注点 | 数字 | 含义 | |---|---|---| -| 框架遍历 | **8.4–9.4 ns/点、每轮 0 B** | 1 万点约 0.094 ms/轮,且不产生垃圾 | -| **每轮存活探测(Modbus)** | **2.3 µs/通道**(原 15.9 ms) | 曾经的 15.9 ms 来自 `Poll(1000)` 的 Windows 计时器粒度 | -| 判脏扫描(每轮一次) | 5 ns/点 | 全树干净时走完全部节点;10k ≈ 50 µs | -| 组合分发 | 2.6 ns/点、逐点零分配 | 点位多本身不是问题 | -| **常驻内存** | **~350–390 B/点;1k≈0.4 MB、10k≈3.5 MB、50k≈17 MB** | 与点位数线性,一次性占用,不构成部署障碍 | -| **每轮分配** | **1k 与 10k 都是 0 B** | 高频采集的 GC 压力与点位数无关 | -| S7 通道读 | 0.59 µs/次、832 B(与数据量无关) | 仅影响直读点位(兜底用法),PLC 决定实际耗时 | -| Modbus cache 复用 | 每轮省 88–280 B | 不值得改公开接口 | -| 指标记录 | 3.6 ns / 0 B;订阅后 5.8 ns | 可以放心常开 | - -> 分配**按点位线性放大**只发生在"直读点位"(DirectTag)形态:S7 每点一次地址解析 ≈832 B。 -> 但 DirectTag 是兜底用法,正常应把点位组织成 `TagCbnt`——那时一次硬件读 + 零分配分发,没有这个问题。 +| 框架遍历 | **8.8–9.2 ns/点、每轮 0 B** | 1 万点约 0.092 ms/轮,不产生垃圾 | +| 组合分发 | **2.1–3.1 ns/点、逐点零分配** | 点位多本身不是瓶颈 | +| 判脏 | **2.4 ns/点**(扁平索引) | 10k ≈ 24 µs;干净时还跳过约 82 µs 的空写遍历 | +| 写遍历 | 8 ns/点(10k ≈ 81–87 µs),**与脏比例几乎无关** | 成本在"走一遍",不在"写多少个" | +| 每轮存活探测(Modbus) | **2.3 µs/通道** | 非阻塞探测(`Poll(0)` + `Available`)的固定成本 | +| S7 通道读 | 0.60 µs/次、832 B | 仅影响DirectTag(非`TagCbnt`的兜底用法),PLC 决定实际耗时 | +| Modbus 通道数组 | 每轮 160–352 B | 不值得改公开接口复用缓冲区 | +| 指标记录 | 3.77 ns / 0 B(订阅后 5.68 ns) | 可常开 | +| 常驻内存 | **~350–400 B/点**;1k≈0.4 MB、10k≈3.5 MB、50k≈17 MB | 一次性、线性,不构成部署障碍 | ## 维护约定 - 新增基准:一个类一个关注点,`[MemoryDiagnoser]` 必开;**必须**能说明“这组数字能/不能得出什么结论”, 避免把桩实现或回环网络的结果当成端到端性能。 - 基准结果不设门槛(机器差异会让它变成随机红);它只用来做改动前后对比。 -- 改动热路径(遍历、组合通知、驱动读写)时,请顺手在本文件更新对应表格——**数字过期比没有更糟**。 -- 改了点位的对象结构(新增字段/包装层)时,记得重跑 `--footprint`:常驻内存是**每点 ~350 B** 的线性量, - 多一个字段就是几十 B × 点位数。 +- 改动热路径(遍历、组合通知、驱动读写、判脏)时,请顺手更新本文件的对应表格——**数字过期比没有更糟**。 +- 改了点位的对象结构(新增字段/包装层)时,记得重跑 `--footprint`:常驻内存是**每点 ~350 B** 的线性量。 \ No newline at end of file diff --git a/benchmarks/StdUnit.Tags.Benchmarks/TagTreeDirtyWriteBenchmarks.cs b/benchmarks/StdUnit.Tags.Benchmarks/TagTreeDirtyWriteBenchmarks.cs new file mode 100644 index 0000000..73e4356 --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/TagTreeDirtyWriteBenchmarks.cs @@ -0,0 +1,70 @@ +using System.Threading; +using System.Threading.Tasks; +using BenchmarkDotNet.Attributes; + +namespace StdUnit.Tags.Benchmarks; + +/// +/// 写遍历的框架成本,按"脏节点比例"分档(0% / 1% / 100%)。
+/// 叶子是纯内存假测点:WriteAsync 不做任何设备 IO,所以量的是**框架的派发开销** +/// (遍历 + 每个节点的策略判断 + 调用写方法),不含真实设备的写入耗时。
+/// 实现上不用 [IterationSetup] 重置脏标记(那会把运行策略切成 ColdStart,测出来的不是吞吐): +/// 而是让"脏"叶子用一个永远保持脏的假测点,指标循环里状态恒定。 +///
+[MemoryDiagnoser] +[SimpleJob(warmupCount: 3, iterationCount: 5)] +public class TagTreeDirtyWriteBenchmarks +{ + /// 叶子测点总数(均分到 10 个子组里)。 + [Params(1_000, 10_000)] + public int TagCount { get; set; } + + /// "已脏"的叶子比例。 + [Params(0, 1, 100)] + public int DirtyPercent { get; set; } + + private TagGrp _root = null!; + + [GlobalSetup] + public void Setup() + { + var channel = new BenchChannel(); + _root = new TagGrp(new TagGrpDescriptor { Name = "root" }, channel); + + const int groupCount = 10; + var perGroup = TagCount / groupCount; + var dirtyPerGroup = perGroup * DirtyPercent / 100; + + for (var g = 0; g < groupCount; g++) + { + var group = new TagGrp(new TagGrpDescriptor { Name = $"g{g}" }, channel); + for (var i = 0; i < perGroup; i++) + { + // 脏叶子:WriteAsync 不清脏,所以每轮都会真的被"写"一次; + // 干净叶子:初始就干净,且不会变脏。 + group.AddTag(i < dirtyPerGroup + ? new AlwaysDirtyTag(new TagDescriptor { TagName = $"d{i}" }, channel, group) + : new BenchLeafTag(new TagDescriptor { TagName = $"c{i}" }, channel, group)); + } + + _root.AddTag(group); + } + } + + [Benchmark] + public Task WriteAsync() => _root.WriteAsync(TraversalMode.IgnoreEnabled, CancellationToken.None); + + /// 永远保持脏的叶子:写方法不改变脏标记,因此每轮都会走到"写"分支。 + private sealed class AlwaysDirtyTag : Tag + { + public AlwaysDirtyTag(TagDescriptor descriptor, BenchChannel channel, ITagGrp parent) + : base(descriptor, channel, TagContainer.From(parent)) + { + IsDirty = true; + } + + public override Task ReadAsync(CancellationToken ct) => Task.CompletedTask; + + public override Task WriteAsync(CancellationToken ct) => Task.CompletedTask; + } +} \ No newline at end of file diff --git a/benchmarks/StdUnit.Tags.Benchmarks/TagTreeTraversalBenchmarks.cs b/benchmarks/StdUnit.Tags.Benchmarks/TagTreeReadBenchmarks.cs similarity index 98% rename from benchmarks/StdUnit.Tags.Benchmarks/TagTreeTraversalBenchmarks.cs rename to benchmarks/StdUnit.Tags.Benchmarks/TagTreeReadBenchmarks.cs index f7070d7..5f0e5db 100644 --- a/benchmarks/StdUnit.Tags.Benchmarks/TagTreeTraversalBenchmarks.cs +++ b/benchmarks/StdUnit.Tags.Benchmarks/TagTreeReadBenchmarks.cs @@ -12,7 +12,7 @@ namespace StdUnit.Tags.Benchmarks; /// [MemoryDiagnoser] [SimpleJob(warmupCount: 3, iterationCount: 5)] -public class TagTreeTraversalBenchmarks +public class TagTreeReadBenchmarks { /// 叶子测点总数(均分到 10 个子组里)。 [Params(1_000, 10_000)] diff --git a/benchmarks/StdUnit.Tags.Benchmarks/TraversalBreakdownBenchmarks.cs b/benchmarks/StdUnit.Tags.Benchmarks/TraversalBreakdownBenchmarks.cs index 883de78..2b90ec0 100644 --- a/benchmarks/StdUnit.Tags.Benchmarks/TraversalBreakdownBenchmarks.cs +++ b/benchmarks/StdUnit.Tags.Benchmarks/TraversalBreakdownBenchmarks.cs @@ -116,6 +116,25 @@ public async Task UnionReadAsync() } } + /// + /// 扁平索引 + 直接读 :在 runner 里预先收集所有可写节点的做法, + /// 每次判脏只需一次数组遍历 + 一次属性读,不做字典递归。 + /// + [Benchmark] + public int IsDirty_DirectArray() + { + var n = 0; + foreach (var tag in _tags) + { + if (tag.IsDirty) + { + n++; + } + } + + return n; + } + /// /// 每轮开头运行器还会调一次 entry.IsDirty():全树干净时要走完所有子节点。 /// 这是"每轮固定成本"里除读之外的另一大块,所以单独量。 diff --git "a/docs/\346\211\251\345\261\225\347\202\271.md" "b/docs/\346\211\251\345\261\225\347\202\271.md" index 66398dc..d9a319f 100644 --- "a/docs/\346\211\251\345\261\225\347\202\271.md" +++ "b/docs/\346\211\251\345\261\225\347\202\271.md" @@ -9,7 +9,7 @@ StdUnit.Tags.Core 硬件无关的核心抽象 + 项目 XML 的 schema └── StdUnit.Tags 项目 / 日志 / 插件 / DI,仍与硬件无关 ├── 驱动包:S7 / ModbusTcp / OpcUaClient / ComScanner / SimpleFiles / Hjzk / ZLan(后者基于 ModbusTcp) - ├── McpServer / BlazorLib 把项目暴露给 AI / 界面 + ├── McpServer / WebUi 把项目暴露给 AI / 界面(原 Blazor.Core 已转维护模式,新界面建议 WebUi) └── RxExtensions / R3Extensions 只依赖 Core,用于订阅测点事件 应用:只引用需要的驱动包 + 接口 + DI 扩展 ``` diff --git "a/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/0. \350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214.md" "b/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/0. \350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214.md" index 33ea3f3..a823af3 100644 --- "a/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/0. \350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214.md" +++ "b/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/0. \350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214.md" @@ -4,7 +4,7 @@ | 文档 | 内容 | |---|---| -| **本文** | 范围边界、模型与运行期契约、性能取舍、已知限制、尚未定稿 | +| **本文** | 范围边界、模型与运行期契约、性能取舍、已知限制、尚未定稿、已评估但不做 | | [1. CI](./1.%20CI.md) | CI/OS 取舍、Linux 上跑 net472(mono)、测试的跨平台与稳定性 | | [2. 兼容与命名](./2.%20兼容与命名.md) | 破坏性变更、兼容残留(保留/移除/推迟) | | [3. 打包与发布](./3.%20打包与发布.md) | 版本通道(正式/迭代)、破坏性变更代价、发布流程、包元数据与授权、依赖版本策略 | @@ -34,6 +34,9 @@ API 细节见教程站点()。 - **一个通道实例只能属于一个入口**,由默认开启的 `EntryChannelExclusivityValidator` 强制。理由不只是"断开互相踩"(连接动作可以是空实现,如 SimpleFiles):两套扫描周期会交错读写同一底层资源,两个入口的生命周期也被耦合;而要求分离的代价几近为零——再声明一个指向同一设备的 `Channel` 即可。 - 因此**"单通道多入口并发"明确不做**:它已经不是潜在缺陷,而是"有明确报错的既定约束"。真要做,必须先放弃上面这条设计(见 `AGENTS.md` 约束 3),代价远大于收益。 - **只有最外层入口才是入口**:`ScanEntries` 遇到入口即停止下探,嵌套 `isEntry="true"` 不生效(该子树由外层入口轮询),错误配置由默认开启的 `NestedEntryValidator` 拒绝。 +- **驱动不需要自己防"连接/断开并发"**:上面两条合起来就推出了这个结论——通道与入口一一对应,入口内部每轮是一条单链 `await`(`EnsureConnectedAsync` 循环 → 处理写意图 → 写 → 读 → 逻辑 → 写),断开只发生在循环退出之后(崩溃/取消清理)或停机超时兜底,而超时兜底后的新启动会被 `OnStartingException` 拒绝。所以 `EnsureConnectedAsync` 与 `DisconnectAsync` 在模型内不会并发。 + - 推论:为"可能的并发"加的信号量、以及"`SemaphoreSlim` 没 `Dispose` 会泄漏"这两类担心都不成立(`SemaphoreSlim.Dispose()` 只有在访问过 `AvailableWaitHandle` 时才真正释放内核对象)。**再提"驱动连接要加互斥"时,先回到本节。** + - 驱动真正要守的是另一件事:**`Dispose()` 与 `DisconnectAsync()` 必须是同一条释放路径**,且**无条件释放**——不要用 `TcpClient.Connected` / `Session.Connected` 当守卫,它只是上次 I/O 的快照,半死连接上返回 `false`,恰好把最该关的句柄留了下来。 - **加载期校验器默认开启、XSD 校验默认关闭**:跨引用、驱动工厂、入口通道独占、嵌套入口这 4 个"代码校验器"在 `UseDefaults = true` 下默认生效(它们只拒绝**确定错误**的配置,且错误信息带完整路径);XSD 校验是 opt-in(`EnableXmlSchemaValidation()`),因为"配置合法但语义不对"才是主要失效模式,且它需要显式引入 schema。 ### 观测方式:事件驱动,不要跨线程读字段 @@ -94,7 +97,41 @@ API 细节见教程站点()。 - **只做"显然该做"的优化,并说清量级**。例:OpcUa 每轮都要"子测点 ↔ NodeId"映射 → 改为按子节点集合懒构建缓存(读/写共用),并做数量校验(万一加载后增删子节点就重建,而不是静默错位)。省下的是 LINQ/字符串哈希/两次 `List` 分配,**相对一次 OPC UA 往返(ms 级)可以忽略**;收益是"不再每轮做显然重复的事"与减少 GC 压力,不是吞吐瓶颈。 - **两趟遍历有意保留**(先写完整个缓存再逐点通知):与 `TagCbnt.NotifyChildrenRead()` 语义一致——处理器里读同组其它测点不该看到半更新的缓存;合并省下的开销可忽略。 -- 已知的优化空间(未做)见 `backlog.md`(Modbus cache 复用、S7 真异步与 `Span`)。 +- **遍历与通知路径必须零分配,且不要在热点路径上做委托调用**(2026-11 三轮修复,都是行为等价的): + 1. `TagUnionExtensions.ReadAsync/WriteAsync` 原先用 `TagUnion.Map` 传三个 `async` 闭包,单节点约 220 B + (闭包 + 委托 + 状态机),1 万点位**每轮 2.19 MB**;改用 `switch`。 + 2. `TagGrp.Children` / `TagCbnt.Children` 是 `IDictionary`,`foreach` 走接口会**装箱 `Dictionary.Enumerator`**, + 而它在每轮的读、写、判脏与通知路径上。改为内部存具体 `Dictionary`、公开属性仍返回 `IDictionary`(API 不变)。 + 3. `SearchAccessMode` 原来用 `TagContainer.Map` + 两个委托,且每点位要查**两次**(R1W 判定 + `IsWriteOnly`); + 改为 `TagContainer.AccessMode` 的 `switch`、只查一次,并给 `ReadAsync` 加"读同步完成就不进 async 机制"的快路径。 + 4. **`access` 的继承修正为逐级冒泡**:此前只有 `ITagGrp` 沿父链递归,`ITag`/`ITagCbnt` 只查"直接父级自己配了没", + `Grp(RO) → Cbnt(未配) → Tag` 会被判成 `RW`。这是**语义修正**,不是性能优化。 + 同时因为**访问模式是配置期属性**(加载后不再变化),解析结果缓存在 `TagUnion.CachedAccessMode` 上: + 每节点一生只解析一次,热路径只剩空值检查。**运行期修改 `Descriptor.AccessMode` 不生效,需重新加载项目。** + 结果:遍历 `1 000 → 8.7 µs / 0 B`、`10 000 → 94 µs / 0 B`(每点 8.7–9.4 ns); + 组合分发 `5 000 子测点 → 12.8 µs / 逐点零分配`。 + 规则:**热点路径不要用 `Map` + 闭包/委托做分派或取值,也不要用 `IDictionary` 接口去 `foreach`**。 +- **每轮的存活探测必须是非阻塞的**:Modbus 的 `Connected` 原先用 `Socket.Poll(1000, SelectRead)` 判断链路, + 而 Windows 的计时器粒度约 15.6 ms —— 空闲连接上这一步实测 **15.9 ms/次**,且发生在每轮、每个通道的 + `EnsureConnectedAsync` 里(100 Hz 扫描根本不可能达成)。改为 `Poll(0)`(判定逻辑不变:`Poll && Available == 0`)后 + 降到 **2.3 µs**。规则:**每轮路径上不要用带超时的 `Poll`/`select` 做探测**;要么非阻塞,要么靠"读失败 → 崩溃 → 重连"。 + 基准见 `EnsureConnectedBenchmarks`。 +- **运行器的判脏走扁平索引,且干净时不要空写**:`TagGrpRunner` 每次(重)启动时把入口子树的 + `ITag` / `ITagCbnt` 收进 `DirtyNodeIndex`(两个数组),每轮判脏从"递归走 `Children` + `TagUnion` 分发" + (5.2 ns/点)降到两次数组扫描(2.6 ns/点);干净时**不再执行那趟必然空转的 `WriteAsync`**(10k 点位约 81 µs)。 + 两条约束:① 正确性依据是 `ITagGrp.IsDirty()` 与 `WriteAsync` 的**一致性契约**—— + "`IsDirty()` 为 false 时 `WriteAsync` 不得写入任何东西;只要子树里存在待写节点 + (`ITag` 或 `ITagCbnt` 自身的 `IsDirty`)就必须为 true"(已写进接口注释)。 + 注意它**不是**"父脏必有脏子":`ITagCbnt.IsDirty` 可以独立为 true(整块缓存重写), + 而索引收录的正是 Tag 与组合本身,所以这种情形不会被漏掉。实现违反契约会让"该写的没写",且没有编译错误; + ② 树结构假定加载后不变(索引随 `CollectChannels()` 同周期重建)。 +- **S7 地址解析的正则提升为静态只读**:原先每次 `Parse` 都 `new Regex(...)`(实测约 10 KB + 5 µs/次), + 而解析发生在每轮读写上。静态化后单次读 6.2 µs/10.49 KB → **596 ns/832 B**。 + 这 832 B 只影响**直读点位**(`DirectTag`,兜底用法);正常把点位组织成 `TagCbnt` 时地址只解析一次加载, + 所以不再继续优化(去正则改 span 手写解析的收益只落在这条兜底路径上)。 +- 这组数字都可用 `benchmarks/StdUnit.Tags.Benchmarks` 复现(`TagTreeReadBenchmarks` / `TagTreeDirtyWriteBenchmarks` / `CbntFanOutBenchmarks` / + `S7ChannelReadBenchmarks`;常驻内存用 `--footprint`);基准**不**进 CI,只作改动前后的对比工具。 +- 已知的优化空间(未做)见 `backlog.md`(Modbus cache 复用)。S7 的读写已经改成了"调用方提供缓冲区 + `Span`"的零拷贝实现;但连接/断开的"真异步"已评估、决定不做,理由见第五节。 ## 四、已知限制 @@ -110,3 +147,24 @@ API 细节见教程站点()。 - 是否需要 `TagSnapshot`(值 + 时间戳的一致读取)。 - 是否需要 `System.Diagnostics.Metrics` 观测(每轮耗时、失败次数、重连次数、意图被拒次数)。 - 是否需要"写后读回校验"选项。 + +### 已评估、决定不做(2026-11) + +记在这里的理由是"别再被提出来一次";其中若有哪条被推翻,请改本节而不是只改 backlog。 + +- **热重载 `ReloadAsync(root)`**:它要解决的事其实就是 `StopAsync` 接 `StartPollAsync`,没有独立价值,不再单列 API。 +- **S7 连接/断开的"真异步"**:收益极低——PLC 的并发吞吐远小于上位机,且入口内部本来就是串行轮询; + 2026-11 起 `Thread` 包装也已删掉(连接/断开就是同步调用,有界由 Sharp7 自己的超时保证),读/写则是 + "调用方提供缓冲区 + `Span`"的零拷贝同步实现。**不要**再为它们引入异步 I/O 抽象。 +- **Modbus 读路径 cache 复用**(把 `IModbusRegisterChannel.ReadRegistersAsync` / `IModbusBitsChannel.ReadBitsAsync` + 改成"写入调用方预分配 buffer"):2026-11 用基准量过(`benchmarks/StdUnit.Tags.Benchmarks`,桩通道 + `[MemoryDiagnoser]`): + + | 每轮寄存器数 | 现状(通道返回新数组) | 复用 Cache | 耗时差 | + |---|---|---|---| + | 32 | 160 B | 72 B | 无可测差异(~31 ns vs ~31 ns) | + | 125 | 352 B | 72 B | 无可测差异(~38 ns vs ~30 ns,抖动大于差距) | + + 按 100 Hz、单入口估算,省下的是 9–28 KB/s —— 相对一次 Modbus TCP 往返(ms 级,且 NModbus 自己还有缓冲分配) + 可以忽略;代价却是**公开接口签名变更**(net472 没有默认接口方法兜底)。结论:不做。 + (基准里剩下的 72 B 是 `Task` 与通知路径的固定开销,与 cache 复用无关。) +- **公开面基线(`PublicApiAnalyzers` / 反射快照测试)**:前者因额外依赖不引入,后者因"关键保证要零反射可验证"的 AOT 取向不采用;详见 `backlog.md` 第二节。 diff --git "a/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/2. \345\205\274\345\256\271\344\270\216\345\221\275\345\220\215.md" "b/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/2. \345\205\274\345\256\271\344\270\216\345\221\275\345\220\215.md" index c4cd863..fb1af15 100644 --- "a/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/2. \345\205\274\345\256\271\344\270\216\345\221\275\345\220\215.md" +++ "b/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/2. \345\205\274\345\256\271\344\270\216\345\221\275\345\220\215.md" @@ -14,10 +14,14 @@ ## 二、明确保留的兼容残留 -部分早已标记废弃的代码和`typo`问题,理论上可以在`1.0`移除,但是考虑到已经在生产现场使用,所以决定**暂时先不移除**,留待在`2.0`移除: +部分早已标记废弃的代码和`typo`问题,理论上可以在`1.0`移除,但是考虑到已经在生产现场使用,所以决定**暂时先不移除**。 -- `ITagsProject.WriteIntent(string, TagGrpWriteIntent)` 的 `[Obsolete]` 2 参重载(本仓库零调用,但库外有真实调用方)。 -- ComScanner 的旧元素名 `` 的兼容解析(XSD 已把该写法标为非法,新配置请写 ``)。 +**2.0 复查结论(2026-11):这两项仍然不移除。** 移除它们换来的只是"公开面更干净",代价却是给现场再制造一次破坏性变更; +它们都没有实际维护成本,因此**不设移除时间点**,也不再为它们去凑"下一个大版本窗口"。 + +- `ITagsProject.WriteIntent(string, TagGrpWriteIntent)` 的 `[Obsolete]` 2 参重载(本仓库零调用,但库外有真实调用方): + 它只是一层转发,零维护成本。 +- ComScanner 的旧元素名 `` 的兼容解析(XSD 已把该写法标为非法,新配置请写 ``):只是一段 fallback。 ## 三、已在 1.1 里改掉的(仅 `StdUnit.Tags.ModbusTcp`) diff --git "a/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/3. \346\211\223\345\214\205\344\270\216\345\217\221\345\270\203.md" "b/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/3. \346\211\223\345\214\205\344\270\216\345\217\221\345\270\203.md" index 6b3e197..b0be7e7 100644 --- "a/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/3. \346\211\223\345\214\205\344\270\216\345\217\221\345\270\203.md" +++ "b/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/3. \346\211\223\345\214\205\344\270\216\345\217\221\345\270\203.md" @@ -38,9 +38,14 @@ dotnet nuget add source <解压目录> -n stdunit-dev ## 三、发布流程 -- 版本号**不写在 csproj 里**,由 `src/publish-packages.ps1` 在打包时以 `-p:PackageVersion=…` 注入: +- 版本号**不写在 csproj 里**,由 `src/publish-packages.ps1` 在打包时注入**两个**属性: + `-p:PackageVersion=…`(包版本)与 `-p:InformationalVersion=…`(程序集里的版本信息)。 + 后者不注入的话会默认派生自 `$(Version)`(恒为 `1.0.0`),于是每个版本发布出去的 DLL 都自称 `1.0.0`—— + 崩溃日志、`dotnet-counters` / OTel 的 scope、任何读 `AssemblyInformationalVersion` 的地方都会拿到错值。 + **只设 `InformationalVersion`、不动 `Version`**,是为了让 `AssemblyVersion` 稳定在 `1.0.0.0`: + 程序集身份不随补丁版跳动,net472 的绑定重定向也不用跟着改。实测结果为 `<包版本>+`(SDK 仍会追加源码版本)。 - **正式发布**:`release-nuget.yml` / `release-baget.yml` 的 `workflow_dispatch` 输入 `releaseVersion` - → `-packageVersion <语义化版本>`,对 13 个项目逐个 `dotnet pack -c Release -p:PackageVersion=…` + `nuget push`。 + → `-packageVersion <语义化版本>`,对 13 个项目逐个 `dotnet pack -c Release -p:PackageVersion=… -p:InformationalVersion=…` + `nuget push`。 号由人显式给,不从文件推断(nuget.org 上的版本不可撤销,且"这次算 minor 还是 major"本身就是兼容性决策)。 - **迭代产物(dev 通道)**:CI 只传构建号 `-DevBuildNumber "."`,基础版本读仓库根的 `next-release-version.txt`(单行,如 `2.0.0`),拼成 `<基础版本>-dev.<构建号>`。这样"下一个计划发布的正式号" @@ -58,7 +63,7 @@ dotnet nuget add source <解压目录> -n stdunit-dev - `-SkipPush` 可只打包不推送(发版前验证产物),此时不再要求 source/key; - `nuget push` 带 `--skip-duplicate`:发布中途失败后重跑,不会因为"包已存在"再挂一次。 - 新增会被发布的包时:把项目名加进 `src/publish-packages.ps1` 列表,并在自己 csproj 里写一行 ``。 -- `StdUnit.Tags.BlazorLib` **有意不在列表内**:它只是实验场(各驱动的编辑器/设计器实现),暂不对外发布,详见 README 的备注。 +- `StdUnit.Tags.BlazorLib` 已在 2.0 移除(实验场,各驱动的编辑器/设计器实现,从未对外发布);它的能力由 `StdUnit.Tags.WebUi` 的设计器承接。`BlazorLib.Core` 仍在列表内,但进入**维护模式**(只修 bug,不加新功能)。 ## 四、包元数据 diff --git a/src/StdUnit.Tags.Core/TagGrps/ITagGrp.cs b/src/StdUnit.Tags.Core/TagGrps/ITagGrp.cs index dbb8c10..68e621a 100644 --- a/src/StdUnit.Tags.Core/TagGrps/ITagGrp.cs +++ b/src/StdUnit.Tags.Core/TagGrps/ITagGrp.cs @@ -98,7 +98,12 @@ public interface ITagGrp /// - /// 是否有脏数据 + /// 是否有脏数据。
+ /// 契约(与 WriteAsync 的一致性):返回 false 时,WriteAsync 不得写入任何东西; + /// 只要子树里存在待写节点( 或 自身的 IsDirty 为 true),就必须返回 true。
+ /// 注意它不是"父脏必有脏子": 可以独立为 true(整块缓存重写), + /// 此时子测点可以全是干净的。运行器据此用扁平索引判脏(收录的正是 Tag 与组合本身), + /// 违反本契约会导致"该写的没写",且不会有任何编译错误。 ///
/// bool IsDirty(); diff --git a/src/StdUnit.Tags/TagGrpRunners/DirtyNodeIndex.cs b/src/StdUnit.Tags/TagGrpRunners/DirtyNodeIndex.cs new file mode 100644 index 0000000..eb186ad --- /dev/null +++ b/src/StdUnit.Tags/TagGrpRunners/DirtyNodeIndex.cs @@ -0,0 +1,79 @@ +using System.Collections.Generic; + +namespace StdUnit.Tags; + +/// +/// 入口子树的"可写节点"扁平索引,把每轮判脏从"递归走 Children + TagUnion 分发"降为"扫两个数组"。
+/// 只收录 与 ——这两类正是写单元:WriteAsync 只看它们各自的 +/// IsDirty 决定是否写;组合本身可以独立为脏(整块缓存重写),所以必须收录。
+/// 树结构假定加载后不变;索引在运行器每次(重)启动时重建。 +///
+internal sealed class DirtyNodeIndex +{ + private readonly ITag[] _tags; + private readonly ITagCbnt[] _cbnts; + + private DirtyNodeIndex(ITag[] tags, ITagCbnt[] cbnts) + { + this._tags = tags; + this._cbnts = cbnts; + } + + /// + /// 收集入口子树中的全部 Tag / Cbnt(不区分是否使能——IsDirty() 本来也不看使能)。
+ /// 索引的正确性建立在 与 WriteAsync 的一致性契约上: + /// "返回 false 时写不得有任何动作;只要存在待写节点就必须返回 true"。 + /// 注意它不是"父脏必有脏子"——组合自身的脏也在收录范围内,因此不会漏。 + ///
+ public static DirtyNodeIndex Build(ITagGrp entry) + { + var tags = new List(); + var cbnts = new List(); + Collect(entry, tags, cbnts); + return new DirtyNodeIndex(tags.ToArray(), cbnts.ToArray()); + } + + /// + /// 是否有任一节点已脏。分两个数组扫描是为了避免对 做类型分发 + /// (实测 10k 节点:直接读 ITag.IsDirty 约 2.6 ns/点,经 TagUnion 约 5.2 ns/点)。 + /// + public bool AnyDirty() + { + foreach (var tag in this._tags) + { + if (tag.IsDirty) + { + return true; + } + } + + foreach (var cbnt in this._cbnts) + { + if (cbnt.IsDirty) + { + return true; + } + } + + return false; + } + + private static void Collect(ITagGrp grp, List tags, List cbnts) + { + foreach (var child in grp.Children.Values) + { + switch (child) + { + case TagUnion.TagUnit unit: + tags.Add(unit.Value); + break; + case TagUnion.TagCbnt cbnt: + cbnts.Add(cbnt.Value); + break; + case TagUnion.TagGrp nested: + Collect(nested.Value, tags, cbnts); + break; + } + } + } +} diff --git a/src/StdUnit.Tags/TagGrpRunners/TagGrpRunner.cs b/src/StdUnit.Tags/TagGrpRunners/TagGrpRunner.cs index aac631d..a15a474 100644 --- a/src/StdUnit.Tags/TagGrpRunners/TagGrpRunner.cs +++ b/src/StdUnit.Tags/TagGrpRunners/TagGrpRunner.cs @@ -73,6 +73,8 @@ public virtual async Task StartAsync(ITagGrp entry, CancellationToken ct) channel = entry.SearchChannel(); channels = entry.CollectChannels(); + // 判脏索引:与 CollectChannels 同生命周期(每次外层重启用重建),把每轮判脏变成两次数组扫描。 + var dirtyIndex = DirtyNodeIndex.Build(entry); // 单槽回调:先取本地再判空,避免两次读取之间被改成 null。 var onStarted = this.RunnerStarted; if (onStarted is not null) @@ -102,7 +104,7 @@ public virtual async Task StartAsync(ITagGrp entry, CancellationToken ct) } await this.DrainWriteIntentsAsync(entry, ct); - if (entry.IsDirty()) + if (dirtyIndex.AnyDirty()) { await entry.WriteAsync(TraversalMode.RespectEnabled, ct); } @@ -112,7 +114,12 @@ public virtual async Task StartAsync(ITagGrp entry, CancellationToken ct) { await onTurn(entry, channel, ct); } - await entry.WriteAsync(TraversalMode.RespectEnabled, ct); + + // 逻辑处理之后再判一次:干净时整趟跳过(WriteAsync 对干净节点本来也是空操作)。 + if (dirtyIndex.AnyDirty()) + { + await entry.WriteAsync(TraversalMode.RespectEnabled, ct); + } sw.Stop(); TagsMetric.RecordTurn(metricTags, sw.Elapsed); diff --git a/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/DirtyNodeIndexTests.cs b/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/DirtyNodeIndexTests.cs new file mode 100644 index 0000000..0715521 --- /dev/null +++ b/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/DirtyNodeIndexTests.cs @@ -0,0 +1,119 @@ +using StdUnit.Tags.Tests.Fakes; +using Xunit; + +namespace StdUnit.Tags.Tests.Core.TagGrpRunners; + +/// +/// 与 的等价性:索引只收录 Tag / Cbnt, +/// 正是 IsDirty() 的语义;任何一处不一致都会让运行器"该写的没写"或"白走一趟"。 +/// +public class DirtyNodeIndexTests +{ + private static TagGrp NewGroup(string name) => + new(new TagGrpDescriptor { Name = name }, new FakedChannel(new TagChannelDescriptor { Name = "ch" })); + + private static FakedTag NewTag(string name, ITagGrp parent) => + new(new TagDescriptor { TagName = name }, new FakedChannel(new TagChannelDescriptor { Name = "ch" }), parent); + + private static FakedTagCbnt NewCbnt(string name) => new(new TagCbntDescriptor { Name = name }); + + private static void AssertEquivalent(ITagGrp entry) + { + var index = DirtyNodeIndex.Build(entry); + Assert.Equal(entry.IsDirty(), index.AnyDirty()); + } + + [Fact] + public void EmptyEntry_IsClean() + { + var entry = NewGroup("entry"); + var index = DirtyNodeIndex.Build(entry); + + Assert.False(index.AnyDirty()); + AssertEquivalent(entry); + } + + [Fact] + public void DirtyTag_IsDetected() + { + var entry = NewGroup("entry"); + var tag = NewTag("t", entry); + entry.AddTag(tag); + + var index = DirtyNodeIndex.Build(entry); + Assert.False(index.AnyDirty()); + + tag.IsDirty = true; + Assert.True(index.AnyDirty()); + AssertEquivalent(entry); + + tag.IsDirty = false; + Assert.False(index.AnyDirty()); + AssertEquivalent(entry); + } + + [Fact] + public void DirtyCbnt_IsDetected() + { + var entry = NewGroup("entry"); + var cbnt = NewCbnt("c"); + entry.AddTag(cbnt); + + var index = DirtyNodeIndex.Build(entry); + Assert.False(index.AnyDirty()); + + cbnt.IsDirty = true; + Assert.True(index.AnyDirty()); + AssertEquivalent(entry); + } + + [Fact] + public void DirtyTag_InNestedGroup_IsDetected() + { + var entry = NewGroup("entry"); + var inner = NewGroup("inner"); + entry.AddTag(inner); + var tag = NewTag("t", inner); + inner.AddTag(tag); + + var index = DirtyNodeIndex.Build(entry); + Assert.False(index.AnyDirty()); + + tag.IsDirty = true; + Assert.True(index.AnyDirty()); + AssertEquivalent(entry); + } + + [Fact] + public void MixedTree_StaysEquivalent() + { + var entry = NewGroup("entry"); + var t1 = NewTag("t1", entry); + var c1 = NewCbnt("c1"); + var nested = NewGroup("nested"); + var t2 = NewTag("t2", nested); + entry.AddTag(t1); + entry.AddTag(c1); + entry.AddTag(nested); + nested.AddTag(t2); + + var index = DirtyNodeIndex.Build(entry); + + Assert.False(index.AnyDirty()); + AssertEquivalent(entry); + + c1.IsDirty = true; + Assert.True(index.AnyDirty()); + AssertEquivalent(entry); + + c1.IsDirty = false; + t2.IsDirty = true; + Assert.True(index.AnyDirty()); + AssertEquivalent(entry); + + t2.IsDirty = false; + t1.IsDirty = true; + Assert.True(index.AnyDirty()); + AssertEquivalent(entry); + } +} diff --git a/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/TagGrpRunnerTests.cs b/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/TagGrpRunnerTests.cs index dd8eb72..e5638bb 100644 --- a/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/TagGrpRunnerTests.cs +++ b/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/TagGrpRunnerTests.cs @@ -43,6 +43,23 @@ private async Task RunUntilCancelled(TagGrpRunner runner, ITagGrp entry, Cancell } } + /// + /// 往 mock 入口挂一个子测点。MockTagGrp.IsDirty() 按 的契约汇总子节点, + /// 所以"入口是否脏"必须通过子节点表达。 + /// + private static FakedTag AddTag(MockTagGrp entry, bool dirty = false) + { + var tag = new FakedTag( + new TagDescriptor { TagName = $"t{entry.Children.Count}" }, + new FakedChannel(new TagChannelDescriptor { Name = "ch" }), + entry) + { + IsDirty = dirty, + }; + entry.Children.Add(tag.TagName(), new TagUnion.TagUnit(tag)); + return tag; + } + [Fact] public async Task StartAsync_NormalLoop_CallsReadWriteAndEvents() { @@ -50,6 +67,7 @@ public async Task StartAsync_NormalLoop_CallsReadWriteAndEvents() var (runner, entry, _, _) = CreateRunner(); entry.Descriptor!.ScanInterval = 20; entry.IsEnabled = true; + AddTag(entry, dirty: true); // 有脏数据才会触发写 using var cts = new CancellationTokenSource(); var turnStartedCalled = false; @@ -196,6 +214,8 @@ public async Task StartAsync_TurnProcessEvent_FiresAfterRead() using var cts = new CancellationTokenSource(); var processOrder = new List(); + // 先干净,逻辑处理时才变脏——这样第一次写必然发生在 Read/Process 之后。 + var tag = AddTag(entry); entry.OnRead = () => processOrder.Add("Read"); entry.OnWrite = () => processOrder.Add("Write"); @@ -203,6 +223,7 @@ public async Task StartAsync_TurnProcessEvent_FiresAfterRead() runner.TurnProcess += (grp, ch, _) => { processOrder.Add("Process"); + tag.IsDirty = true; cts.Cancel(); return Task.CompletedTask; }; @@ -226,7 +247,7 @@ public async Task StartAsync_IsDirty_CallsWriteBeforeRead() var (runner, entry, _, _) = CreateRunner(); entry.Descriptor!.ScanInterval = 20; entry.IsEnabled = true; - entry.IsDirtyReturn = true; + AddTag(entry, dirty: true); using var cts = new CancellationTokenSource(); var callOrder = new List(); @@ -960,7 +981,6 @@ public bool IsEnabled /// 如果不为 null,则 ReadAsync 会抛出此异常。 ///
public Exception? ReadAsyncThrows { get; set; } - public bool IsDirtyReturn { get; set; } public Action? OnRead { get; set; } public Action? OnWrite { get; set; } @@ -982,7 +1002,19 @@ public Task WriteAsync(TraversalMode mode, CancellationToken ct) return Task.CompletedTask; } - public bool IsDirty() => IsDirtyReturn; + /// 按契约实现:等价于"子树中任一 Tag/Cbnt 已脏",组自身不持有脏标记。 + public bool IsDirty() + { + foreach (var child in this.Children.Values) + { + if (child.IsDirty()) + { + return true; + } + } + + return false; + } } private class MockProject : ITagsProject From 07392344cbacb62ee7181aaf9818d12eedb111db Mon Sep 17 00:00:00 2001 From: newbienewbie Date: Thu, 12 Nov 2026 11:07:01 +0800 Subject: [PATCH 10/17] fix CI yml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit yml这个东西实实在在说明了流行不等于优秀 --- .github/workflows/dotnet.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/dotnet.yml b/.github/workflows/dotnet.yml index a2fc699..b351cf5 100644 --- a/.github/workflows/dotnet.yml +++ b/.github/workflows/dotnet.yml @@ -52,7 +52,7 @@ jobs: # 回归要等发版当天才发现。AOT job 已在 Linux 上跑 AspNetCore,因此这里放 ubuntu 没有平台障碍。 # 与主测试**分两步顺序跑**(理由同 release 工作流):`dotnet test` 直接打解决方案会并行拉起多个 testhost, # 4 vCPU 的 CI runner 上会把"机器忙"变成随机红。 - - name: Test with Coverage (net8.0-only: BlazorLib.Core / WebUi) + - name: Test with Coverage (net8.0-only BlazorLib.Core / WebUi) run: dotnet test tests/StdUnit.Tags.Tests.NetCoreOnly/StdUnit.Tags.Tests.NetCoreOnly.csproj -f net8.0 -c Release --no-build --nologo --collect:"XPlat Code Coverage" --results-directory ./TestResults - name: Upload Coverage to Codecov From ef305a5b98d93ec6a79c7fcad84630479cc86a6d Mon Sep 17 00:00:00 2001 From: newbienewbie Date: Thu, 12 Nov 2026 21:10:36 +0800 Subject: [PATCH 11/17] =?UTF-8?q?=E7=8E=B0=E5=9C=A8=E5=B7=B2=E7=BB=8F?= =?UTF-8?q?=E6=8A=8A=E8=AD=A6=E5=91=8A=E8=A7=86=E4=B8=BA=E9=94=99=E8=AF=AF?= =?UTF-8?q?=EF=BC=8C=E7=A6=81=E7=94=A8=E7=B1=BB=E5=BA=93=E5=B1=82=E9=9D=A2?= =?UTF-8?q?=E7=9A=84=20NuGetAudit=20=E6=9D=A5=E9=81=BF=E5=85=8D=E6=8A=AC?= =?UTF-8?q?=E5=8D=87=E5=BC=80=E5=8F=91=E8=80=85=E4=BE=9D=E8=B5=96=E7=89=88?= =?UTF-8?q?=E6=9C=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/Directory.Build.props | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/Directory.Build.props b/src/Directory.Build.props index 9cd2e26..9ba7435 100644 --- a/src/Directory.Build.props +++ b/src/Directory.Build.props @@ -15,6 +15,8 @@ enable enable true + + false