设计审查: WAL 内部缓冲模型 — 私有 encode buffer vs 共享 buffered writer #19

New Issue

2026-06-12T08:28:34+08:00

dailz commented

2026-06-12 08:28:34 +08:00

来源: docs/design.md §3.2 WAL Oracle 架构审查

问题描述

步骤 ⑥ 要求"只做内存内编码，不得触碰 WAL 文件或任何可能被 recovery 看到的 WAL 缓冲区"。步骤 ⑦ 的 WAL write 失败判断标准取决于"zero bytes reached WAL state"。

这涉及实现层面的缓冲模型选择，直接影响 ErrCommitUnknown 的判断：

两种模型

模型 A: 私有 encode buffer + write()

batch → private []byte → write(fd, batchBytes)

write() 调用前：零 WAL 副作用，失败 = 普通错误
write() 调用后：可能有 WAL 副作用，失败 = ErrCommitUnknown
"zero bytes reached WAL state" 可证明：未调用 write()

模型 B: 共享 buffered writer

batch → shared bufio.Writer → flush() → write(fd)

bufio.Write() 进入共享缓冲区时，该缓冲区可能被其他 batch 共享
缓冲区 flush 前已经积累了多个 batch 的数据
单个 batch 无法证明 "zero bytes reached WAL state"
失败判断更保守

需要明确

推荐使用哪种缓冲模型？
如果使用 bufio.Writer，是否需要 per-batch 的 WAL 副作用边界标记？
是否需要显式记录实现约束："WAL write 路径不得使用共享缓冲，每个 batch 独立调用 write()"？

建议

推荐模型 A（私有 buffer + 直接 write），因为：

ErrCommitUnknown 判断边界清晰
不需要额外的缓冲区状态管理
性能损失可忽略（WAL write 本身就是 batch 粒度，不需要额外缓冲）

来源: docs/design.md §3.2 WAL Oracle 架构审查 ## 问题描述步骤 ⑥ 要求"只做内存内编码，不得触碰 WAL 文件或任何可能被 recovery 看到的 WAL 缓冲区"。步骤 ⑦ 的 WAL write 失败判断标准取决于"zero bytes reached WAL state"。这涉及实现层面的缓冲模型选择，直接影响 `ErrCommitUnknown` 的判断： ## 两种模型 **模型 A: 私有 encode buffer + write()** ``` batch → private []byte → write(fd, batchBytes) ``` - `write()` 调用前：零 WAL 副作用，失败 = 普通错误 - `write()` 调用后：可能有 WAL 副作用，失败 = `ErrCommitUnknown` - "zero bytes reached WAL state" 可证明：未调用 `write()` **模型 B: 共享 buffered writer** ``` batch → shared bufio.Writer → flush() → write(fd) ``` - `bufio.Write()` 进入共享缓冲区时，该缓冲区可能被其他 batch 共享 - 缓冲区 flush 前已经积累了多个 batch 的数据 - 单个 batch 无法证明 "zero bytes reached WAL state" - 失败判断更保守 ## 需要明确 1. 推荐使用哪种缓冲模型？ 2. 如果使用 `bufio.Writer`，是否需要 per-batch 的 WAL 副作用边界标记？ 3. 是否需要显式记录实现约束："WAL write 路径不得使用共享缓冲，每个 batch 独立调用 `write()`"？ ## 建议推荐模型 A（私有 buffer + 直接 write），因为： - `ErrCommitUnknown` 判断边界清晰 - 不需要额外的缓冲区状态管理 - 性能损失可忽略（WAL write 本身就是 batch 粒度，不需要额外缓冲）

dailz added the design-review question WAL labels 2026-06-12 08:28:34 +08:00

dailz closed this issue

2026-06-12 09:35:51 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: dailz/go-kv#19