From 373a95996c8b17c3245d1af591bac8f188fdd090 Mon Sep 17 00:00:00 2001 From: Codex Bot Date: Thu, 12 Nov 2026 20:27:32 +0800 Subject: [PATCH] docs: clarify UI bridge continuation and publication boundaries --- src/bridge/ui_bridge.rs | 11 +++++++++-- src/bridge/ui_bridge/calls.rs | 7 +++++++ 2 files changed, 16 insertions(+), 2 deletions(-) diff --git a/src/bridge/ui_bridge.rs b/src/bridge/ui_bridge.rs index bf3efac..a3445c3 100644 --- a/src/bridge/ui_bridge.rs +++ b/src/bridge/ui_bridge.rs @@ -14,6 +14,8 @@ //! begin/resume_paint_frame 求绘制命令,最终由 endor_host 汇总稳定的逐窗文档。 //! commit_frame 是桥接内部的 Mount/几何提交,生命周期回调仍可令依赖失效; //! 它不是向 GUI 发布成功的标志,也不意味着后来失败的整段源输入会回滚先前业务写入。 +//! 布局错误有两种收尾:source_layout 尚未完成时恢复准备检查点;进入 finish_layout_frame 后只释放检查点根。 +//! 后一种路径可能已提交几何或执行钩子,运行时须拒绝失败候选并修复 pending,不能把它解释成完整业务事务回滚。 mod bootstrap; mod calls; mod developer_pages; @@ -115,6 +117,7 @@ struct Session { // new_typed_block 登记、reclaim 清理的弱引用表;不因宿主记账让已不可达的 Block 保活。 nodes: Vec, // 每个窗口独立拥有 Mount、布局缓存和待发布画面;切换窗口只改变 current,不移动业务对象。 + // Presentation 的 desktop 各不相同,但 window::create 共享 master 的 types 字典,跨窗仍使用同一名义类型身份。 presentations: std::collections::BTreeMap, // Deref/DerefMut 选择哪个 Presentation;调用前必须保证对应键仍在 presentations 中。 current: u64, @@ -580,7 +583,7 @@ fn new_camera2d( requested: Option, args: &[Value], ) -> Result { - // 相机和使用它的视口必须在同一个类型域;查询当前窗口 desktop 取得注册表。 + // 相机和使用它的视口必须在同一个 VM 类型域;当前窗口 desktop 与 master 共享 types,不为副窗口另造 Camera2D 类型。 let desktop = session .lock() .map_err(|_| invalid("UI session poisoned"))? @@ -1945,6 +1948,7 @@ impl UiBridge { /// endor_host 每轮刷新调用,广播 VM 变化后为 current 决定无工作、空帧或带视觉根的新一轮布局。 pub fn prepare_frame(&self, vm: &mut Vm) -> Result>>> { // 一次排空变更必须广播所有 Presentation,不能让先刷新的窗口吃掉其他窗口共享业务数据的失效通知。 + // 此处消费的是 VM 变化日志,不是各窗口的刷新请求;observe_changes 会把影响保存在各自缓存/force_frame 中。 let changes = vm.take_changes(); // 本锁内广播变化与提取只读快照,保证 current 根与各窗口的失效观察来自同一批更新。 let mut state = self @@ -2096,7 +2100,7 @@ impl UiBridge { .collect::>>()?; (state.desktop, mounts) }; - // 每片预算 256,由 source_paint 保留未完成续体;此处既可能返回 Draft,也可能返回 Work。 + // 每片预算 256,由 source_paint 保留未完成续体;返回 Complete(Draft) 或 Pending(Work),两者不能当作同一种完成结果。 let progress = crate::source_paint::start(vm, desktop, mounts, root, frame, 256)?; self.accept_paint_progress(progress) } @@ -2117,6 +2121,7 @@ impl UiBridge { &self, progress: crate::source_paint::Progress, ) -> Result { + // 运行时调用前已选定窗口;这里不从 Draft 再选择 current,恢复调用也必须维持同一窗口上下文。 if let crate::source_paint::Progress::Complete(draft) = &progress { // 借用 Draft 而非消费,调用方仍需把它交回运行时进行验证和文档发布。 // 只有完整 Draft 写入依赖,Pending 不改变上一轮已提交读取集合。 @@ -2438,6 +2443,7 @@ impl UiBridge { }))) } Ok(crate::source_layout::Progress::Complete(draft)) => self + // 源布局已结束;从这里开始的投影/提交错误由 finish_layout_frame 释放资源,不再走下方准备态恢复分支。 .finish_layout_frame(vm, context, draft) .map(|frame| LayoutProgress::Complete(Box::new(frame))), Err(error) => { @@ -2561,6 +2567,7 @@ impl UiBridge { // 两项释放都先求值,不能在 hooks 释放处直接 ? 而跳过 checkpoint 的清理。 let released_hooks = hooks.map(|hooks| vm.release(hooks)).transpose(); // 此阶段完成/报错均消费检查点根;这里是释放,不是把已提交几何回滚到准备前。 + // 若投影、commit_frame 或延后 hooks 失败,result? 阻止帧进入 paint;endor_host 的失败路径另修复待展示关系。 let released_checkpoint = checkpoint.release(vm); // 所有清理尝试结束后才传播主结果与释放错误,不把失败帧交给绘制/发布调用者。 let frame = result?; diff --git a/src/bridge/ui_bridge/calls.rs b/src/bridge/ui_bridge/calls.rs index 0a1a073..064be71 100644 --- a/src/bridge/ui_bridge/calls.rs +++ b/src/bridge/ui_bridge/calls.rs @@ -5,6 +5,8 @@ //! Function.owner 保存绑定对象,requested_type 保存原生子类构造请求;本文件 args 只包含显式原生参数。 //! 简单分支同步返回 NativeResult::Return;需要执行源协议/事件处理器的分支返回 Invoke,让 VM 接着推进调用栈。 //! NativeContext 追踪本次分配和 upgrade 的临时根,返回/委托时提升输出引用,其余在域退出时释放。 +//! 下面的提前返回按能力分层:相机/场景、查询/状态、构造、展示协议先处理,最后才要求 Block owner 并克隆 Data。 +//! 这不是统一回滚事务:有些分支会先写托管属性或窗口注册表,末尾 replace_payload 只提交仍需写回的结构副本。 use super::*; impl NativeCallable for Function { @@ -641,6 +643,8 @@ impl NativeCallable for Function { vec![desktop], ))?; // 小驱动先调用 present(value, window),再把结果交 PresentResult 验证/可选打开,所有委托共用当前 VM 预算。 + // 两个 PushNull 填 Call 的空接收者槽,避免 VM 额外插入 receiver;value/window 已作为 present 的两个显式参数加载。 + // 栈先保留 complete 的调用,再嵌套两参 present,最后把其结果作 complete 的一个参数,形成验证续接。 let instructions = [ endor_core::Instruction::new(endor_core::Opcode::LoadConst, 0), endor_core::Instruction::simple(endor_core::Opcode::PushNull), @@ -748,6 +752,7 @@ impl NativeCallable for Function { } // 接收者可能是共享转发别名,解析到最终 Data 后修改副本,最后用一次 replace_payload 写入结构边。 let (data_ref, data) = block::resolve(cx.store(), owner)?; + // data_ref 是最终 Data,不是 owner 包装或它的 Cell;新子组成用此身份防回边,末尾也替换这一对象的 payload。 // 在副本上编辑结构,再经末尾 replace_payload 更新强边与版本,避免直接篡改借用 payload。 let mut data = data.clone(); // 默认返回 Unit/Nil,append/insert/订阅等分支会改成自己的业务结果;查询分支直接返回。 @@ -899,6 +904,7 @@ impl NativeCallable for Function { return Ok(NativeResult::Return(Value::Nil)); } // 后退/前进钳到历史首尾,复用已保留根对象而非重新执行旧源码。 + // 这里不增删历史;导航根通过 Data.trace 保活,show 仅安排后续刷新,不立即切换 active 或产生 Mount。 let next = if matches!(self.operation, Back) { // saturating_sub 在首项停住,不绕回列表尾部。 data.history_index.saturating_sub(1) @@ -1089,6 +1095,7 @@ impl NativeCallable for Function { _ => return Err(invalid("unsupported Block operation")), } // 非提前返回的结构编辑/订阅操作在末尾统一经过写屏障,触发拥有边更新和变更日志。 + // 只覆盖解析到的 Data;原 Block/Cell 身份保持,所有转发到同一 Data 的别名因此观察到本次结构修改。 cx.replace_payload(data_ref, data)?; Ok(NativeResult::Return(result)) }