Table of Contents

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 文件场景)。
  • 与 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——持久化机制与恢复协议