Log 使用指南——WAL 页帧流 / 组提交 / 单写者
给谁看:用 Log 作 WAL / checkpoint delta 的组件开发者 回答什么:EntryLog vs DeltaLog 怎么选 / Settings 全参数 / 组提交策略 / 单写者硬约束 / 恢复 本篇只讲机制——帧字节布局见源码;性能数字见
perf/log-perf-baseline.md定位:Structures/ 6 子族之一,主结构(操作流),与 Ring 并列 2 主结构
0. 一句话总纲
Log = 单写者页帧流 + 组提交三维策略 + 恢复水位 + 不跨页 entry
Append返回 entry 起始LogicalAddress;单条 entry 含 header+payload+padding 超PageSize抛InvalidOperationException。- 批量
BeginAppendBatch()走双页 ping-pong 让渡轨——页满不阻塞写线程,唯一等待点 = 双页都在途的背压。 - 提交 =
CommitAsync(推进CommittedOffset+ meta.Commit + fsync);Flush只落盘不推进水位。 - 恢复三级回退:
LogRecoveryHints→ meta 持久化水位 → 扫盘验帧。 - 多生产者必须经队列汇聚到唯一写线程——
_writeLock是并发安全网,不是并发许可。
1. 定位
- 主结构:Log 与 Ring 并列为主结构——Ring = 数据真相源(record 流),Log = 操作流(WAL/redo 流)。
- 两种形态:
- EntryLog:通用 per-entry 顺序日志,WAL 是其典型用途。CRC64 in-header,22B 头。Meta 默认
Disabled,组提交三维策略默认启用。 - DeltaLog:KV 增量 checkpoint delta 流,绑定 DeltaLogCodec(不可替换)。CRC32C in-header,18B 头。Meta 默认
Transport(嵌入式 meta entry 写入 log 流——临时 delta 文件场景)。
- EntryLog:通用 per-entry 顺序日志,WAL 是其典型用途。CRC64 in-header,22B 头。Meta 默认
- 与 Metadata 关系:DeltaLog 与
versioned-metadata.md配合承载 checkpoint delta + 跨重启水位。 - 与 StorageEngine 关系:Log 接入
IStorageEngine(逻辑地址 = 物理地址),IO 底层 = 持久化的内存——Log 不碰段/对齐/落盘细节,只在引擎地址空间上做 record 格式(codec)+ group commit 调度。引擎使用见storage-engine.md。
1.1 EntryLog vs DeltaLog 形态对比
| 维度 | EntryLog | DeltaLog |
|---|---|---|
| 用途 | 通用 per-entry 顺序日志(WAL 典型) | KV 增量 checkpoint delta 流 |
| Codec | EntryLog.Codec(CRC64 in-header,22B 头,4B 对齐) |
DeltaLog.Codec(CRC32C in-header,18B 头,4B 对齐)——绑定不可替换 |
MaxEntrySize |
4MB(1 << 22) |
4MB(1 << 22) |
| Meta 缺省 | Disabled |
Transport(嵌入式 meta entry 写入 log 流——临时 delta 文件场景) |
| 组提交策略 | 默认启用(GroupCommitPolicy 三维度,构造 commitPolicy=null 时启用) |
不启用专属策略(无 ICommitPolicy 注入参数) |
CommittedOffset |
暴露(commit 边界水位) | 不暴露(基类无此字段) |
| 提前提交循环 | 启动(StartEarlyCommitLoop——CommitInterval ≠ -1ms 时) |
不启动 |
| 恢复钩子 | OnLogRecovered override 设 CommittedOffset = TailAddress + 启提前提交循环 |
默认空(无依赖恢复结果的装配) |
| 构造注入 | commitPolicy / cursorFactory / metaPolicyFactory / metaTransport / clock |
cursorFactory / metaPolicyFactory / metaTransport(无 commitPolicy / clock) |
选型判据:需要 WAL 持久性调度(raft log / redo log)→ EntryLog;承载 checkpoint delta(与 VersionedMetadata 配合)→ DeltaLog。
3. 构造与生命周期
3.1 生命周期(全部结构统一)
- 三步装配:构造 →
Initialize(hints)→WaitForReady(Log 族无工厂;封闭结构才有CreateAsync一步就绪);异步调用方用WaitForReadyAsync。 Initialize启动双引擎并行启动(主引擎 + Managed meta 引擎,均非阻塞)。Dispose幂等——观察在途让渡刷盘(含补跑延迟提交链)、刷末页、释放双页缓冲与 frame 池,最后走基类编排。
3.2 单写者硬性约束
_writeLock 是并发安全网,不是并发许可——保证并发调用不损坏状态(水位/TailAddress 零改动),不改变单写者语义。多生产者必须经队列汇聚到唯一写线程。批协议背压慢路的 Monitor.Exit 窗口内禁止其他写者插队 Begin——批协议消费形态 = 单写者(raft 适配器 = wal 唯一追加方)。
3.3 代码示例
① 装配(三步就绪)
using var fs = TierFs.New("memory:");
var settings = new EntryLogSettings("raft.wal")
{
LogPageSizeBits = 20, // 1MB 页
CommitInterval = TimeSpan.FromMilliseconds(10),
MaxUnflushedBytes = 64 * 1024,
MaxUnflushedCount = 1000,
MetaPolicyKind = MetaPolicyKind.Managed,
MetaOpaqueBytes = 64,
};
// 构造 + Initialize + WaitForReady(恢复三级回退在此完成);异步调用方用 await log.WaitForReadyAsync(ct)
using var log = new EntryLog(fs, settings);
log.Initialize();
log.WaitForReady();
② Append + CommitAsync
// 单写者:多生产者必须经队列汇聚到唯一写线程
LogicalAddress addr = log.Append(stackalloc byte[128]); // 返回 entry 起始地址
// 默认 GroupCommitPolicy 三维度兜底;末页未 commit 数据崩溃后丢失(WAL 语义)
// 显式提交(如 raft Apply 前需确认持久化):
await log.CommitAsync(ct);
// 等待特定 entry 已 commit:
await log.WaitForCommitAsync(addr, ct);
// 提交错误查询(后台循环错误不冒泡到调用方):
Exception? lastErr = log.LastCommitError;
③ Replay(恢复 / 重放已 commit)
// 只重放 ≤ CommittedOffset 的 entry(WAL 一致性语义)
// verifyCrc=false(默认):仅验 Magic,约快 10-50×;true = 每条全量验 CRC(完整性审计)
long count = log.Replay(LogicalAddress.Empty, static (payload, isMeta, addr) =>
{
if (isMeta) return; // 跳过嵌入式 meta entry
ApplyEntry(payload, addr); // 零拷贝 Span——禁止跨回调持有
}, verifyCrc: false);
④ 批量追加(高吞吐——页满让渡不阻塞)
// 批(ref struct)绝不跨 await 持有(持写锁);using 包裹保证 Dispose 释放锁
using var batch = log.BeginAppendBatch();
foreach (var entry in entries)
{
// 页满让渡轨——当前页交异步刷盘、立即切另一页继续写
// 唯一等待点 = 双页都在途的背压(罕见 = 页边界 × 双页在途)
LogicalAddress addr = batch.Append(entry);
}
// Dispose 回写宿主 _pageUsed + 释放写锁——批内未 commit,靠默认 GroupCommitPolicy 或显式 CommitAsync
⑤ 2PC 事务(跨结构原子提交)
// 协调器 = Transactions/TransactionLog(写独立 commit record 文件驱动 Prepare/Confirm/Abort)
// Log 是参与者之一,与 Ring / Index 等共同 Prepare → ConfirmCommitted / Abort
log.OnCommitted(seq, () => ApplyNotify(seq)); // 注册 seq 提交回调(已提交到更高 seq → 立即同步触发)
log.Prepare(seq); // FlushUntil(tail) + AppendMeta(tail)——进入悬干状态
// ... 其他参与者 Prepare ...
// 协调器写 commit record → 各参与者 ConfirmCommitted(seq)
log.ConfirmCommitted(seq); // 推进 LastCommittedSeq + _txRollbackTail
// 失败路径:
log.Abort(seq); // TruncateSuffix 回退到 _txRollbackTail,丢弃本轮悬干数据
8. 反模式(组合层必守)
| # | 反模式 | 后果 | 正解 |
|---|---|---|---|
| 1 | Log 并发 Append | 单写者硬约束破坏——水位/TailAddress 错乱 | 多生产者经队列汇聚到唯一写线程(_writeLock 是安全网,非并发许可) |
| 2 | 批(ref struct)跨 await 持有 | 持写锁跨 await = 自锁死 / SynchronizationLockException | 批内 AppendAsync 背压慢路 await 在宿主侧(孤儿认领协议),消费方续体线程不可预期 |
| 3 | 单 entry 超 PageSize | 抛 InvalidOperationException |
大对象调用方拆分成多条 entry(单 entry 不跨页契约) |
| 4 | 跨 MoveNext 持有 CurrentPayload Span(非 lease 模式) | 换页即还池——span 指向已归还的池缓冲 | 用 lease 模式(leasePages=true,CurrentPayloadMemory 有效至 Dispose)或拷贝交付 |
| 5 | 不查询 LastCommitError | 后台循环提交错误不冒泡到调用方——持久化失败静默 | 上层周期查询 LastCommitError 发现持久化失败 |
| 6 | MetaPolicyKind=Disabled 时 SetOpaqueMeta | 抛 InvalidOperationException(禁用即报错,不静默吞) |
配 Managed / Transport,或移除 opaque 写入 |
| 7 | 绕过组提交策略手动 CommitAsync | 末页未 commit 数据崩溃后丢失(符合 WAL 语义,但可能误以为已持久化) | 显式 CommitAsync 用于 raft Apply 前确认;常规写入信任默认 GroupCommitPolicy |
| 8 | 跨结构组合 DeleteOnClose=true | 跨重启组合必须 false(否则索引重建时真相源被清) | 跨重启组合 DeleteOnClose=false(同 structures.md §5) |
| 9 | 截断后期望 CommittedOffset 自动夹回 | EntryLog 已 override OnTailTruncated / OnAborted 夹回——子类不自管会违反 §7 不变量 |
信任基类夹回逻辑;自定义 LogBase 子类须 override 夹自管水位 |
| 10 | opaque 期望独立提交路径 | 旧 WriteOpaqueMeta 自拍 TailAddress 独立成块 = 并发水位回退 + 被内部提交冲掉,已废除 | opaque 跟随水位线提交链(SetOpaqueMeta stage → 下次 CommitAsync 原子落盘) |
9. 想深入?指路
| 想懂什么 | 去哪 |
|---|---|
| 总览(七种结构怎么选怎么组合) | structures.md |
| 引擎使用(读写/水位/恢复/Compact) | storage-engine.md |
| meta 统一协议(opaque 搭车/块格式/自定义传输) | meta.md |
| Session 协调协议(写/读/检查点三 op、悬挂裁决、故障模型) | session.md |
| 段表 / lease 协议(raft 共识层) | segment-table.md / lease-protocol.md |
| 同族结构 | ring.md / index.md / versioned-metadata.md / mirror.md / snapshot.md |
| 性能基线(Append 吞吐 / 重放速率 / 组提交延迟) | perf/log-perf-baseline.md |
| 帧/头的精确字节布局(互操作解析手册——页帧/entry 头/meta 块/水位全表) | binary-format-spec.md |
| 帧字节布局 / 双页让渡轨状态机 / 2PC 内部状态机 | 源码注释(Structures/Log/ 各 partial)与内部设计稿(不随包发布) |
机制级细节(8 水位全表、帧字节布局、dump 协议、2PC 内部状态机)按需从源码与设计稿查阅——使用面不需要这些细节;能力全集以类型 XML 注释为准。
分册导航:log.md | [log-api.md](API 与工厂) | log-persistence.md | Log——Settings / API 详表 / 注入工厂 | Log——持久化机制与恢复协议