Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 52 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,58 @@

本文件记录**用户可见**的变化。版本号遵循[语义化版本](https://semver.org/lang/zh-CN/) `<major>.<minor>.<patch>`。

## 2.0.0-beta7(尚未发布)

## 2.0.0-beta8(尚未发布)

> 本批仍是 `2.0.0` 的预发布——`2.0.0` 正式版保持未发布。

StdUnit.Tags / StdUnit.Tags.Core: **项目级启停的确定化(`State` / `RunId` / 配对保证)**
- `ITagsProjectCtrl` 新增 `State`(`TagsProjectState`:`Stopped` / `Starting` / `Running` / `Stopping`)
与 `RunId`(每次启动递增)。**"已就绪"的唯一可靠判据是 `State == Running && Project is { }`**:
`Project` 在 `hook` 执行**之前**就已赋值(那时是 `Starting`),单看 `Project != null` 会早于就绪,
旧文档里"等 `Project != null` 就去 `StopAsync` 会与 hook 竞态"正是这个原因。
- `TagsProjectEventArgs` 新增 `State` / `RunId` / `Failure`,**移除** `IsStarted` 属性,改为扩展方法
`TagsProjectEventArgsExtensions.IsStarted()`(等价于 `State == Running`),另提供
`IsStarted(out ITagsProject project)`:判定与取项目一步完成(返回 `true` 时 `project` 必定可用,
返回 `false` 时它是 `null`)。构造函数也改为只接收 `State`(不再有 `bool isstarted` 版本):
事件参数里只有一个"真相",自定义实现与测试替身都不会造出"bool 与 State 各说各话"的参数。
- **配对保证**:只要派发过一次"已启动",本次运行结束前**必定**派发一次、且只有一次"已停止",两者 `RunId` 相同。
**运行中**异常结束(如 `RunAsync` 抛错)补发"已停止"并带 `Failure`;`RunAsync` 自行正常返回同样补发(`Failure` 为 null)。
**启动阶段就失败**(`MakeProject` / `hook` 抛错)的运行没有"已启动",因此也不会补"已停止"——配对约束的是
"对外宣告过的运行",不是"每次 `StartPollAsync` 都有回执"。此前这些路径只释放项目、不发事件,
观察者会永远停在"已启动",且通道不会被断开——现在收尾统一:释放项目 → 断开通道 → 派发"已停止"。
- **停机引起的取消不算失败**:`StopAsync` 触发的 `OperationCanceledException`(取决于 runner 是"正常返回"还是
"抛 OCE")既不会让 `StartPollAsync` 外抛,也不会写进 `Failure`。判据与 `RunnerCrashed` 一致——看"令牌确实已取消",
驱动自身原因抛的 `OCE` 仍算失败。
- **`StopAsync()` 在未运行时是空操作**:不再凭空派发"已停止";重复调用也只派发一次。
- **订阅者异常不再影响启停**:`StartedOrStopped` 改为逐个订阅者 `try/catch` + Error 日志,后续订阅者仍会收到通知。
此前"已启动"在 `StartPollAsync` 的 `try` 内派发,任一观察者抛异常都会**导致项目启动失败**。这与
`RunnerStarted` 的 fast-fail 语义刻意不同:项目级观测是纯旁路,要参与启动的初始化请用 `hook`。
- `OnStartingException` 改为**先取快照再调用**,启动过程中替换该属性不会引发二次读取。
- 新增 `ITagsProjectCtrl.TryGetRunning(out ITagsProject project, out long runId)`:**一次读取**拿到
"正在运行的项目 + 它的运行标识",且两者必定来自同一次运行。`State` / `Project` / `RunId` 是三个独立属性,
"停止后立刻重启"的窗口里分别读取可能拼出「旧项目 + 新 RunId」;需要配对时(尤其是晚订阅者的补查与去重)
请用本方法。**"是否已就绪"只认它**:不再提供 `GetRunningProject()` 这类"只返回项目"的便捷包装,
避免同一件事出现两种读法、两种语义。
- 自定义 `ITagsProjectCtrl` 实现:需要补上 `State`、`RunId`、`TryGetRunning` 三个成员
(`Stopped` / `0` / 恒返回 `false` 是合理默认)。
- 新增扩展方法 `TagsProjectCtrlAttachmentExtensions.AttachRunningProject(Func<ITagsProject, long, IDisposable>)`:
把"给正在运行的项目挂一段观测"的四件固定杂活收敛成一个方法——**晚挂补偿**(先订阅 `StartedOrStopped`,
再补查 `TryGetRunning`)、**按 `RunId` 去重**、**配对摘除**(停止/换运行时先 `Dispose` 旧句柄)、**加锁串行化**。
没有它时,每个观察者都要抄一遍那十几行样板,且很容易写成"分别读 `RunId` 与 `Project`"的错误版本。

StdUnit.Tags.WebUi: 观测流改用 `AttachRunningProject` + 控制器提供的 `RunId`
- 不再自己维护轮次订阅列表、`OnStartedOrStopped` 分发与 `_transitionGate`:订阅、晚挂补偿、
按 `RunId` 去重、停止/换运行时摘除全部交给 `AttachRunningProject`,hub 只保留"挂上之后做什么"
(建索引、发布状态、逐入口订阅)。`_turnSubscriptions` / `UnsubscribeTurns` / `SyncWithController` 随之删除。
- 心跳里的周期性"对账"不再需要:`StartedOrStopped` 的配对与晚挂补偿已经覆盖那些场景
(`ReconcileInterval` 仍作为心跳 tick 的间隔保留)。
- `epoch` 直接取 `RunId`(`TagsProjectEventArgs.RunId` / `ctrl.RunId`),不再维护私有计数器。
- 行为保持:正常停止发一帧 `started=false`;**换运行时不发**中间的 `stopped`,只发新的 `started`
(`OnDetached` 用 `TryGetRunning` 区分"真停止"与"换运行")。


## 2.0.0-beta7

> 本批仍是 `2.0.0` 的预发布——`2.0.0` 正式版保持未发布。

Expand Down
4 changes: 2 additions & 2 deletions samples/StdUnit.Tags.Web/Components/Pages/Monitor.razor
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
@using System.Collections.ObjectModel
@using System.Collections.ObjectModel
@using System.Reactive.Linq
@using System.Xml.Linq
@using StdUnit.Tags
Expand Down Expand Up @@ -66,7 +66,7 @@
{
var sender = ep.Sender;
var args = ep.EventArgs;
this._project = args.IsStarted ? this.projctrl.Project : null;
this._project = args.IsStarted() ? this.projctrl.Project : null;
this.InvokeAsync(StateHasChanged);
});

