docs: clarify event failure cleanup and VM sequence contracts

This commit is contained in:
2026-11-12 20:53:49 +08:00
parent f0bfbc9fc1
commit 2d5138c7ad
3 changed files with 10 additions and 4 deletions
+4 -1
View File
@@ -18,6 +18,7 @@ fn invalid(message: &'static str) -> VmError {
}
/// ui_bridge::calls 安装 on/onClick 时调用,检查零参或单 Event 回调能力,不在此执行用户函数。
/// 这里只检查 Function 身份和可接受参数数量;Event 的名义参数注解及实际返回/效果由 VM 真正调用时继续检查。
pub fn validate_handler(
store: &endor_core::ObjectStore,
function: ObjectRef,
@@ -475,6 +476,7 @@ impl NativeCallable for Finish {
/// vm_sequence 在所有 Delivery 之后调用,清理当前阶段/守卫并返回最终 Event,供调用方读取默认阻止状态。
fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
// 保留事件最终 prevented 等标志,不用 Event::default 抹掉这一轮处理结果。
// 仅正常走到序列末尾才进入这里;回调报错会中断驱动,届时靠弱 guard 失效解除重入限制,不保证 phase/currentTarget 已清空。
let mut event = cx.store().payload::<Event>(self.0, "Event")?.clone();
// 正常序列结束清递送标记与当前上下文,保留原始 target/mount 和 prevented 供调用方读取。
event.dispatch = None;
@@ -512,6 +514,7 @@ pub fn dispatch(
return Err(invalid("invalid event kind"));
}
// 路线由目标向外保存。无 Mount 的代码事件只访问目标对象,不猜测共享 Block 属于哪个出现。
// kind 和候选连接在构建驱动时选定;后续回调改 event.kind 不会重选本轮列表,Connection.handler 是否已取消则由 Delivery 临时重查。
let mut route = vec![(owner, mount)];
if let Some(mount) = mount {
// 克隆出现 payload 后沿其 parent/page 弱边构建路径,和 Block.children 的业务组成分开。
@@ -646,7 +649,7 @@ pub fn dispatch(
Finish(event_ref),
vec![event_ref, guard],
))?;
// 无论传播是否被停止,Finish 都作为序列最后一项执行,它不受 Delivery 的 stopped 判定影响。
// 停止传播只让 Delivery 跳过处理器,Finish 仍作为序列最后一项执行;若处理器抛错则整段序列失败,不保证进入 Finish。
calls.push(finish);
// 驱动常量池拥有完整顺序,全部处理器共用调用者 VM 的预算,不能逐个 vm.call 重置额度。
let driver = crate::vm_sequence::build(cx, calls, "<event dispatch>", desktop)?;