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
+3 -2
View File
@@ -32,6 +32,7 @@ impl SourcePlan {
/// endor_host 执行入口调用,优先接受完整 Module,失败则按顶层换行候选边界拼出 Aster 可解析的交互输入。
/// 模块解析失败本身不立即作为最终错误:普通顶层脚本本就需要走后面的 Interactive 解析路径。
/// 这里只产出 AST 计划,不执行已接受的片段;endor_host 先完成所有根的预算检查和编译,再进入源代码执行。
pub fn parse(source: &SourceUnit) -> Result<SourcePlan> {
// 完整模块优先;只有模块解析失败才退回连续交互输入模式,宿主不自行实现 Endor 语法。
if let Ok(module) = frontend::parse_source_ast(source, ParseMode::Module) {
@@ -99,9 +100,9 @@ pub fn parse(source: &SourceUnit) -> Result<SourcePlan> {
}
}
}
// 空输入不能静默产生空计划;再次委托交互入口给出解析器自己的空输入诊断与来源。
// 没有接受任何片段时,再把完整输入交给前端校验;是否为空输入/注释及是否可接受,仍由前端定义。
if roots.is_empty() {
// 不自造宿主错误字符串,保留前端对空输入的原始诊断和 SourceUnit 来源信息。
// 不自造宿主错误字符串;失败则保留前端诊断,成功也不把这次仅用于校验的根追加到 roots。
frontend::parse_source_ast(source, ParseMode::Interactive)?;
}
Ok(SourcePlan::Script(roots))
+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)?;
+3 -1
View File
@@ -5,6 +5,7 @@
//! source_layout/source_paint 用 repeat_call 循环推进出现位置,并用 collect_and_continue 收集单次源调用结果。
//! 本模块只生成驱动字节码和托管函数,不在 Rust 中自行解释语句,也不替调用方重置 VM 预算。
//! 原生调用返回 Invoke 后,VM 在既有帧循环中执行驱动,因此可挂起工作仍有明确的 owning VM。
//! build 串联的是普通调用序列,任一步报错便中断后续步骤;末项不是 finally,错误时临时根/检查点仍须由所属工作收尾路径释放。
use endor_core::{
CodeLayout, EndorCode, EndorCodeObject, Instruction, NativeContext, ObjectRef, Opcode, Value,
VmError,
@@ -63,7 +64,7 @@ pub fn repeat_call(
name: &'static str,
desktop: ObjectRef,
) -> Result<ObjectRef, VmError> {
// 回调返回 Bool;repeat_while 消费这个条件并决定是否跳回本帧开头。
// 内部 Advance 回调约定返回 Bool;repeat_while 生成的是 VM 真值条件跳转,不额外验证返回值必须是 Bool。
// 退出后显式返回 Nil,回调的继续条件不会泄露为驱动返回值。
let mut instructions = vec![
Instruction::new(Opcode::LoadConst, 0),
@@ -96,6 +97,7 @@ pub fn collect_and_continue(
desktop: ObjectRef,
) -> Result<ObjectRef, VmError> {
// 常量布局固定为 collector、function、各实参、true。
// function 或 collector 失败时不会装入最终 true,外层循环也不会自动跳过失败节点;本助手不捕获或重试源错误。
// 先把 collector 的调用前缀压栈,再执行 function,使其返回值直接成为 collector 的唯一实参。
// count 同时确定 Call 的显式参数数和 true 常量的池位置,不能把 collector 的一参计入它。
let count = arguments.len();