docs: explain graphics resources and runtime dispatch lifecycles
This commit is contained in:
@@ -1,8 +1,9 @@
|
||||
//! 托管事件与订阅的传播实现。Connection 持有回调引用,Event 保存目标、阶段与停止传播状态。
|
||||
//! 分发沿出现关系执行 capture → target → bubble,记录默认行为阻止状态;只有同一 VM 中的回调可以接触托管对象。
|
||||
//!
|
||||
//! Managed subscriptions and occurrence-specific propagation. A validated VM
|
||||
//! function sequences calls, so all handlers share one execution budget.
|
||||
//! bootstrap 调用 install 安装 Event/Subscription 控制方法;ui_bridge::calls 和 graphics/scene3d 指针适配调用 dispatch。
|
||||
//! dispatch 只快照路线并生成驱动,真正回调执行由 VM 调用 Delivery,再通过 Invoke 接回源处理器。
|
||||
//! vm_sequence::build 使整次传播共用同一执行预算;每次具体 Mount 是独立传播上下文,不从共享业务树猜父链。
|
||||
use crate::{block, mount::Mount, ui_bridge::attach_desktop_type};
|
||||
use endor_core::{
|
||||
ContextNativeFunction, NativeCallable, NativeContext, NativeResult, ObjectPayload, ObjectRef,
|
||||
@@ -11,19 +12,21 @@ use endor_core::{
|
||||
|
||||
// 一次分发最多安排 10000 个处理器,另由共享 VM 驱动约束全部回调的总执行预算。
|
||||
const MAX_DELIVERIES: usize = 10_000;
|
||||
/// 统一构造本模块的参数错误,让调用方停止处理无效输入。
|
||||
/// 订阅检查、事件构造与传播分支共用的参数错误构造器,源诊断位置由外层 VM 调用栈提供。
|
||||
fn invalid(message: &'static str) -> VmError {
|
||||
VmError::InvalidArgument(message)
|
||||
}
|
||||
|
||||
/// 检查订阅回调满足事件处理器调用契约,避免等到实际点击才暴露签名错误。
|
||||
/// ui_bridge::calls 安装 on/onClick 时调用,检查零参或单 Event 回调能力,不在此执行用户函数。
|
||||
pub fn validate_handler(
|
||||
store: &endor_core::ObjectStore,
|
||||
function: ObjectRef,
|
||||
) -> Result<(), VmError> {
|
||||
if !store.object(function)?.payload().is_function() {
|
||||
// 普通 Object 即使有 call 属性也不能作为这里的 Function 注册,避免实际分派才暴露类型错误。
|
||||
return Err(invalid("event handler must be a Function"));
|
||||
}
|
||||
// 元数据必须明确存在;不能把未知 arity 当作“随便传一个 Event 总能工作”。
|
||||
let arity = store
|
||||
.call_arity(function)?
|
||||
.ok_or(invalid("event handler requires positional metadata"))?;
|
||||
@@ -72,8 +75,11 @@ impl ObjectPayload for Event {
|
||||
#[derive(Debug, Clone)]
|
||||
/// 实际拥有回调引用的托管连接,挂在目标的订阅关系中参与 GC。
|
||||
pub struct Connection {
|
||||
// Block 的 subscriptions 强持 Connection,Connection 再强持 handler;取消时将这一强边置空。
|
||||
pub handler: Option<ObjectRef>,
|
||||
// 与 Event.kind 比较的精确事件字符串,不对事件名称做前缀或真值匹配。
|
||||
pub kind: String,
|
||||
// 区分捕获和非捕获队列;目标阶段两种队列仍共享一个传播组。
|
||||
pub capture: bool,
|
||||
}
|
||||
impl ObjectPayload for Connection {
|
||||
@@ -92,15 +98,16 @@ impl ObjectPayload for Connection {
|
||||
/// 枚举本对象真正拥有的托管强引用,供 Aster 引用追踪和循环回收使用。
|
||||
fn trace(&self, visit: &mut dyn FnMut(ObjectRef)) {
|
||||
if let Some(handler) = self.handler {
|
||||
// Aster GC 访问者只收到当前仍连接的处理器;None 不再保活旧回调及它捕获的业务对象。
|
||||
visit(handler);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// A token never retains its target or callback. The Block owns the connection.
|
||||
#[derive(Debug)]
|
||||
/// 源代码可保留的订阅能力包装,用于取消对应连接。
|
||||
pub struct Subscription {
|
||||
// 事件 Connection 或属性 Binding 的弱引用;用户长期保留 token 不应反向保活目标和计算闭包。
|
||||
pub connection: WeakObjectRef,
|
||||
}
|
||||
impl ObjectPayload for Subscription {
|
||||
@@ -119,7 +126,7 @@ impl ObjectPayload for Subscription {
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy)]
|
||||
/// 保存 owner、签名或操作枚举的原生方法适配器,统一由 VM 调用。
|
||||
/// install 的名义方法表选用的操作标签;TypedMethod 提供类型契约,Method 只执行对应状态变化/查询。
|
||||
enum Method {
|
||||
Stop,
|
||||
StopImmediate,
|
||||
@@ -134,17 +141,21 @@ impl NativeCallable for Method {
|
||||
Some(endor_core::CallArity::exact(1))
|
||||
}
|
||||
|
||||
/// 按操作读取或修改连接/传播状态;断开清除真实 handler/compute,停止标志写回同一 Event。
|
||||
/// TypedMethod::invoke 转交,按 receiver payload 查询/取消订阅,或更新当前事件传播控制标志。
|
||||
fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
|
||||
// 方法接收者仍在 args[0];不像 UiBridge 的 TypeMethod,这个包装没有提前把 owner 剥出来。
|
||||
let [Value::Object(owner)] = args else {
|
||||
return Err(invalid("event method receiver"));
|
||||
};
|
||||
// 取消/查询订阅和传播控制使用不同 payload,先按方法标签分流再进行受检查的向下转型。
|
||||
let result = match self {
|
||||
Self::Disconnect | Self::Connected => {
|
||||
// Subscription 不直接拥有 Connection,读弱身份后在当前 NativeContext 中临时升级。
|
||||
let weak = cx
|
||||
.store()
|
||||
.payload::<Subscription>(*owner, "Subscription")?
|
||||
.connection;
|
||||
// 已死亡连接正常得到 None,isConnected=false/disconnect 无动作,而不是新建连接。
|
||||
let connection = cx.upgrade(weak)?;
|
||||
// Subscription 同时包装事件 Connection 和属性 Binding;按 payload 类型清 handler 或 compute。
|
||||
let connected = if let Some(connection) = connection {
|
||||
@@ -155,10 +166,12 @@ impl NativeCallable for Method {
|
||||
.as_any()
|
||||
.is::<crate::binding::Binding>()
|
||||
{
|
||||
// 属性绑定和事件订阅复用同一种取消令牌,但 Binding 的真实强边字段是 compute。
|
||||
let mut data = cx
|
||||
.store()
|
||||
.payload::<crate::binding::Binding>(connection, "Binding")?
|
||||
.clone();
|
||||
// 返回查询的是操作前连接状态;disconnect 自己最后返回 Unit,不暴露该布尔。
|
||||
let connected = data.compute.is_some();
|
||||
// 取消切断真实强拥有边,外部仍可保留 token,但 token 弱引用本身不保活回调或目标。
|
||||
if matches!(self, Self::Disconnect) {
|
||||
@@ -167,10 +180,12 @@ impl NativeCallable for Method {
|
||||
}
|
||||
connected
|
||||
} else {
|
||||
// 其余合法令牌包装事件 Connection,不用 Binding 的字段布局读取它。
|
||||
let mut data = cx
|
||||
.store()
|
||||
.payload::<Connection>(connection, "Connection")?
|
||||
.clone();
|
||||
// handler=None 就是已断开,保留 Connection 对象本身不代表回调仍可执行。
|
||||
let connected = data.handler.is_some();
|
||||
if matches!(self, Self::Disconnect) {
|
||||
data.handler = None;
|
||||
@@ -179,24 +194,30 @@ impl NativeCallable for Method {
|
||||
connected
|
||||
}
|
||||
} else {
|
||||
// 弱目标已经死亡与主动断开都属于不再连接,查询不因此报过期对象错误。
|
||||
false
|
||||
};
|
||||
if matches!(self, Self::Disconnect) {
|
||||
// API 约定取消返回 Unit,只有 isConnected 返回前面采样到的布尔。
|
||||
Value::Nil
|
||||
} else {
|
||||
Value::Bool(connected)
|
||||
}
|
||||
}
|
||||
_ => {
|
||||
// 传播标志属于 Event payload,复制后经 replace_payload 写回以保持 store 的写屏障。
|
||||
let mut event = cx.store().payload::<Event>(*owner, "Event")?.clone();
|
||||
if matches!(self, Self::Prevented) {
|
||||
// 只读查询不替换 payload,不制造一次虚假的事件变更。
|
||||
Value::Bool(event.prevented)
|
||||
} else {
|
||||
match self {
|
||||
Self::Stop | Self::StopImmediate => {
|
||||
// Stop 保留当前组的其余回调,Immediate 额外跳过同组后续 Delivery。
|
||||
event.stopped_at = Some(event.group);
|
||||
event.immediate |= matches!(self, Self::StopImmediate);
|
||||
}
|
||||
// 只记录阻止默认,不在本模块额外调用或取消某个 OS 默认动作。
|
||||
Self::Prevent => event.prevented = true,
|
||||
_ => unreachable!(),
|
||||
}
|
||||
@@ -212,6 +233,7 @@ impl NativeCallable for Method {
|
||||
#[derive(Debug)]
|
||||
/// 安装到托管类型上的原生构造调用适配器。
|
||||
pub struct Constructor {
|
||||
// bootstrap 在 Event 类型/签名都建立后补入,VM 据此先检查 Type/kind/字段外壳。
|
||||
pub signature: Option<endor_core::CallSignature>,
|
||||
}
|
||||
impl NativeCallable for Constructor {
|
||||
@@ -224,8 +246,9 @@ impl NativeCallable for Constructor {
|
||||
Some(endor_core::CallArity::range(2, usize::MAX))
|
||||
}
|
||||
|
||||
/// 先验证事件子类字段数量与注解,再创建原生 Event 并填充声明字段,错误不得留下部分实例。
|
||||
/// VM 执行 Event/源子类 NativeTyped 构造器时调用,验证字段前不先分配业务 Event,避免非法字段副作用。
|
||||
fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
|
||||
// definition 是实际请求子类,kind 是唯一原生构造参数,其余后缀对应声明字段。
|
||||
let [Value::Object(definition), Value::Text(kind), values @ ..] = args else {
|
||||
return Err(invalid("Event requires an event kind"));
|
||||
};
|
||||
@@ -236,19 +259,22 @@ impl NativeCallable for Constructor {
|
||||
.fields()
|
||||
.to_vec();
|
||||
if fields.len() != values.len() {
|
||||
// 不用 zip 静默截断少/多实参,完整类型字段数量必须与输入后缀一致。
|
||||
return Err(invalid("incorrect Event field arguments"));
|
||||
}
|
||||
cx.store()
|
||||
.check_class_field_arguments(*definition, values)?;
|
||||
// 数量和类型都检查后才创建真实子类 Event;NativeContext 会清理未输出的临时根。
|
||||
let event = new_event(cx, *definition, kind)?;
|
||||
for (field, value) in fields.iter().zip(values) {
|
||||
// 用普通属性写入口初始化字段,保持对象引用和依赖记录受 VM 统一管理。
|
||||
cx.set_attr(event, &field.name, value.clone())?;
|
||||
}
|
||||
Ok(NativeResult::Return(Value::Object(event)))
|
||||
}
|
||||
}
|
||||
|
||||
/// 建立本次分发拥有的托管 Event,保存目标、输入与传播控制状态。
|
||||
/// Event 构造器、click 和图形/三维指针适配调用,建立尚未分派的带名义身份事件;目标由 dispatch 填写。
|
||||
pub fn new_event(
|
||||
cx: &mut NativeContext<'_>,
|
||||
definition: ObjectRef,
|
||||
@@ -257,11 +283,13 @@ pub fn new_event(
|
||||
if kind.is_empty() || kind.len() > 128 {
|
||||
return Err(invalid("event kind must contain 1..128 UTF-8 bytes"));
|
||||
}
|
||||
// payload 默认标志与普通属性分开:停止/默认阻止在 payload,目标/阶段信息通过托管属性公开。
|
||||
let event = cx.allocate(Event::default())?;
|
||||
cx.attach_type(event, definition)?;
|
||||
cx.set_attr(event, "kind", Value::Text(kind.into()))?;
|
||||
// 新事件尚未递送,目标、出现与 hit 都为空;kind 保留输入种类,phase 初始 none。
|
||||
for name in ["target", "mount", "currentTarget", "currentMount", "hit"] {
|
||||
// 初始化明确的 nil,处理器读取未分派事件时不会因字段缺失而失败。
|
||||
cx.set_attr(event, name, Value::Nil)?;
|
||||
}
|
||||
cx.set_attr(event, "phase", Value::Text("none".into()))?;
|
||||
@@ -269,8 +297,9 @@ pub fn new_event(
|
||||
}
|
||||
|
||||
#[derive(Debug)]
|
||||
/// 带事件类型签名和 owner 的原生方法包装。
|
||||
/// install 挂到 Event/Subscription 类型上的签名包装;实例 receiver 由 VM 方法绑定机制传入。
|
||||
struct TypedMethod {
|
||||
// 无状态操作标签,实际事件/订阅状态都在本次传入 receiver 的托管 payload 中。
|
||||
method: Method,
|
||||
signature: endor_core::CallSignature,
|
||||
}
|
||||
@@ -285,7 +314,7 @@ impl NativeCallable for TypedMethod {
|
||||
}
|
||||
}
|
||||
|
||||
/// 把本模块的类型、方法或能力注册到所属运行时上下文。
|
||||
/// ui_bridge::bootstrap 完成 Event/Subscription/Function 类型建立后调用,为两类对象安装控制与查询方法。
|
||||
pub fn install(
|
||||
vm: &mut Vm,
|
||||
roots: &mut Vec<ObjectRef>,
|
||||
@@ -307,6 +336,7 @@ pub fn install(
|
||||
] {
|
||||
// isDefaultPrevented/isConnected 返回 Bool 且只读;控制传播和取消方法返回 Unit 并声明 Mutating。
|
||||
let query = matches!(method, Method::Prevented | Method::Connected);
|
||||
// callable 接一个隐式名义 receiver,查询返回 Bool/ReadOnly,修改返回 Unit/Mutating。
|
||||
let function = vm.allocate(ContextNativeFunction::new(
|
||||
name,
|
||||
TypedMethod {
|
||||
@@ -314,10 +344,13 @@ pub fn install(
|
||||
signature: endor_core::CallSignature::exact(
|
||||
vec![endor_core::AnnotationType::Nominal(definition)],
|
||||
if query {
|
||||
// isDefaultPrevented/isConnected 的返回类型是布尔,不把“无连接”写成 nil。
|
||||
endor_core::AnnotationType::Bool
|
||||
} else {
|
||||
// 控制/取消操作没有业务返回值,VM 用 Unit 检查而非任意 Any。
|
||||
endor_core::AnnotationType::Unit
|
||||
},
|
||||
// 同一个标签同时决定调用效果,不能让断开连接冒充只读查询。
|
||||
if query {
|
||||
endor_core::CallEffect::ReadOnly
|
||||
} else {
|
||||
@@ -337,18 +370,27 @@ pub fn install(
|
||||
#[derive(Debug)]
|
||||
/// 本次递送选择的对象方法或显式订阅处理器。
|
||||
enum Handler {
|
||||
// 捕获 Connection 对象而非函数快照,前面回调 disconnect 后本项会重新观察 handler=None。
|
||||
Token(ObjectRef),
|
||||
// onClick 的旧式单处理器是本轮函数快照,不具有独立 Connection 令牌。
|
||||
Legacy(ObjectRef),
|
||||
// onEvent 从实际类型的方法表在轮到本项时解析,以保留继承/源覆盖。
|
||||
ObjectMethod,
|
||||
}
|
||||
#[derive(Debug)]
|
||||
/// 事件传播过程中将要调用的一项处理器及其阶段/目标上下文。
|
||||
struct Delivery {
|
||||
// 本轮事件由 captures 显式保活;payload 中的数值句柄本身不构成 VM 强边。
|
||||
event: ObjectRef,
|
||||
// 当前路径项的业务对象,不一定是最终 target;祖先捕获/冒泡也用相同适配器。
|
||||
owner: ObjectRef,
|
||||
// 该路径项的具体出现,页面上下文无 Mount 时为 None。
|
||||
mount: Option<ObjectRef>,
|
||||
// stopPropagation 的边界编号;目标捕获与非捕获共享组,其他出现/阶段递增。
|
||||
group: usize,
|
||||
// 对外公开的 capture/target/bubble 字符串,与 group 的内部停止规则分别保存。
|
||||
phase: &'static str,
|
||||
// 处理器的解析策略,决定是否需要临时取连接或补 receiver。
|
||||
handler: Handler,
|
||||
}
|
||||
impl NativeCallable for Delivery {
|
||||
@@ -357,13 +399,16 @@ impl NativeCallable for Delivery {
|
||||
Some(endor_core::CallArity::exact(0))
|
||||
}
|
||||
|
||||
/// 轮到该处理器时重查传播状态和连接是否仍有效,更新当前阶段/目标,再按真实回调 arity 发出 VM 调用。
|
||||
/// vm_sequence 驱动轮到本项时调用,重查停止/连接状态,再用 Invoke 交给同预算的真实处理器。
|
||||
fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
|
||||
// 不是快照整个传播开始时的标志,前一个回调产生的 stop 必须立刻影响当前项。
|
||||
let mut event = cx.store().payload::<Event>(self.event, "Event")?.clone();
|
||||
// 真正轮到处理器时重新读取传播状态,之前回调的 stop 操作立即影响后续项,无需重建序列。
|
||||
if event.immediate || event.stopped_at.is_some_and(|group| group != self.group) {
|
||||
// 跳过此项仍返回正常 Nil,让驱动继续推进到其他跳过项和最终 Finish 清理。
|
||||
return Ok(NativeResult::Return(Value::Nil));
|
||||
}
|
||||
// 函数与参数前缀一起解析:对象协议需 receiver,独立处理器最初没有显式参数。
|
||||
let (function, mut arguments) = match self.handler {
|
||||
// 序列只捕获 Connection,不快照 handler;前面处理器取消它后,这里看到 None 并跳过。
|
||||
Handler::Token(token) => {
|
||||
@@ -372,6 +417,7 @@ impl NativeCallable for Delivery {
|
||||
.payload::<Connection>(token, "Connection")?
|
||||
.handler
|
||||
else {
|
||||
// 已断开连接不再调用旧 handler,即使驱动已经为它分配过 Delivery。
|
||||
return Ok(NativeResult::Return(Value::Nil));
|
||||
};
|
||||
(handler, vec![])
|
||||
@@ -379,9 +425,11 @@ impl NativeCallable for Delivery {
|
||||
Handler::Legacy(function) => (function, vec![]),
|
||||
// 对象协议在执行到该项时解析实际类型的 onEvent;显式 receiver 先放入实参向量。
|
||||
Handler::ObjectMethod => {
|
||||
// 动态源子类的 onEvent 可以不同于基类默认空实现,不能在安装时固定函数。
|
||||
let Some(definition) = cx.store().type_of(self.owner)? else {
|
||||
return Err(invalid("untyped event target"));
|
||||
};
|
||||
// 按类型继承查方法,缺少协议方法是契约错误,不降级忽略对象事件能力。
|
||||
let function = cx
|
||||
.store()
|
||||
.lookup_method(definition, "onEvent")?
|
||||
@@ -406,6 +454,7 @@ impl NativeCallable for Delivery {
|
||||
.call_arity(function)?
|
||||
.is_some_and(|arity| arity.accepts(1))
|
||||
{
|
||||
// 单 Event 回调优先;仅真正不接受一参但接受零参的便捷处理器才不追加事件。
|
||||
arguments.push(Value::Object(self.event));
|
||||
}
|
||||
Ok(NativeResult::Invoke {
|
||||
@@ -423,8 +472,9 @@ impl NativeCallable for Finish {
|
||||
Some(endor_core::CallArity::exact(0))
|
||||
}
|
||||
|
||||
/// 正常序列结束时清除活跃派发守卫与当前上下文,保留 target/prevented 并返回实际 Event,允许后续重用。
|
||||
/// vm_sequence 在所有 Delivery 之后调用,清理当前阶段/守卫并返回最终 Event,供调用方读取默认阻止状态。
|
||||
fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
|
||||
// 保留事件最终 prevented 等标志,不用 Event::default 抹掉这一轮处理结果。
|
||||
let mut event = cx.store().payload::<Event>(self.0, "Event")?.clone();
|
||||
// 正常序列结束清递送标记与当前上下文,保留原始 target/mount 和 prevented 供调用方读取。
|
||||
event.dispatch = None;
|
||||
@@ -436,10 +486,8 @@ impl NativeCallable for Finish {
|
||||
}
|
||||
}
|
||||
|
||||
/// Snapshot the selected occurrence's route and listener order. Disconnection
|
||||
/// before a listener's turn skips it; newly registered listeners wait for the
|
||||
/// next dispatch. A code event without a Mount visits only its target object.
|
||||
/// 快照 Mount 路径和订阅顺序,构造共享预算的 capture/target/bubble 驱动并返回 VM 续调。
|
||||
/// ui_bridge::calls 的 click/dispatch 及指针适配调用,构造本轮路线/处理顺序,再返回 VM 驱动续调。
|
||||
/// 无 Mount 的代码事件只访问 owner,不猜测共享对象位于哪个窗口;新订阅不加入本轮,取消可立即跳过旧项。
|
||||
pub fn dispatch(
|
||||
cx: &mut NativeContext<'_>,
|
||||
owner: ObjectRef,
|
||||
@@ -447,13 +495,16 @@ pub fn dispatch(
|
||||
mount: Option<ObjectRef>,
|
||||
desktop: ObjectRef,
|
||||
) -> Result<NativeResult, VmError> {
|
||||
// 先检查真实 Event payload,复制是为了稍后重置传播标志并经写屏障写回。
|
||||
let mut event = cx.store().payload::<Event>(event_ref, "Event")?.clone();
|
||||
// 只有 guard 仍存活才禁止重入;此前分发失败但 guard 已释放时,不让旧弱身份永久锁住 Event。
|
||||
if let Some(weak) = event.dispatch
|
||||
&& cx.upgrade(weak)?.is_some()
|
||||
{
|
||||
// 同 Event 不可重入分发;若上轮驱动已因失败释放,弱 guard 失效则允许重新使用。
|
||||
return Err(invalid("Event is already being dispatched"));
|
||||
}
|
||||
// kind 可以是源程序改过的普通属性,所以每次 dispatch 都重新验证实际字符串和长度。
|
||||
let Value::Text(kind) = cx.store().get_attr(event_ref, "kind")? else {
|
||||
return Err(invalid("Event kind must be text"));
|
||||
};
|
||||
@@ -463,21 +514,26 @@ pub fn dispatch(
|
||||
// 路线由目标向外保存。无 Mount 的代码事件只访问目标对象,不猜测共享 Block 属于哪个出现。
|
||||
let mut route = vec![(owner, mount)];
|
||||
if let Some(mount) = mount {
|
||||
// 克隆出现 payload 后沿其 parent/page 弱边构建路径,和 Block.children 的业务组成分开。
|
||||
let target = cx.store().payload::<Mount>(mount, "Mount")?.clone();
|
||||
// 传入 Mount 必须仍挂接且确实展示 owner;同一 Block 的另一个出现不能替代该上下文。
|
||||
if !target.mounted || target.block != owner {
|
||||
return Err(invalid("event context does not belong to this Block"));
|
||||
}
|
||||
// parent 是下一祖先弱身份,目标先放进 seen,防止父链回到自身。
|
||||
let mut parent = target.parent;
|
||||
// 沿弱 parent 链构建本轮路径快照,检查死亡祖先、脱离与环;不通过 Block 业务孩子关系反推祖先。
|
||||
let mut seen = std::collections::HashSet::from([mount]);
|
||||
while let Some(weak) = parent {
|
||||
// NativeContext 跟踪升级根,驱动 captures 将保留真正需要的祖先直到本轮执行结束。
|
||||
let ancestor = cx
|
||||
.upgrade(weak)?
|
||||
.ok_or(invalid("event route has expired"))?;
|
||||
if !seen.insert(ancestor) {
|
||||
// 循环父链不能让宿主构造无限驱动,遇重复身份立即拒绝。
|
||||
return Err(invalid("cyclic event route"));
|
||||
}
|
||||
// 祖先存在还不够,必须仍挂载,不能把历史出现关系当成当前传播路径。
|
||||
let data = cx.store().payload::<Mount>(ancestor, "Mount")?;
|
||||
if !data.mounted {
|
||||
return Err(invalid("event route is detached"));
|
||||
@@ -487,15 +543,17 @@ pub fn dispatch(
|
||||
}
|
||||
// 出现祖先之外再加入 Page 上下文,页面本身无 currentMount;弱页已失效则拒绝该旧路线。
|
||||
if let Some(weak) = target.page {
|
||||
// 页面属于传播最外层语义目标,但没有它自己的内容 Mount,所以 route 中配 None。
|
||||
let page = cx.upgrade(weak)?.ok_or(invalid("event Page has expired"))?;
|
||||
route.push((page, None));
|
||||
}
|
||||
}
|
||||
// 所有递送和 Finish 显式捕获 guard,Event 只弱引用它;驱动完成/失败释放后 guard 自动结束本轮资格。
|
||||
let guard = cx.new_object()?;
|
||||
// 按最终递送顺序存临时 callable,vm_sequence::build 随后让它们成为驱动常量强边。
|
||||
let mut calls = Vec::new();
|
||||
// 每个出现/阶段有自己的停止边界;同业务对象多次出现也不能共用一个 group。
|
||||
let mut group = 0;
|
||||
// Each occurrence is its own propagation group, even for shared Blocks.
|
||||
// 先从最外层向目标递送捕获,再从目标向外递送非捕获;目标两次遍历都标记 phase=target。
|
||||
let traversal = route
|
||||
.iter()
|
||||
@@ -509,15 +567,19 @@ pub fn dispatch(
|
||||
.map(|(index, entry)| (index, entry, false)),
|
||||
);
|
||||
for (index, &(block, current_mount), capture) in traversal {
|
||||
// block 可能是共享转发别名,解析到实际 Data 后读取本轮回调/订阅列表。
|
||||
let (_, data) = block::resolve(cx.store(), block)?;
|
||||
// 此路径项的候选处理顺序,稍后逐项包装成独立 Delivery。
|
||||
let mut handlers = Vec::new();
|
||||
// 本轮先快照符合事件 kind 与 capture 的订阅顺序;回调期间新注册的连接不进入当前分发。
|
||||
for token in &data.subscriptions {
|
||||
// subscriptions 保存的是 Connection 而非用户持有的 Subscription 令牌。
|
||||
let token_data = cx.store().payload::<Connection>(*token, "Connection")?;
|
||||
if token_data.handler.is_some()
|
||||
&& token_data.kind == kind
|
||||
&& token_data.capture == capture
|
||||
{
|
||||
// 这里只快照连接身份,handler 的存活在真正执行 Delivery 时再次读取。
|
||||
handlers.push(Handler::Token(*token));
|
||||
}
|
||||
}
|
||||
@@ -527,22 +589,28 @@ pub fn dispatch(
|
||||
if kind == "click"
|
||||
&& let Some(handler) = data.click
|
||||
{
|
||||
// 旧式 onClick 仅匹配 click 且只在非捕获阶段执行,不变成所有事件通用监听器。
|
||||
handlers.push(Handler::Legacy(handler));
|
||||
}
|
||||
}
|
||||
for handler in handlers {
|
||||
if calls.len() >= MAX_DELIVERIES {
|
||||
// 总量包括所有祖先和阶段,不能让每个节点各用 10000 额度放大一次分发。
|
||||
return Err(invalid("event delivery budget exceeded"));
|
||||
}
|
||||
// 每一项显式保活本轮 Event、guard、目标和可选 Mount/连接;不能仅靠 Rust ObjectRef 值当 GC 根。
|
||||
let mut captures = vec![event_ref, guard, block];
|
||||
if let Some(mount) = current_mount {
|
||||
// captures 保留这一具体出现,不能只保留业务 Block 丢掉几何/祖先上下文。
|
||||
captures.push(mount);
|
||||
}
|
||||
match handler {
|
||||
// Connection 或旧函数必须有真实托管强边,Rust 枚举里的句柄数值不保活它们。
|
||||
Handler::Token(token) | Handler::Legacy(token) => captures.push(token),
|
||||
// 对象方法在轮到时查找,owner 已在 captures,不提前强持某个可能被覆盖的函数。
|
||||
Handler::ObjectMethod => {}
|
||||
}
|
||||
// 分配一个零参步骤;真实用户函数的 receiver/Event 参数由 Delivery::invoke 再决定。
|
||||
let function = cx.allocate(ContextNativeFunction::new(
|
||||
"event delivery",
|
||||
Delivery {
|
||||
@@ -551,10 +619,13 @@ pub fn dispatch(
|
||||
mount: current_mount,
|
||||
group,
|
||||
phase: if index == 0 {
|
||||
// 路线 index=0 始终是最终目标,目标捕获/非捕获都对外显示 target。
|
||||
"target"
|
||||
} else if capture {
|
||||
// 从外层向目标的祖先遍历显示 capture。
|
||||
"capture"
|
||||
} else {
|
||||
// 从目标向外层的祖先遍历显示 bubble。
|
||||
"bubble"
|
||||
},
|
||||
handler,
|
||||
@@ -564,13 +635,12 @@ pub fn dispatch(
|
||||
attach_desktop_type(cx, function, "Function", desktop)?;
|
||||
calls.push(function);
|
||||
}
|
||||
// Capture and bubble at the target are one group: stopPropagation at
|
||||
// target capture still permits other target listeners.
|
||||
// 目标捕获后不递增 group,使 stopPropagation 仍允许目标非捕获处理器;其他路径/阶段则隔离为新组。
|
||||
if index != 0 || !capture {
|
||||
group += 1;
|
||||
}
|
||||
}
|
||||
// Finish 也捕获 guard,保证即使没有任何用户监听器,整次驱动仍维持活跃分发资格到结束。
|
||||
let finish = cx.allocate(ContextNativeFunction::new(
|
||||
"event finish",
|
||||
Finish(event_ref),
|
||||
@@ -578,6 +648,7 @@ pub fn dispatch(
|
||||
))?;
|
||||
// 无论传播是否被停止,Finish 都作为序列最后一项执行,它不受 Delivery 的 stopped 判定影响。
|
||||
calls.push(finish);
|
||||
// 驱动常量池拥有完整顺序,全部处理器共用调用者 VM 的预算,不能逐个 vm.call 重置额度。
|
||||
let driver = crate::vm_sequence::build(cx, calls, "<event dispatch>", desktop)?;
|
||||
event.dispatch = Some(cx.store().downgrade(guard)?);
|
||||
event.group = 0;
|
||||
@@ -592,6 +663,7 @@ pub fn dispatch(
|
||||
"mount",
|
||||
mount.map(Value::Object).unwrap_or(Value::Nil),
|
||||
)?;
|
||||
// 仅委托驱动,不在本 Rust 调用栈递归执行用户回调;VM 后续负责返回最终 Event。
|
||||
Ok(NativeResult::Invoke {
|
||||
function: driver,
|
||||
arguments: vec![],
|
||||
|
||||
Reference in New Issue
Block a user