Expand Down
4 changes: 2 additions & 2 deletions samples/WpfDemo/MainWindow.xaml.cs
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
using StdUnit.Tags;
using StdUnit.Tags;
using StdUnit.Tags.R3;
using R3;
using System.Windows;
Expand All @@ -19,7 +19,7 @@ public MainWindow()
var app = App.Current as App ?? throw new InvalidCastException("App.Current is not of type App");

var projobs = app.Ctrl.ObserveStartedOrStopped()
.Select(evt => evt.IsStarted ? evt.Project : null)
.Select(evt => evt.IsStarted() ? evt.Project : null)
// 测点项目由后台线程在 Application_Startup 中启动,可能早于本窗口构造;
// StartedOrStopped 是普通事件、不会重放历史记录,因此用当前 Project 作首值兜底。
.Prepend(() => app.Ctrl.Project)
Expand Down
119 changes: 107 additions & 12 deletions src/StdUnit.Tags.Core/Projects/ITagsProjectCtrl.cs
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,28 @@

namespace StdUnit.Tags;

/// <summary>
/// 测点项目的运行状态。<br/>
/// 只有 <see cref="Running"/> 与 <see cref="Stopped"/> 是"稳定态",
/// 也是 <see cref="ITagsProjectCtrl.StartedOrStopped"/> 唯一会派发的两个状态。<br/>
/// <see cref="Starting"/> / <see cref="Stopping"/> 是过渡态,只用于让 <see cref="ITagsProjectCtrl.State"/>
/// 能如实反映"正在启动/正在停止",不会单独派发事件。
/// </summary>
public enum TagsProjectState
{
/// <summary>未运行:从未启动、已停止,或启动失败收尾之后。</summary>
Stopped = 0,

/// <summary>正在启动:项目实例已创建,正在执行 <c>hook</c>,轮询尚未开始。</summary>
Starting = 1,

/// <summary>运行中:<c>hook</c> 已执行完,轮询进行中。此时 <see cref="ITagsProjectCtrl.Project"/> 必不为 <c>null</c>。</summary>
Running = 2,

/// <summary>正在停止:已发出取消,正在等待轮询退出、释放项目、断开通道。</summary>
Stopping = 3,
}

