docs: clarify binding refresh and worker publication boundaries

This commit is contained in:
2026-11-12 19:57:03 +08:00
parent 7f7464ae2b
commit 0cd708f8c7
5 changed files with 35 additions and 3 deletions
+13 -1
View File
@@ -7,6 +7,13 @@
//! Function/TypeMethod/NativeFactory 是语言调用适配,Session 保存跨调用的窗口展示状态;
//! 真正的排版/绘制交给 render,业务对象与 Mount 数据交给 model,均不在这里操作 OS 窗口。
//! 本模块会在 worker 中访问 VM;Arc/Mutex 只用于共享原生会话,不授权 GUI 线程直接调用 VM。
//!
//! 阅读调用链时应分清三个入口:bootstrap::install 创建类型和原生 callable;
//! calls 中实现的 Function::invoke 接收源程序的工厂/方法调用;endor_host 的 step_refresh 则推进展示刷新。
//! 刷新先计算绑定,再用 prepare_frame 判断是否有工作,begin/resume_layout_frame 求几何,
//! begin/resume_paint_frame 求绘制命令,最终由 endor_host 汇总稳定的逐窗文档。
//! commit_frame 是桥接内部的 Mount/几何提交,生命周期回调仍可令依赖失效;
//! 它不是向 GUI 发布成功的标志,也不意味着后来失败的整段源输入会回滚先前业务写入。
mod bootstrap;
mod calls;
mod developer_pages;
@@ -1913,7 +1920,7 @@ impl UiBridge {
}
Ok(())
}
/// endor_host 在刷新稳定循环中调用,重算失效绑定;回调可继续改变对象,随后 prepare_frame 才排空变化。
/// endor_host 在刷新稳定循环中调用,先只读计算失效绑定,再由宿主应用目标属性;随后 prepare_frame 才排空这些变化。
pub fn refresh_bindings(&self, vm: &mut Vm) -> Result<()> {
// 只在锁内快照弱节点与宿主桌面集合,实际绑定回调在锁外执行,避免回调访问 UI 时死锁。
let (nodes, desktops) = {
@@ -2211,6 +2218,7 @@ impl UiBridge {
};
// 准备私有布局草稿与缓存副本,之后的源调用在锁外运行;正式状态等完成时再写回。
let (mut layout, cache, desktop, page, nodes) = {
// 克隆布局/缓存作为本轮私有求解输入,page 同时保留显式清空请求;此处尚不消费 pending 或覆盖 active。
let state = self
.session
.lock()
@@ -2237,6 +2245,7 @@ impl UiBridge {
let surface = root.surface.clone().unwrap_or_default();
layout.page_mode = root.surface.as_ref().map(|surface| surface.mode);
{
// 只借用当前全局出现身份下界,放锁后才在私有 layout 上创建结构;即使取消也不允许复用已暴露 ID。
let state = self
.session
.lock()
@@ -2302,6 +2311,7 @@ impl UiBridge {
/// endor_host 在布局/绘制挂起让出 worker 时调用,累计诊断次数,不改变下一片执行预算。
pub fn note_refresh_yield(&self) -> Result<()> {
// 本锁仅保护跨窗口共享的诊断累计值,不恢复续体、不选择窗口,也不改变本轮是否需要发布。
let mut state = self
.session
.lock()
@@ -2317,6 +2327,7 @@ impl UiBridge {
cancelled_layout: bool,
cancelled_paint: bool,
) -> Result<()> {
// 三个统计在同一短锁内更新,让 stats 不会看到“重启已记账而对应取消尚未记账”的中间值。
let mut state = self
.session
.lock()
@@ -2466,6 +2477,7 @@ impl UiBridge {
let result: Result<crate::document::Frame> = (|| {
self.select_window(window)?;
{
// select_window 已恢复 context.window,锁只覆盖读取该窗 Mount 数据和原生投影,源生命周期钩子稍后在锁外执行。
let state = self
.session
.lock()
+3
View File
@@ -288,8 +288,10 @@ impl NativeCallable for Function {
// 页面是 Block 的子集,同一页跨窗口迁移不会增加业务页面计数。
let mut pages = 0_i64;
for weak in &session.nodes {
// 弱索引可能已死亡;只统计成功升级的对象,不能用 nodes.len() 代表当前存活 Block 数。
if let Some(object) = cx.upgrade(*weak)? {
blocks += 1;
// Page 是这些存活 Block 的子集,按 payload 标志计一次,不按标签数或 Mount 数重复统计。
if cx.store().payload::<block::Block>(object, "Block")?.page {
pages += 1;
}
@@ -787,6 +789,7 @@ impl NativeCallable for Function {
// 平台索引转换和容器长度检查分开,len 本身允许表示“插到末尾”。
let position = usize::try_from(integer(args.first())?)
.map_err(|_| invalid("child position out of range"))?;
// 插入位置是孩子之间的缝,允许等于 len 表示末尾;大于 len 则在分配 slot 和修改子序列之前拒绝。
if position > data.children.len() {
return Err(invalid("child position out of range"));
}