feat: 新增采样器按指令周期记录样本并输出热点直方图

crates/oxide_cli/src/bench/js_stress.rs

@@ -86,6 +86,11 @@ pub fn run_js_stress_bench(config: &BenchConfig, kernel: &Arc<KernelCore>, pool:
             let mut guard = pool.spawn();
             let vm = guard.vm_mut();
 
+            // 指令周期采样只对测量迭代开启：预热不采样，直方图不混入
+            // 预热样本，stderr 输出也不随预热迭代重复。
+            vm.set_sample_period(config.sample_period);
+            vm.set_sample_top_k(config.sample_top);
+
             let pre_session = vm.session_object_count();
             let pre_epoch = vm.epoch_object_count();
 

crates/oxide_cli/src/bench/mod.rs

@@ -32,6 +32,11 @@ pub struct BenchConfig {
     pub iterations: u32,
     pub update_baseline: bool,
     pub leak_check_interval: usize,
+    /// 指令周期采样周期（2 的幂，0 关闭）：开启时测量迭代每 period 条指令
+    /// 记一条样本，run 末按 flat_id 输出 top-K 直方图。
+    pub sample_period: u64,
+    /// 采样直方图 top-K 大小（默认 10）。
+    pub sample_top: usize,
 }
 
 /// 按 mode 分派到具体 benchmark 实现（js/rust/leak）。

crates/oxide_cli/src/main.rs

@@ -87,6 +87,13 @@ enum Commands {
         update_baseline: bool,
         #[arg(long, default_value = "1000")]
         leak_check_interval: usize,
+        /// 指令周期采样周期（2 的幂，0 关闭，默认关闭）。开启时测量迭代每
+        /// period 条指令记一条样本，run 末按 flat_id 输出 top-K 直方图。
+        #[arg(long, default_value = "0")]
+        sample: u64,
+        /// 采样直方图 top-K 大小（默认 10）。
+        #[arg(long, default_value = "10")]
+        sample_top: usize,
     },
     Test {
         suite: Option<String>,
@@ -130,9 +137,17 @@ fn main() -> ExitCode {
             iterations,
             update_baseline,
             leak_check_interval,
+            sample,
+            sample_top,
         }) => {
             let kernel = make_kernel(false, false);
             let pool = make_pool(&kernel);
+            // 采样周期边界检查：须为 0（关闭）或 2 的幂，否则指令边界的
+            // `steps & (period - 1) == 0` 判定退化（周期不整除步数序列）。
+            if sample != 0 && sample & (sample - 1) != 0 {
+                eprintln!("--sample period must be 0 (disabled) or a power of two, got {sample}");
+                return ExitCode::FAILURE;
+            }
             let config = bench::BenchConfig {
                 mode: mode.unwrap_or_else(|| "js".to_string()),
                 filter,
@@ -140,6 +155,8 @@ fn main() -> ExitCode {
                 iterations,
                 update_baseline,
                 leak_check_interval,
+                sample_period: sample,
+                sample_top,
             };
             bench::run_benchmarks(config, kernel, pool)
         }