docs: explain Tessera modules and execution flows in Chinese
This commit is contained in:
@@ -1,3 +1,7 @@
|
||||
//! 每次展示的托管上下文:同一个 Block 出现在两个位置时,有两个独立 Mount。
|
||||
//! Mount 保存父子关系、出现几何和布局期间的查询上下文;MountTable 用弱索引定位对象,不靠索引强行保活业务树。
|
||||
//! 同步会安排 onMount/onUnmount。布局取消时使用 Checkpoint 恢复未发布状态,避免半完成的出现关系影响下一次刷新。
|
||||
//!
|
||||
//! Managed presentation contexts. The active desktop owns the mount dictionary;
|
||||
//! reverse links and the host registry are weak, so shared content cannot retain a Page.
|
||||
use crate::document::{Frame, MountGeometry};
|
||||
@@ -11,16 +15,20 @@ use std::{
|
||||
};
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
/// 一个组件在一个展示位置上的上下文。强持有 Block,反向页面/父子链接使用弱身份,避免共享组件把已关闭页面保活。
|
||||
pub struct Mount {
|
||||
// 组件是强引用;页面、父节点和兄弟链接是弱引用,防止反向链接形成保活环。
|
||||
pub block: ObjectRef,
|
||||
pub page: Option<WeakObjectRef>,
|
||||
pub parent: Option<WeakObjectRef>,
|
||||
pub first_child: Option<WeakObjectRef>,
|
||||
pub next_sibling: Option<WeakObjectRef>,
|
||||
// 已发布几何与每次出现的滚动位置分开保存,同一 Block 的多个位置互不覆盖。
|
||||
pub geometry: MountGeometry,
|
||||
pub scroll_offset: [f32; 2],
|
||||
pub version: u64,
|
||||
pub mounted: bool,
|
||||
// Mount 可以拥有任务;退役后任务交付还要检查 owner 是否仍有效。
|
||||
pub tasks: Option<ObjectRef>,
|
||||
// Private derived scratch, installed before the read-only layout call and
|
||||
// cleared by geometry commit. It contains no managed references or roots.
|
||||
@@ -28,18 +36,23 @@ pub struct Mount {
|
||||
}
|
||||
|
||||
impl ObjectPayload for Mount {
|
||||
/// 声明此 payload 的赋值遵循引用身份语义,避免把内部宿主状态当作可复制值。
|
||||
fn reference_assignment_only(&self) -> bool {
|
||||
true
|
||||
}
|
||||
/// 提供受检查的 Any 下转型入口,让宿主按具体 payload 类型读取数据。
|
||||
fn as_any(&self) -> &dyn std::any::Any {
|
||||
self
|
||||
}
|
||||
/// 返回运行时诊断/类型检查使用的稳定 payload 名称。
|
||||
fn kind_name(&self) -> &'static str {
|
||||
"tessera-mount"
|
||||
}
|
||||
/// 声明此 payload 是否允许使用托管属性存储,具体字段仍由类型与调用检查约束。
|
||||
fn allows_attributes(&self) -> bool {
|
||||
true
|
||||
}
|
||||
/// 枚举本对象真正拥有的托管强引用,供 Aster 引用追踪和循环回收使用。
|
||||
fn trace(&self, visit: &mut dyn FnMut(ObjectRef)) {
|
||||
visit(self.block);
|
||||
if let Some(tasks) = self.tasks {
|
||||
@@ -49,6 +62,7 @@ impl ObjectPayload for Mount {
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy)]
|
||||
/// 该原生能力的查询/操作分类,方法包装用它选择具体实现。
|
||||
enum Query {
|
||||
Bounds,
|
||||
ScrollTo,
|
||||
@@ -68,6 +82,7 @@ enum Query {
|
||||
}
|
||||
|
||||
#[derive(Debug)]
|
||||
/// 保存 owner、签名或操作枚举的原生方法适配器,统一由 VM 调用。
|
||||
struct Method {
|
||||
signature: endor_core::CallSignature,
|
||||
owner: ObjectRef,
|
||||
@@ -76,9 +91,11 @@ struct Method {
|
||||
}
|
||||
|
||||
impl NativeCallable for Method {
|
||||
/// 给出参数与返回值的托管类型契约;实际操作在 invoke 中执行。
|
||||
fn signature(&self) -> Option<endor_core::CallSignature> {
|
||||
Some(self.signature.clone())
|
||||
}
|
||||
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
|
||||
fn arity(&self) -> Option<endor_core::CallArity> {
|
||||
Some(endor_core::CallArity::exact(
|
||||
if matches!(
|
||||
@@ -97,6 +114,7 @@ impl NativeCallable for Method {
|
||||
))
|
||||
}
|
||||
|
||||
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
|
||||
fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
|
||||
let mount = cx.store().payload::<Mount>(self.owner, "Mount")?.clone();
|
||||
if !mount.mounted
|
||||
@@ -324,6 +342,7 @@ impl NativeCallable for Method {
|
||||
}
|
||||
}
|
||||
|
||||
/// 声明 Mount 查询方法的源类型契约,区分几何、层次与坐标操作。
|
||||
fn mount_signature(
|
||||
store: &endor_core::ObjectStore,
|
||||
desktop: ObjectRef,
|
||||
@@ -370,12 +389,14 @@ fn mount_signature(
|
||||
}
|
||||
|
||||
#[derive(Debug, Default, Clone)]
|
||||
/// 活动出现的弱索引。真实托管拥有关系在 desktop 的挂载字典中,索引不能充当隐藏 GC 根。
|
||||
pub struct MountTable {
|
||||
pub active: HashMap<u64, WeakObjectRef>,
|
||||
order: Vec<u64>,
|
||||
}
|
||||
|
||||
#[derive(Debug)]
|
||||
/// 同步出现关系时的共享临时工作状态,保存本轮重用、建立和退役安排。
|
||||
struct Sync {
|
||||
desktop: ObjectRef,
|
||||
page: Option<ObjectRef>,
|
||||
@@ -388,6 +409,7 @@ struct Sync {
|
||||
}
|
||||
|
||||
#[derive(Debug)]
|
||||
/// 将一个生命周期回调及参数接入同一 VM 调用序列。
|
||||
struct LifecycleCall {
|
||||
function: ObjectRef,
|
||||
block: ObjectRef,
|
||||
@@ -395,10 +417,12 @@ struct LifecycleCall {
|
||||
unmount: bool,
|
||||
}
|
||||
impl NativeCallable for LifecycleCall {
|
||||
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
|
||||
fn arity(&self) -> Option<endor_core::CallArity> {
|
||||
Some(endor_core::CallArity::exact(0))
|
||||
}
|
||||
|
||||
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
|
||||
fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
|
||||
if self.unmount {
|
||||
crate::tasks::cancel_owner(cx, self.mount)?;
|
||||
@@ -410,6 +434,7 @@ impl NativeCallable for LifecycleCall {
|
||||
}
|
||||
}
|
||||
|
||||
/// 构造生命周期调用所需的托管函数与参数,使回调遵循同一 VM 的引用和执行约束。
|
||||
fn lifecycle_call(
|
||||
cx: &mut NativeContext<'_>,
|
||||
mount: ObjectRef,
|
||||
@@ -437,10 +462,12 @@ fn lifecycle_call(
|
||||
}
|
||||
|
||||
impl NativeCallable for Sync {
|
||||
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
|
||||
fn arity(&self) -> Option<endor_core::CallArity> {
|
||||
Some(endor_core::CallArity::exact(0))
|
||||
}
|
||||
|
||||
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
|
||||
fn invoke(&self, cx: &mut NativeContext<'_>, _args: &[Value]) -> Result<NativeResult, VmError> {
|
||||
let mut blocks = HashMap::new();
|
||||
for weak in &self.nodes {
|
||||
@@ -630,6 +657,7 @@ impl NativeCallable for Sync {
|
||||
|
||||
/// Explicitly owned roots protect the old presentation while preparation
|
||||
/// temporarily replaces its desktop dictionary and Mount payloads.
|
||||
/// 布局准备前的挂载快照与临时保留,用于取消恢复;成功提交后必须释放其保留引用。
|
||||
pub struct Checkpoint {
|
||||
table: MountTable,
|
||||
dictionary: Option<ObjectRef>,
|
||||
@@ -638,6 +666,7 @@ pub struct Checkpoint {
|
||||
}
|
||||
|
||||
impl Checkpoint {
|
||||
/// 释放检查点为回滚临时保留的托管根,成功提交后不再需要这些引用。
|
||||
pub fn release(self, vm: &mut Vm) -> Result<(), VmError> {
|
||||
let mut result = Ok(());
|
||||
for root in self.roots.into_iter().rev() {
|
||||
@@ -648,6 +677,7 @@ impl Checkpoint {
|
||||
result
|
||||
}
|
||||
|
||||
/// 恢复检查点中尚未发布的出现关系与布局上下文,并释放临时保留。
|
||||
pub fn restore(
|
||||
self,
|
||||
vm: &mut Vm,
|
||||
@@ -707,6 +737,7 @@ impl Checkpoint {
|
||||
}
|
||||
|
||||
impl MountTable {
|
||||
/// 保留布局准备前的 Mount 状态,供失败或取消路径恢复。
|
||||
pub fn checkpoint(&self, vm: &mut Vm, desktop: ObjectRef) -> Result<Checkpoint, VmError> {
|
||||
let dictionary = match vm.get_attr(desktop, "mounts") {
|
||||
Ok(Value::Object(dictionary)) => Some(dictionary),
|
||||
@@ -762,6 +793,7 @@ impl MountTable {
|
||||
|
||||
/// A faulted domain cannot run user onUnmount callbacks. Still detach every
|
||||
/// context and release its owning dictionary through the normal heap barrier.
|
||||
/// 退役当前出现表,撤销挂载关系并准备不再展示的生命周期状态。
|
||||
pub fn retire(&mut self, vm: &mut Vm, desktop: ObjectRef) -> Result<(), VmError> {
|
||||
for weak in self.ordered().into_iter().rev() {
|
||||
if let Some(object) = vm.upgrade(weak)? {
|
||||
@@ -788,6 +820,7 @@ impl MountTable {
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// 按原始展示顺序返回弱 Mount 身份,供事件和协议驱动器保持稳定顺序。
|
||||
pub fn ordered(&self) -> Vec<WeakObjectRef> {
|
||||
self.order
|
||||
.iter()
|
||||
@@ -795,6 +828,7 @@ impl MountTable {
|
||||
.collect()
|
||||
}
|
||||
|
||||
/// 根据新结构复用或建立每次出现的 Mount,连接父子关系并准备生命周期调用。
|
||||
pub fn synchronize(
|
||||
&mut self,
|
||||
vm: &mut Vm,
|
||||
|
||||
Reference in New Issue
Block a user