docs: clarify UI bridge continuation and publication boundaries

This commit is contained in:
2026-11-12 20:27:32 +08:00
parent b44d7833ea
commit 373a95996c
2 changed files with 16 additions and 2 deletions
+9 -2
View File
@@ -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<WeakObjectRef>,
// 每个窗口独立拥有 Mount、布局缓存和待发布画面;切换窗口只改变 current,不移动业务对象。
// Presentation 的 desktop 各不相同,但 window::create 共享 master 的 types 字典,跨窗仍使用同一名义类型身份。
presentations: std::collections::BTreeMap<u64, crate::presentation::Presentation>,
// Deref/DerefMut 选择哪个 Presentation;调用前必须保证对应键仍在 presentations 中。
current: u64,
@@ -580,7 +583,7 @@ fn new_camera2d(
requested: Option<ObjectRef>,
args: &[Value],
) -> Result<ObjectRef, VmError> {
// 相机和使用它的视口必须在同一个类型域;查询当前窗口 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<Option<Option<Arc<UiNode>>>> {
// 一次排空变更必须广播所有 Presentation,不能让先刷新的窗口吃掉其他窗口共享业务数据的失效通知。
// 此处消费的是 VM 变化日志,不是各窗口的刷新请求;observe_changes 会把影响保存在各自缓存/force_frame 中。
let changes = vm.take_changes();
// 本锁内广播变化与提取只读快照,保证 current 根与各窗口的失效观察来自同一批更新。
let mut state = self
@@ -2096,7 +2100,7 @@ impl UiBridge {
.collect::<Result<Vec<_>>>()?;
(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<crate::source_paint::Progress> {
// 运行时调用前已选定窗口;这里不从 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?;
+7
View File
@@ -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))
}