docs: explain UI bridge callers, control flow and VM ownership
This commit is contained in:
@@ -1,30 +1,38 @@
|
||||
//! 把内置开发工具和起始页接入托管 Page。工厂在所属 VM 中编译和执行,而不是在窗口线程另建业务状态。
|
||||
//!
|
||||
//! Developer workspaces are managed Pages, using the same roots and placement API.
|
||||
//! bootstrap::install 调用 install 和 install_start_page;前者注册 ui.developerTools,后者注册 ui.newTab。
|
||||
//! GUI 发出的 developer-open:* 输入由 UiBridge::dispatch 转成一次 VM 调用,再进入 OpenTool::invoke。
|
||||
//! 这里管理 Page 的创建与归属;Console/Network 等工具的原生内容由 shell/developer_tools 按页面标记绘制。
|
||||
use super::*;
|
||||
|
||||
#[derive(Debug)]
|
||||
/// 工具打开能力,保存所属会话和 ui 对象;调用时校验工具名,再在该 VM 中展示页面。
|
||||
struct OpenTool {
|
||||
// 查找现有页面和安排 show 时使用同一展示域;不另建开发工具专属 VM。
|
||||
session: Shared,
|
||||
// 保存 ui.newTab 工厂入口;ContextNativeFunction 的 captures 同时声明这个托管强边。
|
||||
ui: ObjectRef,
|
||||
}
|
||||
impl NativeCallable for OpenTool {
|
||||
/// 仅接受一个工具名称字符串,工具类型与白名单在 invoke 检查。
|
||||
/// VM 在进入 invoke 前检查一个显式参数;这里只有数量检查,字符串类型与白名单由 invoke 检查。
|
||||
fn arity(&self) -> Option<endor_core::CallArity> {
|
||||
Some(endor_core::CallArity::exact(1))
|
||||
}
|
||||
/// 把白名单工具名转换成对应托管 Page;New tab 转交预编译工厂,其余管理页复用已有实例或创建新页。
|
||||
/// VM 执行 ui.developerTools 时调用:New tab 委托源工厂,其余工具优先激活已有页面,否则创建标记页。
|
||||
fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
|
||||
// 同时验证数量和字符串表示;不能把任意对象的可读表示当作工具名字接受。
|
||||
let [Value::Text(name)] = args else {
|
||||
// 错误发生在任何页面分配/登记之前,因此无须撤销一次半完成的工具打开。
|
||||
return Err(invalid("developerTools requires a tool name"));
|
||||
};
|
||||
// 工具名白名单包含四个管理页和特殊新标签动作,拒绝任意字符串进入工厂/工具标记路径。
|
||||
if !["Console", "Sources", "Network", "Settings", "New tab"].contains(&name.as_str()) {
|
||||
// 白名单错误交回 VM,不把名字继续写入 _tesseraTool 让 GUI 猜测工具类型。
|
||||
return Err(invalid("unknown developer tool"));
|
||||
}
|
||||
// 新标签交给预编译 ui.newTab 托管工厂,经 NativeResult::Invoke 回到同一 VM 执行。
|
||||
if name == "New tab" {
|
||||
// 只解析函数身份,Invoke 让 VM 自己推进源工厂,保留调用栈/预算与托管返回值语义。
|
||||
let factory = object(Some(&cx.store().get_attr(self.ui, "newTab")?))?;
|
||||
return Ok(NativeResult::Invoke {
|
||||
function: factory,
|
||||
@@ -39,16 +47,19 @@ impl NativeCallable for OpenTool {
|
||||
.nodes
|
||||
.clone();
|
||||
for weak in nodes {
|
||||
// NativeContext::upgrade 的临时引用由原生调用域管理;这里只保留实际选中的工具页作为返回值。
|
||||
if let Some(page) = cx.upgrade(weak)?
|
||||
&& cx.store().get_attr(page, "_tesseraTool").ok() == Some(Value::Text(name.clone()))
|
||||
{
|
||||
// 已有同类工具页则激活并聚焦其所属原生窗口,不每次打开都创建重复 Page。
|
||||
show(cx, page, &self.session)?;
|
||||
let window = {
|
||||
// show 可能保留旧归属;重新查所属窗口,Focus 应发给真实窗口而不是当前主窗口。
|
||||
let state = self
|
||||
.session
|
||||
.lock()
|
||||
.map_err(|_| invalid("UI session poisoned"))?;
|
||||
// show 成功后仍无登记表示桥接关系异常,不能随意选择其他窗口聚焦。
|
||||
let id = page_window(cx.store(), &state, page)?
|
||||
.ok_or(invalid("tool is not open"))?;
|
||||
object(Some(
|
||||
@@ -56,6 +67,7 @@ impl NativeCallable for OpenTool {
|
||||
.get_attr(state.presentations[&id].desktop, "window")?,
|
||||
))?
|
||||
};
|
||||
// 只登记原生命令,GUI 在发布后再执行系统聚焦;VM worker 不直接操作 OS 窗口。
|
||||
crate::window::enqueue(cx, window, crate::window::Action::Focus)?;
|
||||
return Ok(NativeResult::Return(Value::Object(page)));
|
||||
}
|
||||
@@ -67,14 +79,16 @@ impl NativeCallable for OpenTool {
|
||||
&self.session,
|
||||
None,
|
||||
)?;
|
||||
// title 是用户可见标签,_tesseraTool 是宿主识别内容的私有标记,不能只设置其中一个。
|
||||
cx.set_attr(page, "title", Value::Text(name.clone()))?;
|
||||
cx.set_attr(page, "_tesseraTool", Value::Text(name.clone()))?;
|
||||
show(cx, page, &self.session)?;
|
||||
Ok(NativeResult::Return(Value::Object(page)))
|
||||
}
|
||||
}
|
||||
/// 把本模块的类型、方法或能力注册到所属运行时上下文。
|
||||
/// bootstrap::install 在任务/类型能力就绪后调用,注册开发工具 callable;此时不打开任何页面。
|
||||
pub(super) fn install(vm: &mut Vm, ui: ObjectRef, session: &Shared) -> Result<()> {
|
||||
// payload 共享 Session,captures 显式持有 ui;仅存 Rust ObjectRef 不会形成 VM 可追踪强边。
|
||||
let function = vm.allocate(ContextNativeFunction::new(
|
||||
"developerTools",
|
||||
OpenTool {
|
||||
@@ -89,16 +103,17 @@ pub(super) fn install(vm: &mut Vm, ui: ObjectRef, session: &Shared) -> Result<()
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Compile the bundled Endor page once per VM, in a private module namespace.
|
||||
/// Its functions/classes and callbacks remain ordinary managed VM objects.
|
||||
/// 编译并安装 VM 私有的起始页工厂,供新页面动作重复调用。
|
||||
/// bootstrap 在 UiBridge 组装完成后调用,编译内置起始页模块并把 newTab 工厂挂到 ui。
|
||||
/// 每个 VM 仅安装一次,后续新标签操作重复调用工厂;源类/闭包仍由正常 VM 对象系统管理。
|
||||
pub(super) fn install_start_page(vm: &mut Vm, bridge: &UiBridge) -> Result<()> {
|
||||
// 源码随 binary 嵌入,每个 VM 安装时解析/编译一次;函数工厂之后重复执行不再重复编译模块。
|
||||
let source = frontend::EndorReader::from_text(
|
||||
"tessera:start-page.endor",
|
||||
include_str!("start_page.endor"),
|
||||
);
|
||||
// 按完整 Module 解析,保证类型与工厂定义属于一次安装环境,而不是用户 REPL 的多个输入片段。
|
||||
let ast = frontend::parse_source_ast(&source, frontend::ParseMode::Module)?;
|
||||
// 这里只生成代码模板,后面的 load 才把模板变成当前 VM 的托管代码对象。
|
||||
let compiled = compiler::compile_ast(
|
||||
&ast,
|
||||
&source,
|
||||
@@ -111,9 +126,12 @@ pub(super) fn install_start_page(vm: &mut Vm, bridge: &UiBridge) -> Result<()> {
|
||||
},
|
||||
)
|
||||
.map_err(|error| source.annotate(error))?;
|
||||
// 私有全局字典防止内置页面辅助类污染用户命名;导出闭包可通过托管边继续持有其环境。
|
||||
let globals = vm.new_dict()?;
|
||||
// 暂存安装/执行错误,闭包返回之后仍统一释放 globals 的局部拥有根。
|
||||
let result = (|| -> Result<()> {
|
||||
bridge.install_globals(vm, globals)?;
|
||||
// 加载所得代码有独立根,execute 成功/失败后都需 vm.release(code)。
|
||||
let code = compiled.load(vm)?;
|
||||
// 执行模块定义类和工厂,使用单次预算;这里不主动调用 newTab,不在安装时打开页面。
|
||||
let value = vm.execute_with_limits(
|
||||
|
||||
Reference in New Issue
Block a user