docs: explain UI bridge callers, control flow and VM ownership

This commit is contained in:
2026-11-12 16:36:11 +08:00
parent f00fd05754
commit fbc5bed19e
8 changed files with 878 additions and 103 deletions
+63 -2
View File
@@ -1,42 +1,63 @@
//! 安装一次 VM 域需要的宿主类型、对象和方法。类型注册表是源代码调用原生能力的入口。
//! 先建立类型与桌面基础设施,再绑定构造器、视觉协议和开发工具工厂;返回的根负责保持这些对象存活。
//!
//! Allocate and connect the managed desktop, type tables and host globals.
//! 调用链:`endor_host::compile` / `ReplSession::new` 创建候选 VM,
//! 随后调用本模块的 `install`;运行时再通过 install_globals 注入源程序使用的 UI 值。
//! 本文件只建立宿主环境。源程序稍后调用构造器或实例方法时,才会进入 `calls::Function::invoke`。
//! 安装返回的 UiBridge 由运行时保存;传入的 roots 由候选运行时持有,并在失败或退役时统一释放。
use super::*;
/// 把本模块的类型、方法或能力注册到所属运行时上下文。
/// 为一次候选程序/REPL 会话安装 Tessera 宿主环境,供运行时后续注入全局值和执行源程序。
///
/// 类型要先创建,签名才能引用它们;因此先分配没有签名的函数,再原地补齐 payload。
/// 所有 `?` 都把安装失败交还候选运行时,不会在这里把半成品替换成活跃程序。
/// `roots` 保存明确的 VM 拥有根;Rust 的 ObjectRef 数值和 Arc<Mutex<Session>> 均不能替代它们。
pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
// 先建立 desktop/ui/tabs 并加入显式 roots,后面初始化失败时由上层运行时统一释放,避免依赖 Rust 句柄保活。
// desktop 是此桥接域的类型注册表和窗口资源入口;它不是操作系统桌面或原生窗口。
let desktop = vm.new_object()?;
roots.push(desktop);
// 安装时尚无窗口尺寸;运行时收到 viewport 后再填充,避免在 VM 引导期间依赖 GUI 状态。
vm.set_attr(desktop, "viewport", Value::Nil)?;
// tabs 是主窗口的托管页面注册表,Presentation 和 window::install 会使用同一字典身份。
let tabs = vm.new_dict()?;
roots.push(tabs);
vm.set_attr(desktop, "tabs", Value::Object(tabs))?;
// ui 是对源代码公开的命名空间;desktop 保存内部记账,二者用途不能混同。
let ui = vm.new_object()?;
roots.push(ui);
// 原生 Session 借用托管身份,主窗口先拥有独立 Presentation;业务对象仍全部位于传入的单一 VM。
let session = Arc::new(Mutex::new(Session {
// 节点弱索引用来检查数量与回收失效记录,不应让已关闭的业务对象继续存活。
nodes: Vec::new(),
// 先登记主窗口上下文;后续窗口通过 create_window 建立各自的 Presentation。
presentations: std::collections::BTreeMap::from([(
crate::window::MAIN_WINDOW,
crate::presentation::Presentation::new(desktop, tabs),
)]),
// Session 的 Deref 按 current 选择布局/挂载状态;初始所有操作都落在主窗口。
current: crate::window::MAIN_WINDOW,
// master 始终指向主 desktop,副窗口仍借用同一 VM 的类型和资源域。
master: desktop,
// 分配器从现有最高窗口 ID 继续增长;Mount 则尚无任何已分配出现位置。
next_window: crate::window::MAIN_WINDOW,
next_mount: 0,
// 关闭后尚未交给 GUI 的原生命令暂存在这里,不能随 Presentation 删除而丢失。
retired_commands: Vec::new(),
// 累计诊断计数由刷新流程更新,供 ui.stats/开发工具观察本会话的实际工作量。
refresh_yields: 0,
refresh_restarts: 0,
layout_cancels: 0,
paint_cancels: 0,
paint_slices: 0,
binding_evaluations: 0,
// 清理阶段会置位,create_window 等操作据此拒绝在退出期间重新创建资源。
exiting: false,
}));
// 先分配函数占位再补签名,因为签名会引用尚未建立的名义类型;保存列表用于第二阶段替换 payload。
// 保存 ui.name 的函数身份及 Operation,等全部类型注册后再为这些函数补齐精确签名。
let mut public_functions = Vec::new();
// 另外记录 TypeConstructor 所用的工厂;它们多接收一个 Type 首参,不能套用自由函数签名。
let mut factories = Vec::new();
for (name, operation) in [
("implement", Operation::Implement),
@@ -63,6 +84,8 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
("viewport", Operation::Viewport),
("window", Operation::Window),
] {
// 每个名字得到自己的 VM callable,实际操作由 Function 根据 operation 分派。
// desktop 放在 captures 中,确保函数仍可达时它所依赖的类型注册表也能被 GC 追踪。
let function = vm.allocate(ContextNativeFunction::new(
name,
Function {
@@ -75,6 +98,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
vec![desktop],
))?;
roots.push(function);
// 属性供源程序的 ui.text/ui.present 等查询;列表供本函数第二阶段补签名,职责不同。
vm.set_attr(ui, name, Value::Object(function))?;
public_functions.push((name, function, operation));
}
@@ -83,6 +107,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
roots.extend([root_types.object, root_types.type_type]);
vm.set_attr(ui, "Object", Value::Object(root_types.object))?;
vm.set_attr(ui, "Type", Value::Object(root_types.type_type))?;
// definitions 汇集全部类型,稍后写入 desktop.types,供 desktop_type 按名称查精确身份。
let mut definitions = vec![
("Object", root_types.object),
("Type", root_types.type_type),
@@ -127,10 +152,13 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
("Task", "Object", None),
("ObjectList", "Object", Some("object-list")),
] {
// 依照表中基类名取得当前 VM 的真实类型,不能用另一个 VM 中的同名 Type 代替。
let base = object(Some(&vm.get_attr(ui, base_name)?))?;
// 根据构造规则选择专用工厂、通用工厂或抽象类型;这里只注册,不分配业务实例。
let constructor = match constructor_name {
// ObjectList 与 Event 有特殊的“类型首参+子类字段”构造规则,单独原生适配;其他类型共用 NativeFactory。
Some("object-list") => {
// ObjectList 构造要保持托管元素身份与字段规则,由 object_list::Constructor 处理。
let factory = vm.allocate(ContextNativeFunction::new(
"object-list",
crate::object_list::Constructor {
@@ -140,17 +168,20 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
vec![desktop],
))?;
roots.push(factory);
// 工厂本身也是语言中的 Function 实例,挂类型后才能通过名义函数检查。
let function_type = object(Some(&vm.get_attr(ui, "Function")?))?;
vm.attach_type(factory, function_type)?;
TypeConstructor::NativeTyped(factory)
}
Some("event") => {
// Event 另有必填事件名;其专用 Constructor 在真正调用时解析事件参数和子类字段。
let factory = vm.allocate(ContextNativeFunction::new(
"event",
crate::event_dispatch::Constructor { signature: None },
vec![],
))?;
roots.push(factory);
// 与列表工厂保持相同函数类型体系;无 desktop 捕获的分配器不额外引入桌面强边。
let function_type = object(Some(&vm.get_attr(ui, "Function")?))?;
vm.attach_type(factory, function_type)?;
TypeConstructor::NativeTyped(factory)
@@ -176,6 +207,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
.map(Operation::SceneObject)
.ok_or(invalid("unknown native type allocator"))?,
};
// 通用 NativeFactory 在调用时区分原生参数与源子类字段,并保留 requested Type。
let factory = vm.allocate(ContextNativeFunction::new(
constructor_name,
NativeFactory {
@@ -187,10 +219,12 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
vec![desktop],
))?;
roots.push(factory);
// 这个函数属于构造器元数据,不直接放在 ui.name;但仍需标为 Function 实例。
let function_type = object(Some(&vm.get_attr(ui, "Function")?))?;
vm.attach_type(factory, function_type)?;
TypeConstructor::NativeTyped(factory)
}
// 没有公开分配规则的类型仍可用于类型检查/协议;直接把它当构造器调用会由 VM 拒绝。
None => TypeConstructor::Abstract,
};
// 记住实际工厂身份,类型构建完成后原地补签名,避免替换类型内指向的构造函数对象。
@@ -198,6 +232,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
{
factories.push((tag, factory));
}
// 生成新 Type 后同时公开到 ui,并加入待提交注册表,两个入口必须指向同一对象。
let definition = vm.new_type(name, base, constructor)?;
roots.push(definition);
vm.set_attr(ui, name, Value::Object(definition))?;
@@ -217,6 +252,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
("PaintCommand", vec![]),
("CameraGesture", vec![]),
] {
// 表里的字段名转成 VM 可检查的字段声明;map 的每次调用只描述一个字段,不执行布局。
let fields = fields
.into_iter()
.map(|name| endor_core::ClassField {
@@ -225,11 +261,13 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
type_name: if matches!(name, "children" | "commands") {
"Object"
} else {
// 余下字段都是测量/几何数值,让 VM 在实例化时先拒绝非数字实参。
"Number"
}
.into(),
})
.collect();
// 这些协议值只携带源字段,使用普通 class 分配;不需要 Block 的原生 payload。
let definition = vm.new_class(
name,
root_types.object,
@@ -243,14 +281,17 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
// The desktop owns the registry through ordinary traced attributes. The
// Rust session only borrows handles and adds no hidden lifetime roots.
// 桌面通过普通属性拥有类型字典;后续 nominal 查询必须使用同一 desktop 中注册的精确类型身份。
// 类型字典由 desktop 属性托管持有;后续桥接调用可从其查找 Block、Event 等精确类型。
let types = vm.new_dict()?;
roots.push(types);
for (name, definition) in definitions {
// 字符串键是宿主查询约定,值才是参与 is_instance/is_subtype 的真实名义身份。
vm.dict_set(types, Value::Text(name.into()), Value::Object(definition))?;
}
vm.set_attr(desktop, "types", Value::Object(types))?;
vm.attach_type(desktop, root_types.object)?;
vm.attach_type(ui, root_types.object)?;
// 安装后续编译函数的默认类型,也用于下方所有方法 wrapper 的 attach_type。
let function_type = object(Some(&vm.get_attr(ui, "Function")?))?;
// 让后续 VM 创建的函数使用宿主 Function 名义类型,并打开源类型检查,再安装完整本机签名。
vm.set_function_type(function_type)?;
@@ -273,6 +314,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
)?;
}
for (name, function) in factories {
// 恢复第一阶段记录的分配器类别;Event/ObjectList 不走 NativeFactory,需要单独补外壳。
let operation = match name {
"text" => Some(Operation::Text),
"rect" => Some(Operation::Rect),
@@ -288,6 +330,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
"button" => Some(Operation::Button),
"page" => Some(Operation::Page),
"window-create" => Some(Operation::NewWindow),
// None 在本轮只表示专用构造器,不表示前一阶段的 Abstract 类型。
"event" | "object-list" => None,
name => Some(
crate::scene3d_model::Constructor::from_function(name)
@@ -296,6 +339,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
),
};
if let Some(operation) = operation {
// options 只描述原生构造选项,调用时由 NativeFactory 在切掉 Type 和子类字段后校验。
let options = operation_signature(vm.object_store(), desktop, operation)?;
// 外层 NativeTyped 工厂接收 Type 首参和任意候选尾参,允许子类字段;NativeFactory 用 options 再核对基构造参数。
let envelope = CallSignature {
@@ -305,6 +349,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
returns: options.returns.clone(),
effect: options.effect,
};
// 初始强边是注册表;随后追加签名引用的类型,供 ContextNativeFunction::trace 使用。
let mut captures = vec![desktop];
// 参数和返回注解中的名义类型也是托管引用,必须纳入 captures,不能只把它们存进 Rust 签名结构。
captures.extend(options.references());
@@ -323,16 +368,20 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
)?;
} else {
// 特殊构造器保留宽变参外壳,再由对应 Constructor 按类型字段数拆实参,返回准确 Event/ObjectList 名义类型。
// 为返回值选取专用名义类型,避免宽变参外壳同时放宽了返回值检查。
let kind = if name == "event" {
"Event"
} else {
"ObjectList"
};
// Event 的 Type 之后还有必填字符串事件名;ObjectList 只有 Type 为必填,其余由实现解释。
let signature = CallSignature {
arity: endor_core::CallArity::range(
// 这里包含 Type 首参;源子类字段由构造器验证,所以最大个数保留开放。
if name == "event" { 2 } else { 1 },
usize::MAX,
),
// 固定前缀与 required 数量保持一致,额外实参由 variadic 和字段验证共同约束。
parameters: if name == "event" {
vec![AnnotationType::Type.into(), AnnotationType::String.into()]
} else {
@@ -344,6 +393,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
effect: CallEffect::ReadOnly,
};
if name == "event" {
// 原地更新 Event 工厂,TypeConstructor 中已保存的对象引用继续有效。
vm.replace_payload(
function,
ContextNativeFunction::new(
@@ -355,6 +405,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
),
)?;
} else {
// 这里只有 ObjectList;保留 desktop 捕获,以便专用分配器给结果附加列表类型。
vm.replace_payload(
function,
ContextNativeFunction::new(
@@ -369,6 +420,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
}
}
}
// 对这批公开入口补 Function 类型身份;不重新分配 callable,ui 属性仍指向原对象。
for name in [
"open",
"text",
@@ -390,6 +442,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
"implements",
"supports",
] {
// 从 ui 取回前面已补完签名的函数;名称表与安装表不一致会在这里报错而非静默漏装。
let function = object(Some(&vm.get_attr(ui, name)?))?;
vm.attach_type(function, function_type)?;
}
@@ -437,7 +490,9 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
("Page", "back", Operation::Back),
("Page", "forward", Operation::Forward),
] {
// expected 同时用于方法所属类型、receiver 校验和签名中的名义参数身份。
let expected = object(Some(&vm.get_attr(ui, type_name)?))?;
// VM 的方法分派负责绑定 receiver;TypeMethod 再验证它并转交 Function 执行业务操作。
let method = vm.allocate(ContextNativeFunction::new(
name,
TypeMethod {
@@ -451,20 +506,26 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
))?;
roots.push(method);
vm.attach_type(method, function_type)?;
// 写到类型方法表而非每个实例的属性,实例与源子类可共享同一个原生实现。
vm.define_method(expected, name, method)?;
}
// 类型与基础方法就绪后再装窗口、默认视觉、事件方法和能力契约,顺序满足各模块查类型/方法的前提。
crate::window::install(vm, roots, desktop, tabs)?;
// 默认 measure/arrange/paint 安装到 Block 体系;源代码之后可按协议覆盖它们。
let block_type = object(Some(&vm.get_attr(ui, "Block")?))?;
crate::native_visual::install(vm, roots, desktop, block_type, function_type)?;
// 事件方法需要识别 Event 实例;订阅返回值则使用 Subscription 身份管理取消连接。
let event_type = object(Some(&vm.get_attr(ui, "Event")?))?;
// token_type 传给事件安装器,不能拿 Event 类型代替,否则取消令牌会违反返回契约。
let token_type = object(Some(&vm.get_attr(ui, "Subscription")?))?;
crate::event_dispatch::install(vm, roots, event_type, token_type, function_type)?;
crate::protocols::install(vm, roots, desktop, ui)?;
// 每个桥接域配套自己的任务 Scheduler,再接工具入口及托管起始页工厂,最后返回可使用的 UiBridge。
// Scheduler 随 UiBridge 交还运行时;它还未开始执行用户任务,只完成 ui 异步 API 注册。
let tasks = crate::tasks::install(vm, roots, ui, desktop)?;
crate::bridge::graphics::install(vm, roots, ui, desktop)?;
developer_pages::install(vm, ui, &session)?;
// 将语言命名空间、展示会话与任务调度打包,运行时随后通过同一 bridge 推进刷新与回调。
let bridge = UiBridge { ui, session, tasks };
developer_pages::install_start_page(vm, &bridge)?;
Ok(bridge)