docs: clarify presentation state and window resource lifecycle

This commit is contained in:
2026-11-12 20:32:45 +08:00
parent 723e7f1fbd
commit 8042d2efd4
3 changed files with 20 additions and 5 deletions
+3
View File
@@ -40,6 +40,7 @@ impl NativeCallable for OpenTool {
});
}
// 锁内只复制弱节点索引,之后逐个升级并查工具标记,不持 session 锁运行 show 的流程。
// 搜索范围是会话全部节点而非 current 的标签;已关闭但仍被源引用的工具页也可复用,死亡弱项则跳过。
let nodes = self
.session
.lock()
@@ -73,6 +74,7 @@ impl NativeCallable for OpenTool {
}
}
// 没有现存工具页才创建空托管 Page,_tesseraTool 标记让宿主在该页面位置绘制对应管理工具。
// 工具原生内容不需要伪造 Block 子树;空 Page 仍沿正常窗口注册、标签投影及生命周期刷新路径展示。
let page = new_typed_block(
cx,
Data::new(Kind::Page, vec![], 0.0, 0.0),
@@ -107,6 +109,7 @@ pub(super) fn install(vm: &mut Vm, ui: ObjectRef, session: &Shared) -> Result<()
/// 每个 VM 仅安装一次,后续新标签操作重复调用工厂;源类/闭包仍由正常 VM 对象系统管理。
pub(super) fn install_start_page(vm: &mut Vm, bridge: &UiBridge) -> Result<()> {
// 源码随 binary 嵌入,每个 VM 安装时解析/编译一次;函数工厂之后重复执行不再重复编译模块。
// 模板之后必须 load 到传入的所属 VM;不同会话的类、闭包和私有 globals 不能复用另一 VM 的托管对象身份。
let source = frontend::EndorReader::from_text(
"tessera:start-page.endor",
include_str!("start_page.endor"),
+8 -4
View File
@@ -31,7 +31,7 @@ pub(crate) struct Presentation {
pub tab_ids: Vec<(WeakObjectRef, u64)>,
// 分配新原生标签 ID 的单调计数,与可被回收的 Page 弱身份分开。
pub next_tab: u64,
// 最近发布的标签值列表,用于检测标题/活动项/顺序变化。
// 最近一次桥接 commit_frame 保存的标签草稿,用于检测标题/活动项/顺序变化;不保证 GUI 已收到该帧。
pub last_tabs: Vec<crate::tabs::Tab>,
// 当前页面兼容表面相机和模式,随本窗口展示更新。
pub surface: crate::page::Surface,
@@ -41,7 +41,8 @@ pub(crate) struct Presentation {
pub layout: crate::layout::LayoutRuntime,
// 本窗口活动 Mount 的弱索引与发布顺序,托管字典负责强拥有。
pub mounts: crate::mount::MountTable,
// 最后完整发布的布局版本,未提交的分片结果不能直接覆盖此边界。
// commit_frame 已同步 Mount 的布局版本,输入检查据此拒绝旧几何;后续 paint/稳定发布仍可能尚未完成。
// 字段名沿用 published_version,但不代表此值已经写入 GUI 共享文档,也不是整个源输入的成功标记。
pub published_version: u64,
// 即使根快照身份未变也要求重新发布一帧,例如源绘制读取的数据发生变化时。
pub force_frame: bool,
@@ -67,8 +68,9 @@ pub(crate) struct Presentation {
impl Presentation {
/// 比较布局/绘制读取版本和名称依赖,标记需要刷新并通知快照缓存。
/// UiBridge::prepare_frame 将同一 ChangeBatch 广播所有窗口;这里只设置失效状态,实际提取/布局由各窗随后推进。
pub fn observe_changes(&mut self, vm: &Vm, changes: &ChangeBatch) {
// 先检查粗粒度对象版本,layout 优先于 paint;每类只记录第一个失效项用于诊断。
// 先检查粗粒度对象版本,layout 优先于 paint;合并后的两阶段读取序列只记录第一个失效项用于诊断。
// 对象已经释放时版本查询失败,也视作失效,而非继续使用旧缓存。
if let Some((phase, object, version)) = self
.layout_reads
@@ -93,7 +95,7 @@ impl Presentation {
vm.change_version(*object).ok()
);
}
// 再核对名称级依赖,避免仅凭对象版本漏掉名称解析路径上的变化。
// 再核对精确依赖,既包括对象属性名,也包括命名空间查找和字典种类,保留 VM 记录的原粒度。
// 两个检查独立执行,因此同次观察可能分别增加计数,后者诊断可覆盖前者。
if let Some((phase, dependency)) = self
.layout_names
@@ -125,6 +127,7 @@ impl Presentation {
}
/// 按尺寸、内容或绘制失效原因清理对应缓存,避免把所有变化都当成相同重建。
/// calls::Invalidate 已校验 reason,并按最终共享 Data 收集 affected 中的全部 Block 别名;这里不再自行扫描其他窗口。
pub fn invalidate(
&mut self,
cx: &mut NativeContext<'_>,
@@ -206,6 +209,7 @@ pub(crate) fn split_reads(
// 其他精确依赖保持原枚举与顺序,不能降级为对象版本而丢掉名字解析语义。
let mut names = Vec::new();
// 整对象依赖按身份收集到有序表,重复项以最后一次版本为准;其余精确依赖保持原记录。
// 调用方先排除各窗口 desktop 记账读取;本函数不负责过滤宿主身份,也不替调用方取得新的版本。
for dependency in reads {
// 按 ReadDependency 种类拆分;不会 retain 借用身份或执行源函数。
match dependency {
+9 -1
View File
@@ -283,6 +283,8 @@ impl NativeCallable for Method {
}
}
/// 把合法窗口操作追加到所属窗口的待发布命令,不能直接在 VM 线程操作 OS。
/// Method::invoke 先检查尺寸/标题/只读规则;工具激活和 close 也直接调用本入口,因此 closed 与动作参数并不在这里重验。
/// 返回成功只表示 outbox 已排队;worker 成功发布并封装 session 后,shell::app 才可能执行动作。
pub fn enqueue(
cx: &mut NativeContext<'_>,
owner: ObjectRef,
@@ -314,12 +316,14 @@ pub fn enqueue(
// 必须先成功经过 VM 写屏障,才修改不可回滚的原生 outbox;只读调用不能先留下待发命令再报错。
cx.replace_payload(owner, data)?;
// 同窗口同动作只保留最后请求,其他类别保持先后;此处只入队,GUI 是否执行取决于后续成功发布。
// 例如 Resize(seq1)、Focus(seq2)、Resize(seq3) 会留下 Focus(seq2)、Resize(seq3),不能保留首次 Resize 的旧序号。
queue.retain(|old| !old.same_kind(&command));
queue.push(command);
Ok(())
}
/// 将页面登记到其窗口,维护托管所有权与页面顺序。
/// UiBridge::show_in 在调用前处理跨窗撤登记;本入口只保证该窗口内不重复,不负责查找或迁移其他窗口的同一 Page。
pub fn register_page(
cx: &mut NativeContext<'_>,
window: ObjectRef,
@@ -443,6 +447,7 @@ pub fn pages(store: &ObjectStore, window: ObjectRef) -> Result<&[ObjectRef], VmE
Ok(&store.payload::<ManagedWindow>(window, "Window")?.pages)
}
/// 取走当前窗口累积的命令,后续由成功发布结果携带到 GUI。
/// 正常发布路径会封装返回值;故障清理路径也调用本函数但直接丢弃结果,所以 drain 本身不能视为发布成功。
pub fn take_commands(vm: &Vm, window: ObjectRef) -> Result<Vec<Command>, VmError> {
// 读取 payload 只取得共享 transport outbox;drain 不应制造业务依赖写入。
let data = vm.payload::<ManagedWindow>(window, "Window")?;
@@ -546,7 +551,8 @@ pub fn install(
/// Create a managed native-window resource. The GUI creates the OS resource only
/// after the owning candidate/input publishes its immutable projection.
/// 建立托管窗口、desktop 与页面容器;原生窗口通过命令发布后出现。
/// 建立托管窗口、desktop 与页面容器;桥接强制生成该窗口的首帧,GUI 根据成功发布的窗口投影创建 OS 资源。
/// Action 没有 Create 变体;这里返回的三元组由 ui_bridge::create_window 用于建立独立 Presentation。
pub fn create(
cx: &mut NativeContext<'_>,
master: ObjectRef,
@@ -609,6 +615,7 @@ pub fn close(cx: &mut NativeContext<'_>, window: ObjectRef) -> Result<(), VmErro
return Ok(());
}
// 真实关闭边界先取消窗口与所有页面 owner 的任务,再撤销页面登记,防止晚到结果继续更新已关闭资源。
// cancel_owner 只取消传入 owner 的作用域;具体 Mount 的任务随后在桥接刷新卸载出现时清理,不在此遍历 Mount 表。
crate::tasks::cancel_owner(cx, window)?;
// 遍历旧页顺序副本,unregister_page 可以安全更新真实集合;每页 owner 任务先取消。
for page in data.pages.clone() {
@@ -628,6 +635,7 @@ pub fn close(cx: &mut NativeContext<'_>, window: ObjectRef) -> Result<(), VmErro
/// Host teardown for a stopped VM: no binding, dispatch or source execution.
/// 撤销已失效窗口的托管资源关系,不重新执行源关闭请求。
/// UiBridge::shutdown/retire_window 先处理任务或 Mount,再调用这里断 Page 拥有边;不等同于源 close 的排队关闭流程。
pub fn retire(vm: &mut Vm, window: ObjectRef) -> Result<(), VmError> {
// 已停止域的宿主路径只解除托管页面拥有边并标记 closed,任务/OS 清理由外层退役流程负责。
let mut data = vm.payload::<ManagedWindow>(window, "Window")?.clone();