/// <summary>
/// 测点项目控制器接口。
/// 核心方法是<br/>
Expand All @@ -11,25 +33,79 @@ namespace StdUnit.Tags;
public interface ITagsProjectCtrl
{
/// <summary>
/// 测点项目,如果测点项目未启动,则为null
/// 当前运行状态,可随时查询(不依赖事件)。<br/>
/// <b>判断"是否已就绪"请用 <see cref="TryGetRunning"/></b>:
/// <see cref="Project"/> 在 <c>hook</c> 执行之前就已赋值(此时状态是 <see cref="TagsProjectState.Starting"/>),
/// 单看 <c>Project != null</c> 会早于"项目确实已就绪"。
/// </summary>
TagsProjectState State { get; }

/// <summary>
/// 当前(或最近一次)运行的标识:每次 <c>StartPollAsync</c> 递增,与
/// <see cref="TagsProjectEventArgs.RunId"/> 同源。<br/>
/// 用于把"事件"和"事后补查到的状态"对上。<br/>
/// <b>需要与 <see cref="Project"/> 成对使用(判断"现在跑的是哪一次")时,请改用
/// <see cref="TryGetRunning"/>:</b>两个属性是两次独立读取,"停止后立刻重启"的窗口里可能读到
/// 「旧项目 + 新 RunId」这种不一致的组合。
/// </summary>
long RunId { get; }

/// <summary>
/// 一次读取拿到"正在运行的项目 + 它的运行标识",<b>保证两者来自同一次运行</b>。<br/>
/// 返回值等价于"读到的瞬间 <see cref="State"/> 是 <see cref="TagsProjectState.Running"/> 且
/// <see cref="Project"/> 非 null",但状态、项目、运行号是同一次快照读出的,
/// 不存在"分两次读、中间被一次启停插进来"的问题。观察者晚启动、需要补查当前状态时,用它最稳。<br/>
/// <br/>
/// <b>观察者晚于项目启动时,用它补偿</b>:先订阅 <see cref="StartedOrStopped"/>,
/// 再调用本方法一次,覆盖"订阅之前已经发生的变化"。
/// </summary>
/// <param name="project">正在运行的项目</param>
/// <param name="runId">该项目的运行标识,与 <see cref="TagsProjectEventArgs.RunId"/> 同源</param>
/// <returns>当前处于 <see cref="TagsProjectState.Running"/> 时为 <c>true</c></returns>
bool TryGetRunning(out ITagsProject project, out long runId);

/// <summary>
/// 测点项目,<see cref="TagsProjectState.Starting"/> / <see cref="TagsProjectState.Running"/> 时非 null,
/// 其余状态为 <c>null</c>。<br/>
/// <br/>
/// 注意,非<c>null</c>并不意味着项目在执行。要获取当前正在执行的项目,使用<see cref="TryGetRunning"/>。
/// </summary>
ITagsProject? Project { get; }

/// <summary>
/// 当正在启动测点项目时发生异常时的回调。<br/>
/// 返回值表示是否已经处理了异常,如果返回true,则不会再向外层抛出异常。
/// 返回值表示是否已经处理了异常,如果返回true,则不会再向外层抛出异常。<br/>
/// <b>该属性在每次读取时取值</b>:启动过程中被替换不会影响本次启动已取到的委托。
/// </summary>
Func<Exception, Task<bool>>? OnStartingException { get; set; }

/// <summary>
/// 测点项目启动或停止事件
/// 测点项目启动或停止事件。<b>只在两个稳定态上派发</b>(<see cref="TagsProjectState.Running"/> / <see cref="TagsProjectState.Stopped"/>):<br/>
/// <list type="bullet">
/// <item><b>配对由库保证</b>:只要派发过一次"已启动",本次运行结束前<b>必定</b>派发一次"已停止",
/// 两者的 <see cref="TagsProjectEventArgs.RunId"/> 相同。"运行中"异常结束(如 <c>RunAsync</c> 抛错)同样补发,
/// 此时 <see cref="TagsProjectEventArgs.Failure"/> 带异常;正常停机为 <c>null</c>(停机引起的
/// <see cref="OperationCanceledException"/> 也算正常停机)。<b>启动阶段就失败</b>(<c>MakeProject</c> / <c>hook</c> 抛错)
/// 的运行没有"已启动",因此也不会有"已停止"——配对约束的是"对外宣告过的运行",不是"每次 StartPollAsync 都有回执"。</item>
/// <item><b>热事件</b>:只在状态迁移时派发一次,晚订阅者收不到历史通知。
/// 需要"当前是否已启动"请查 <see cref="State"/>,需要"现在就是这个状态"请自行补偿。</item>
/// <item><b>订阅者抛异常不影响启停</b>:逐个 <c>try/catch</c> 并记 Error 日志,后续订阅者仍会收到通知
/// (与 <see cref="ITagsProject.RunnerStarted"/> 的 fast-fail 语义不同——项目级观测是纯旁路,
/// 要参与启动的初始化请用 <c>hook</c>)。</item>
/// <item>派发"已停止"事件时,轮询已退出、项目已释放、通道已断开,<see cref="TagsProjectEventArgs.Project"/> 为 <c>null</c>;
/// 此时可以安全复用通道实例、目录,或替换 XML。</item>
/// </list>
/// </summary>
event TagsProjectStartedOrStopped? StartedOrStopped;

/// <summary>
/// 启动测点项目轮询。<br/>
/// 此方法通常不会结束,除非测点项目被停止或在启动阶段发生异常。<br/>
/// 如果在项目启动阶段就发生异常,则会触发<see cref="OnStartingException"/>回调。<br/>
/// 状态与会话:进入时 <see cref="State"/> 变为 <see cref="TagsProjectState.Starting"/>(此时 <see cref="Project"/> 已非 null、
/// <c>hook</c> 正在执行),<c>hook</c> 完成后变为 <see cref="TagsProjectState.Running"/> 并派发"已启动";
/// 无论正常结束还是异常结束,退出前都会回到 <see cref="TagsProjectState.Stopped"/>,
/// 并且只要派发过"已启动",就必定补派一次"已停止"(异常时 <see cref="TagsProjectEventArgs.Failure"/> 非 null)。<br/>
/// 示例:
/// <example><![CDATA[
/// ctrl.StartPollAsync(dir: "D:\\MyProject", root: null, hook: async (proj, sp, ct) =>{
Expand Down Expand Up @@ -59,7 +135,8 @@ public interface ITagsProjectCtrl
/// 语义:<b>发取消信号 → 等待轮询循环退出(有界)→ 释放项目 → 断开通道 → 触发 <see cref="StartedOrStopped"/> 的"已停止"事件</b>。<br/>
/// 因此返回后可以安全地复用通道实例/项目目录或替换 XML;"已停止"事件也因此是确定性信号。<br/>
/// 唯一的例外是底层驱动不响应取消:此时等待会在 <c>PollExitWaitTimeout</c>(默认 30s)后超时,
/// 记一条 Warning 并继续清理,不再等待循环退出。
/// 记一条 Warning 并继续清理,不再等待循环退出。<br/>
/// <b>未运行时调用是空操作</b>:不会派发"已停止"(重复调用也只会派发一次)。
/// </summary>
/// <returns></returns>
Task StopAsync();
Expand All @@ -72,14 +149,19 @@ public interface ITagsProjectCtrl
public class TagsProjectEventArgs : EventArgs
{
/// <summary>
/// c'tor
/// c'tor。控制器与自定义 <see cref="ITagsProjectCtrl"/> 实现都用它构造事件参数——
/// 只有 <see cref="State"/> 这一个"真相",不再存在"bool 与 State 各说各话"的可能。
/// </summary>
/// <param name="isstarted"></param>
/// <param name="project"></param>
public TagsProjectEventArgs(bool isstarted, ITagsProject? project)
/// <param name="state">本次通知对应的状态(只会是 <see cref="TagsProjectState.Running"/> 或 <see cref="TagsProjectState.Stopped"/>)</param>
/// <param name="project">项目实例;停止事件传 <c>null</c></param>
/// <param name="runId">运行标识;自定义实现没有这个概念时可留默认值</param>
/// <param name="failure">导致本次运行结束的异常;正常停机传 <c>null</c></param>
public TagsProjectEventArgs(TagsProjectState state, ITagsProject? project, long runId = 0, Exception? failure = null)
{
this.IsStarted = isstarted;
Project = project;
this.State = state;
this.Project = project;
this.RunId = runId;
this.Failure = failure;
}

/// <summary>
Expand All @@ -89,9 +171,22 @@ public TagsProjectEventArgs(bool isstarted, ITagsProject? project)
public ITagsProject? Project { get; }

/// <summary>
/// 测点项目是否启动
/// 本次通知对应的状态:只会是 <see cref="TagsProjectState.Running"/> 或 <see cref="TagsProjectState.Stopped"/>。
/// </summary>
public TagsProjectState State { get; }

/// <summary>
/// 运行标识:每次 <c>StartPollAsync</c> 递增。"已启动"与"已停止"的 <c>RunId</c> 相同,
/// 可以据此配对、关联日志(例如界面推送流用它区分不同批次的快照)。
/// </summary>
public long RunId { get; }

/// <summary>
/// 导致本次运行结束的异常:<b>运行中</b>异常结束(如 <c>RunAsync</c> 抛错)时非 null;
/// 正常停机(<c>StopAsync</c>,含停机引起的 <see cref="OperationCanceledException"/>)为 null。
/// "已启动"通知里恒为 null;启动阶段就失败的运行不会派发任何事件,因此也谈不上 Failure。
/// </summary>
public bool IsStarted { get; }
public Exception? Failure { get; }
}

/// <summary>
Expand Down
Loading
Loading