docs: explain UI bridge callers, control flow and VM ownership
This commit is contained in:
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user