# Regolith 性能基准

基准套件在 [src/bench_test.mbt](../src/bench_test.mbt)，用 `moon bench` 运行
（`moon test` 会跳过注入式基准测试）。所有基准跑在内存数据库上，测的是引擎
本身（memtable 跳表、WAL 编码、SSTable 索引/bloom、归并迭代器），不含磁盘
IO。工作负载确定：定宽键 `k00000`…（字典序 = 数值序），值 64 字节。

## 怎么读输出

```
time (mean ± σ)         range (min … max)  in N × M runs
   6.22 µs ± 611.85 ns     5.45 µs …   7.53 µs  in 10 ×  15844 runs
```

- `mean`：单次迭代的耗时（对 `bench put` 是一次 put；对 `bench scan` 是一次
  2000 键全扫；对 `WriteBatch` 是一次 500 键批量提交）
- `N × M runs`：N = 采样轮数，M = 每轮执行的迭代次数
- 吞吐换算：`1 / mean`（scan/compact 类再乘以单次迭代处理的条目数）

## 实测数字（2026-10-29）

**native 后端（CI ubuntu，`moon bench --target native`，日志为记录）**：

| 基准 | 单次迭代 | mean | 换算吞吐 |
|---|---|---|---|
| put into memtable（2000 × 64B 循环覆盖） | 1 次 put | 784 ns | ~1.28M puts/s |
| get from memtable（2000 键） | 1 次 get | 370 ns | ~2.70M gets/s |
| get from L0 sstable（2000 键） | 1 次 get | 2.60 µs | ~385k gets/s |
| get from L2 sstable（2000 键） | 1 次 get | 2.68 µs | ~373k gets/s |
| scan 2000 entries（memtable + L0 双流归并） | 1 次全扫 | 308 µs | ~6.5M entries/s |
| WriteBatch 500 puts | 1 批 500 键 | 369 µs | ~0.74 µs/put（~1.36M puts/s） |
| compact L1 merge（2000 键重写） | 1 次归并 | 1.14 ms | ~1.75M entries/s |

**js 后端（node，本机参考）**：

| 基准 | 单次迭代 | mean | 换算吞吐 |
|---|---|---|---|
| put into memtable（2000 × 64B 循环覆盖） | 1 次 put | 6.22 µs | ~161k puts/s |
| get from memtable（2000 键） | 1 次 get | 1.23 µs | ~813k gets/s |
| get from L0 sstable（2000 键） | 1 次 get | 15.2 µs | ~66k gets/s |
| get from L2 sstable（2000 键） | 1 次 get | 15.1 µs | ~66k gets/s |
| scan 2000 entries（memtable + L0 双流归并） | 1 次全扫 | 1.37 ms | ~1.46M entries/s |
| WriteBatch 500 puts | 1 批 500 键 | 2.17 ms | ~4.3 µs/put（~230k puts/s） |
| compact L1 merge（2000 键重写） | 1 次归并 | 9.14 ms | ~219k entries/s |

## 实测数字（2026-10-31，v3 键压缩格式）

**js 后端（node，本机参考）**：

| 基准 | 单次迭代 | mean | 换算吞吐 |
|---|---|---|---|
| put into memtable（2000 × 64B 循环覆盖） | 1 次 put | 6.22 µs | ~161k puts/s |
| get from memtable（2000 键） | 1 次 get | 1.25 µs | ~800k gets/s |
| get from L0 sstable（2000 定宽键，v3） | 1 次 get | 9.01 µs | ~111k gets/s |
| get from L0 sstable v3（2000 长共享前缀键） | 1 次 get | 12.44 µs | ~80k gets/s |
| get from L2 sstable（2000 键） | 1 次 get | 9.05 µs | ~110k gets/s |
| scan 2000 entries（memtable + L0 双流归并） | 1 次全扫 | 1.75 ms | ~1.14M entries/s |
| WriteBatch 500 puts | 1 批 500 键 | 2.31 ms | ~4.6 µs/put（~216k puts/s） |
| compact L1 merge（2000 键重写） | 1 次归并 | 9.09 ms | ~220k entries/s |

### v3 表体积实测（2000 键 × 64B 值，SstBuilder 实测字节数）

| 键形 | v3 实测 | v2 布局估算 | 变化 |
|---|---|---|---|
| 定宽 `k00000`（6 字节，浅共享） | 146,325 | 152,739 | **−4.2%** |
| 40 字节共享前缀 + 6 字节后缀 | 153,540 | 235,248 | **−34.7%** |
| 随机 16 字节二进制键（无共享） | 175,920 | 173,204 | +1.6% |

v2 估算公式：`Σ(1 + 1 + seq_varint_len + 1 + 键长 + 64)` + 块头 count +
索引段 + bloom（2500 字节）+ footer 30 字节——与 v3 实测同构到逐 varint。
随机键的 +1.6% 来自设计稿已声明的两项开销：每键多一个 `shared` varint
（最坏 ≈1 字节/键）与 restarts 段（重启点 × 4 字节平摊 ≈0.25 字节/键）。
前缀键的 −34.7% 落在设计稿预计的 30–60% 区间内。

## 怎么解读

- **读分三级，代价递增**：memtable 跳表命中 370ns；SSTable 命中（L0/L2 同为
  ~2.6µs）走的是 bloom 过滤 + 块索引二分 + 块内解析，层级不改变代价（每层
  只有一张表时）。
- **v3 块内二分换长键解码**：长共享前缀键的 get（12.44µs）比定宽键
  （9.01µs）慢约 3.4µs——每键多解码 40 字节，但重启点二分保证块内扫描
  ≤ `restart_interval`（16）条，不会随块条目数线性退化。这是体积 −34.7%
  换来的读代价，仍然有界。
- **批写摊薄固定开销**：500 键一次 WriteBatch 的每键成本 0.74µs < 单键 put
  784ns——WAL 单条批记录 + 连续 seq 段，比逐键写省掉组提交与记录头开销。
  这正是申报书 §4 场景一「多键用一次批量写原子提交」的量化理由。
- **压缩吞吐与扫描同量级**：compact 重写 2000 键 1.14ms（~1.75M 键/s）与
  扫描（~6.5M 键/s）的差异来自读改写三份数据 + 写新表，符合 LSM 写放大模型。
- **后端间只有常数倍差异**：js 后端每个操作慢 8-20 倍，但所有路径的相对
  关系一致（批写 < 逐键写、memtable 读 ≪ SST 读）——引擎行为跨后端可预期，
  与「确定性」承诺一致。

## 基准的工程含义

这套基准覆盖全部热路径（写路径、三级读路径、扫描、批写、压缩），并作为
CI 的 native 任务随每次 push 回归——性能测试和正确性测试同一地位。数字证明
引擎在 2000 键规模上没有病态路径：native 上最贵的读（SSTable 点查）2.6µs，
最贵的写路径（逐键 put）784ns，批写路径更快。