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
+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 {