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()