docs: 逐模块细化中文逻辑注释并覆盖测试与示例
This commit is contained in:
@@ -7,13 +7,17 @@ use endor_core::{
|
||||
VmError,
|
||||
};
|
||||
|
||||
/// 根据当前输入构造本模块的派生结果,具体的验证与资源边界见函数内步骤。
|
||||
/// 将零参数调用列表编成一个托管驱动,按输入顺序执行,返回最后一次调用的值。
|
||||
/// 空列表返回 Nil。所有调用都在调用者的 VM 预算内运行,避免宿主逐个调用时重置预算。
|
||||
/// name 用于诊断位置;desktop 用来给生成函数挂接桌面 Function 类型。
|
||||
pub fn build(
|
||||
cx: &mut NativeContext<'_>,
|
||||
calls: Vec<ObjectRef>,
|
||||
name: &'static str,
|
||||
desktop: ObjectRef,
|
||||
) -> Result<ObjectRef, VmError> {
|
||||
// 每个函数放入常量池。LoadConst/PushNull/Call 组成零参数调用,
|
||||
// 中间结果由 PopTop 丢弃;最后结果留在栈顶交给 ReturnValue。
|
||||
let mut instructions = Vec::with_capacity(calls.len() * 4 + 2);
|
||||
let mut constants: Vec<Value> = calls.into_iter().map(Value::Object).collect();
|
||||
for index in 0..constants.len() {
|
||||
@@ -24,6 +28,7 @@ pub fn build(
|
||||
instructions.push(Instruction::simple(Opcode::PopTop));
|
||||
}
|
||||
}
|
||||
// 没有调用时也必须给 ReturnValue 提供合法栈顶,不能返回一个空栈。
|
||||
if constants.is_empty() {
|
||||
constants.push(Value::Nil);
|
||||
instructions.push(Instruction::new(Opcode::LoadConst, 0));
|
||||
@@ -47,6 +52,8 @@ pub fn repeat_call(
|
||||
name: &'static str,
|
||||
desktop: ObjectRef,
|
||||
) -> Result<ObjectRef, VmError> {
|
||||
// 回调返回 Bool;repeat_while 消费这个条件并决定是否跳回本帧开头。
|
||||
// 退出后显式返回 Nil,回调的继续条件不会泄露为驱动返回值。
|
||||
let mut instructions = vec![
|
||||
Instruction::new(Opcode::LoadConst, 0),
|
||||
Instruction::simple(Opcode::PushNull),
|
||||
@@ -77,6 +84,8 @@ pub fn collect_and_continue(
|
||||
name: &'static str,
|
||||
desktop: ObjectRef,
|
||||
) -> Result<ObjectRef, VmError> {
|
||||
// 常量布局固定为 collector、function、各实参、true。
|
||||
// 先把 collector 的调用前缀压栈,再执行 function,使其返回值直接成为 collector 的唯一实参。
|
||||
let count = arguments.len();
|
||||
let mut constants = vec![Value::Object(collector), Value::Object(function)];
|
||||
constants.extend(arguments);
|
||||
@@ -90,6 +99,7 @@ pub fn collect_and_continue(
|
||||
for index in 0..count {
|
||||
instructions.push(Instruction::new(Opcode::LoadConst, index as u32 + 2));
|
||||
}
|
||||
// 收集器返回值不参与外层调度;丢弃后返回 true,通知重复驱动继续取下一项。
|
||||
instructions.extend([
|
||||
Instruction::new(Opcode::Call, count as u32),
|
||||
Instruction::new(Opcode::Call, 1),
|
||||
@@ -121,8 +131,12 @@ fn driver(
|
||||
/// false falls through. Operand widths include EXTENDED_ARG code units.
|
||||
/// 构造由继续条件决定是否再执行一轮的同帧循环。
|
||||
pub fn repeat_while(instructions: &mut Vec<Instruction>) -> Result<(), VmError> {
|
||||
// 跳转单位是编码后的双字节 code unit,不是 Instruction 数量。
|
||||
// 大操作数会生成 EXTENDED_ARG,因此必须编码后计算实际长度。
|
||||
let body = Instruction::encode_all(instructions)?.len() / 2;
|
||||
let mut back = Instruction::new(Opcode::JumpBackward, 0);
|
||||
// 回跳距离包含自身宽度;而距离变大又可能扩大自身编码宽度。
|
||||
// 迭代到宽度/距离一致后,false 跳过回跳指令,true 回到整个驱动的起点。
|
||||
loop {
|
||||
let units = Instruction::encode_all(&[back])?.len() / 2;
|
||||
let distance = u32::try_from(body + 1 + units)
|
||||
@@ -142,6 +156,8 @@ mod tests {
|
||||
use endor_core::{ExecutionLimits, Vm};
|
||||
#[test]
|
||||
fn repeated_bytecode_handles_extended_operands_and_keeps_one_frame() {
|
||||
// 300 个 Nop 强制跨越单字节跳转距离:false 应正常退出;true 应耗尽指令预算,
|
||||
// 而非耗尽帧预算,从而验证循环确实复用同一个执行帧。
|
||||
for condition in [false, true] {
|
||||
let mut instructions = vec![Instruction::simple(Opcode::Nop); 300];
|
||||
instructions.push(Instruction::new(Opcode::LoadConst, 0));
|
||||
@@ -177,6 +193,7 @@ mod tests {
|
||||
}
|
||||
vm.release(code).unwrap();
|
||||
vm.release(globals).unwrap();
|
||||
// 释放代码与全局字典后执行循环回收,确认生成的常量/函数没有遗留托管对象。
|
||||
vm.collect_cycles();
|
||||
assert_eq!(vm.object_count(), 0);
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user