ITStudio_OUC/OxideJS
Archived
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 补充注释与格式化

Browse Source
This commit is contained in:
爱特每羊队
2026-08-06 23:10:27 +08:00
parent 4e0fd762c2
commit 328b8a3ddc
156 changed files with 2393 additions and 1687 deletions
Download Patch File Download Diff File Expand all files Collapse all files
crates/oxide_vm/src/dispatch/call.rs
+16 -16
View File
@@ -33,14 +33,14 @@ impl Vm {
let args_slice = &args_buf[..len];
builtins_debug!("native_call depth={} args={}", self.native_call_depth, arg_count);
// SAFETY: native_fn was set via set_native_fn with a valid NativeFn pointer;
// native_fn_ptr_to_fn is the single coercion point for NativeFnPtr → NativeFn.
// SAFETY: native_fn 经 set_native_fn 以合法 NativeFn 指针设置；
// native_fn_ptr_to_fn 是 NativeFnPtr → NativeFn 的唯一强制转换点。
let func: NativeFn = unsafe { native_fn_ptr_to_fn(obj.native_fn().unwrap()) };
// regs[254] is the caller's `this` register and doubles as the "current callee"
// slot that dispatcher builtins (Function.prototype.bind/call/apply) read. Native
// calls share the flat register file with the caller, so snapshot the caller's
// `this`, expose the callee for the native's duration, then restore it — otherwise
// every native call leaves its own function object in the caller's `this` register.
// regs[254] 是调用方的 `this` 寄存器，同时充当分发型 builtin
// （Function.prototype.bind/call/apply）读取的"当前 callee"槽。native 调用与
// 调用方共享扁平寄存器文件，因此先快照调用方 `this`，在 native 执行期间暴露
// callee，随后恢复——否则每次 native 调用都会把自己的函数对象留在调用方的
// `this` 寄存器里。
let saved_this = self.regs[254];
self.regs[254] = callee;
self.native_call_depth += 1;
@@ -58,7 +58,7 @@ impl Vm {
(err_val, self.thrown_error_kind(err_val))
} else {
let msg = if err_val.is_string() {
// SAFETY: err_val is a string value.
// SAFETY: err_val 是字符串值。
unsafe { (*err_val.as_string_ptr()).data.clone() }
} else {
format!("{err_val}")
@@ -184,8 +184,8 @@ impl Vm {
}
}
}
// Cell not yet created (hoisting order: CREATE_CLOSURE before MAKE_CELL).
// Create cell lazily with caller's register value.
// cell 尚未创建（hoisting 顺序：CREATE_CLOSURE 先于 MAKE_CELL），
// 用调用方寄存器值惰性创建 cell。
self.lazy_create_upvalue_cell(rd, uv_idx)
}
@@ -195,7 +195,7 @@ impl Vm {
let obj = unsafe { &mut *callee.as_js_object_ptr() };
let upvals = obj.upvalues_slice_mut();
if uv_idx < upvals.len() {
// Try to get value from caller's cell table (MAKE_CELL ran after CREATE_CLOSURE)
// 尝试从调用方 cell 表取初值（MAKE_CELL 在 CREATE_CLOSURE 之后执行）。
let val = if self.cell_stack.len() >= 2 {
let caller_cells = &self.cell_stack[self.cell_stack.len() - 2];
if uv_idx < caller_cells.len() && !caller_cells[uv_idx].is_null() {
@@ -317,10 +317,10 @@ impl Vm {
if super_obj.native_fn().is_some() {
self.regs[253] = derived_this;
self.regs[254] = super_ctor; // bind_dispatcher reads regs[254] as the wrapper callee
self.regs[254] = super_ctor; // bind_dispatcher 把 regs[254] 当作包装 callee 读取
let (args_buf, len) = Self::build_native_args(first_arg_reg, arg_count, 253);
// SAFETY: native_fn was set via set_native_fn with a valid NativeFn pointer;
// native_fn_ptr_to_fn is the single coercion point for NativeFnPtr → NativeFn.
// SAFETY: native_fn 经 set_native_fn 以合法 NativeFn 指针设置；
// native_fn_ptr_to_fn 是 NativeFnPtr → NativeFn 的唯一强制转换点。
let func: NativeFn = unsafe { native_fn_ptr_to_fn(super_obj.native_fn().unwrap()) };
match func(self, &args_buf[..len]) {
NativeResult::Ok(val) => {
@@ -336,8 +336,8 @@ impl Vm {
}
}
NativeResult::TailCall { callee, this, args } => {
// e.g. bound function: resolve the tail call, use its return
// value as the constructed instance (or fall back to derived_this).
// 如 bound 函数：解析尾调用，用其返回值作为构造实例
// （或回退到 derived_this）。
match self.call_function_sync(callee, this, &args) {
Ok(val) => {
self.regs[254] = if val.is_object() { val } else { derived_this };
crates/oxide_vm/src/dispatch/exception.rs
+1 -1
View File
@@ -1 +1 @@
// dispatch helper functions extracted from vm.rs
//! 异常处理相关 dispatch 辅助函数（占位，逻辑位于 vm_dispatch_ctrl / vm_dispatch_misc）。
crates/oxide_vm/src/dispatch/for_in.rs
+1 -1
View File
@@ -1 +1 @@
// dispatch helper functions extracted from vm.rs
//! for-in 相关 dispatch 辅助函数（占位，逻辑位于 vm_dispatch_misc）。
crates/oxide_vm/src/dispatch/misc.rs
+13 -4
View File
@@ -65,7 +65,7 @@ impl Vm {
pub(crate) fn dispatch_store_var(&mut self, rd: usize, a: usize, b: usize) -> Result<bool, String> {
vm_trace!("STORE_VAR r{}={:?} const={}", rd, self.regs[a], b);
if b != 0 {
// const guard: check if already initialized
// const guard：检查目标槽是否已初始化。
if !self.regs[rd].is_undefined() {
self.raise_error_kind("TypeError", "Assignment to constant variable")?;
return Ok(true);
@@ -75,8 +75,13 @@ impl Vm {
Ok(false)
}
/// SPILL：regs[rd] → spill_stack[帧基址 + slot]。ext 字 = slot u16（D-06）。
/// 帧基址 = 当前 CallFrame.spill_offset（顶层模块无帧 = 0，D-08）。
/// SPILL：`regs[rd]` → `spill_stack[帧基址 + slot]`。
///
/// ext 字为 slot（u16）；帧基址 = 当前 CallFrame.spill_offset（顶层模块无帧为 0）。
/// # 边界与前提
/// - slot 超 u16 范围返回错误（RegAlloc 保证发射在界内）。
/// # 副作用
/// - 写 spill 栈，可能触发 resize 扩容。
#[inline(always)]
pub(crate) fn dispatch_spill(&mut self, rd: usize) -> Result<(), String> {
let slot = self.bytecode[self.pc] as usize;
@@ -94,7 +99,11 @@ impl Vm {
Ok(())
}
/// UNSPILL：spill_stack[帧基址 + slot] → regs[rd]。越界读 undefined（防御，D-06 slot 由 RegAlloc 保证在界内）。
/// UNSPILL：`spill_stack[帧基址 + slot]` → `regs[rd]`。
///
/// # 边界与前提
/// - slot 超 u16 范围返回错误。
/// - 越界读返回 undefined（防御：slot 由 RegAlloc 保证在界内）。
#[inline(always)]
pub(crate) fn dispatch_unspill(&mut self, rd: usize) -> Result<(), String> {
let slot = self.bytecode[self.pc] as usize;
crates/oxide_vm/src/dispatch/property.rs
+3 -3
View File
@@ -46,7 +46,7 @@ impl Vm {
if val.is_string() {
let length_si = self.kernel_core.perm_interner().intern("length").0;
if prop_name_si == length_si {
// SAFETY: val is a string value.
// SAFETY: val 是字符串值。
let len = unsafe { (*val.as_string_ptr()).data.encode_utf16().count() };
return Ok(Some(JsValue::int(len as i32)));
}
@@ -207,14 +207,14 @@ impl Vm {
prop_cache_miss();
ic_debug!("IC_GET miss shape={} prop={}", obj.shape_id(), prop_name_si);
let resolved = self.ordinary_get(obj, prop_name_si, val)?;
// Try own property first (fast path, depth=0).
// 先试自身属性（快路径，depth=0）。
if let Some(pos) = self.kernel_core.shape_forge().lookup_position(obj.shape_id(), prop_name_si) {
if !obj.is_accessor_meta(pos) {
ic_helper::write_ic_back(&mut self.bytecode, self.pc, obj.shape_id(), pos, 0);
ic_debug!("IC_GET write-back own shape={} slot={}", obj.shape_id(), pos);
}
} else {
// Walk proto chain to find which object actually owns this property.
// 沿原型链查找真正拥有该属性的对象。
let mut cursor = obj.proto().as_js_object_ptr();
let mut depth = 1u8;
while !cursor.is_null() {