Table of Contents

Log——持久化机制与恢复协议

分册导航:log.md | [log-api.md](API 与工厂) | log-persistence.md | Log——Settings / API 详表 / 注入工厂 | Log——持久化机制与恢复协议

6. 持久化机制

6.1 页帧格式(LogPageFrameHeader)

[LogPageFrameHeader 8B][entry data 扇区对齐][Crc32Footer 4B][padding 撑到扇区对齐]
  • LogPageFrameHeader(8B):MagicValue("LPGF")+ DataLength(页内有效数据字节数,不含 header/footer)。源生成器自动生成 codec。
  • Crc32Footer(4B):CRC32C 覆盖 [header + data](不含 footer 自身与 padding)。
  • entry 布局:[EntryLogHeader 22B / DeltaLogHeader 18B][payload][padding 4B 对齐]——单 entry 不跨页(超 PageSize 抛)。

6.1.1 地址空间窗口模型(Allocate + CalculationAddress + Write)

Log 不用 engine.Append(pwrite 后才知地址——无法满足"entry 写入时即知地址"),改用三层结构:

层 操作 IO
地址空间窗口 engine.Allocate(SpaceAllocSize) → 大区间 CAS 推水位 零 IO
页(PageSize 攒批单位) engine.CalculationAddress(_spaceStart, _spaceWriteOffset) 精确推算 entry 地址 纯逻辑
entry 写入 engine.Write(addr, frame) 在已分配空间内覆写(lease 保护,DIO 对齐) 真正 IO
  • SpaceAllocSize = PageSize × 16(一个窗口放 16 页 frame,摊薄 Allocate(CAS) 开销)。
  • 窗口剩余放不下时 ReclaimTail 退回旧窗口未用空间 + Allocate 新窗口(窗口换代 _spaceGeneration++,在途写失败回滚只认同代——跨代回滚会覆写新窗口游标)。
  • DIO 三重对齐(IOMode.Enabled 下硬责任):fileOffset(Allocate 返回,段内扇区对齐)/ length(AlignUp 到扇区,padding 补零)/ buffer 地址(AlignedMemoryManager 扇区对齐分配)。

6.1.2 双页 ping-pong 让渡轨

路径 调用 语义
同步轨 FlushPage Append/Flush/CommitAsync 屏障路径 原地同步写——_inFlightFlush 等待后内联写新页
让渡轨 FlushPageYield 批协议页满 / 异步 AppendAsync 组帧 → 先行推进地址(frame 尺寸已知)→ 启动纯数据写任务 → 立即切另一页继续写(IO 重叠)
观察点 DrainInFlightSync/Async 下次让渡 / Flush / Dispose 等纯数据写完成 → 补跑延迟提交链(OnPageFlushed)

让渡轨状态机:Writing → Flushing[IO 在途] → 空闲;双页 ping-pong 不变。_inFlightFlush 是纯数据写任务——永不触碰 _writeLock、永不内联跑提交链(批持锁等待在途刷盘时内嵌提交链 = 自锁死)。提交链延迟到观察点(DrainInFlightSync/Async)在锁语义内补跑。

6.2 组提交策略(GroupCommitPolicy 三维度)

维度 字段 0 值语义 禁用值
字节量 MaxUnflushedBytes 字节维度立即满足(每次 Append 触发) long.MaxValue
时间 Interval 时间维度立即满足 -1ms(InfiniteTimeSpan)
记录数 MaxUnflushedCount 条数维度立即满足 int.MaxValue

判定:UnflushedBytes ≥ MaxUnflushedBytes || (Interval ≠ -1ms && SinceLastCommit ≥ Interval) || UnflushedCount ≥ MaxUnflushedCount——任一满足即触发。三个全 0 = 每次 Append 立即提前提交。

6.3 两层提交模型(职责分离)

层 触发 语义 可配置
底层页提交契约(恒成立) 跨页 Append / Flush / Dispose → FlushPage → OnPageFlushed 前一页换出时即持久化(数据 + meta + CommittedOffset 推进)。最坏情况:写满一页才提交。 否(不可关)
可选提前提交(注入式优化) ICommitPolicy 在页未满时提前触发 降延迟。注入 null = 仅依赖底层页契约;注入 GroupCommitPolicy = 三维度提前提交。 是

6.4 CommitAsync vs Flush

API 落盘(fsync) 推进 CommittedOffset meta.Commit 典型用途
Flush / FlushAsync ✓ ✗ ✗ 仅落盘,不推进水位(如读前确保可见)
CommitAsync ✓ ✓ ✓ 显式提交(raft Apply 前确认持久化)
OnPageFlushed(底层契约) ✓(已落盘) ✓ ✓ 页换出同步提交(恒成立)
后台提前提交循环 ✓(仅推进到 FlushedTail) ✓ ✓ 时间维度兜底(Interval 到期)

崩溃一致性顺序:data fsync 先于 meta fsync——CommitWithFlush = FlushUntil(engine.Write + engine.Flush 落盘 data)→ CommitCore(AppendMeta + meta.Commit 落盘 meta)。断电时 meta 绝不会标记一个 data 尚未落盘的 commit 点。

6.4.1 提交执行链(同步轨 / 异步轨)

阶段 同步轨 CommitWithFlush 异步轨 CommitWithFlushAsync
① 落盘 data FlushUntil(commitTarget) → engine.Flush FlushUntilAsync → engine.Flush
② 推进水位 CommitCore(commitTarget) → AppendMeta + meta.Commit CommitCoreAsync → AppendMetaAsync + meta.CommitAsync
③ 唤醒等待者 Monitor.PulseAll(_commitLock) 同

6.4.2 守卫矩阵(防自递归 / 防 Dispose 篡改)

守卫 触发条件 行为
_inCommit 重入守卫 CommitCore → AppendMeta 写 meta entry 触发页满 → FlushWindow → OnPageFlushed → CommitCore 重入时跳过 CommitCore——防无限递归栈溢出(meta entry 是提交记录本身,不需要再触发提交)。
IsDisposed 守卫 FlushOnDispose 期间的页 flush 不再触发 commit——Dispose 职责是把脏页冲到盘上(避免数据丢失),但不应隐式篡改 commit 边界(未 commit 的末页重启后按未 commit 处理,符合 WAL 语义)。
committedTail ≤ _committedOffset 守卫 末页重复 flush 不再 commit——避免末页重复 flush 时无谓 commit。

6.4.3 水位不变量

不变量 语义
CommittedOffset ≤ FlushedTail 已 commit 必已落盘——CommitWithFlush 先 FlushUntil 后 CommitCore,保证此序。
FlushedTail ≤ TailAddress 已落盘水位 ≤ 当前写游标(含内存页内未 flush 的 entry)——让渡轨先行推进 TailAddress 后两者脱钩。
BeginAddress ≤ CommittedOffset commit 边界不得越过头截断——TruncatePrefix 后不夹回(head 回收不影响 commit)。
截断后 CommittedOffset ≤ TailAddress TruncateSuffix / Abort 后 EntryLog override OnTailTruncated / OnAborted 夹回——否则 Replay 越界跳段报 Segment not found。

6.4.4 内置 ICommitPolicy 对照

策略 ShouldCommit 返回 用途
GroupCommitPolicy(默认——构造注入 null 即得) 三维度任一满足即 true WAL 典型场景(默认 10ms/64KB/1000)
自定义实现(恒 true) 恒 true 单条强制——每次 Append 立即提交(宜配 WriteThrough)
自定义实现(恒 false) 恒 false 手动 / 2PC——靠 CommitAsync / TransactionLog 驱动

6.5 meta 持久化三策略

MetaPolicyKind meta 引擎 典型用途
Disabled 无 不持久化水位——SetOpaqueMeta 抛 InvalidOperationException,ReadOpaqueMeta 恒空。
Managed 独立 meta 引擎(同构 Create) 跨重启单值状态 + opaque 搭车水位线原子落盘。
Transport 嵌入式 meta entry 写入 log 流(MetaHost),或注入 IMetaTransport 外部传输 DeltaLog 临时 delta 文件场景(缺省)。

opaque 登记:SetOpaqueMeta(bytes) stage 进策略缓冲,随下次水位提交原子落盘(同一块、同一 CRC)。无独立 opaque 提交路径。需确定性持久化点调 CommitAsync(一块 = 当前水位 + opaque)。


7. 恢复协议

7.1 三级回退(与 Metadata/Mirror/Snapshot 统一)

优先级 来源 适用
① LogRecoveryHints 外部主动注入(最高优先级) 上层快照场景注入 TailAddress;DeltaLog 临时文件场景注入 FileSize(近似水位)。
② meta 持久化水位 MetaPolicy.LoadAsync 读最后一块 meta LogMetaPayload.TailAddress > Empty 时启用。同时还原 LastCommittedSeq / LastPreparedSeq / PreparedTailAddress(2PC 悬干裁决依据)。
③ 扫盘 从 engine.MinAddress 前向走帧到最后一个有效帧尾 兜底——逐帧验证 magic + dataLen + footer CRC,撕裂/坏帧止步于前一有效帧。

恢复后 ReconcileEngineTail:退到 Log 真实尾 + 帧边界 padded end 对齐(meta/hints 记录的尾是末帧数据尾,padding 之后才能续写首个新 frame,否则 cursor 读完末帧 CRC 跳过 padding 后找不到新帧 header)。EntryLog 的 EntryLogRecovery.OnLogRecovered 在恢复后设 CommittedOffset = TailAddress(恢复后天然一致)+ 启动提前提交循环。

7.2 LogRecoveryHints 字段

字段 类型 说明
TailAddress LogicalAddress? 已知写游标(上层快照场景注入;优先于扫盘)。
BeginAddress LogicalAddress? 已知头截断边界(retention 场景注入)。
FlushedUntilAddress LogicalAddress? 已知落盘边界。
CommittedOffset LogicalAddress? 已知 commit 边界(EntryLog 场景注入)。
FileSize long? 已知文件大小(非地址,DeltaLog 临时文件场景近似水位)。

7.3 嵌入式 meta + 临时文件(DeltaLog 形态)

DeltaLog 默认 MetaPolicyKind.Transport——meta entry 作为 IsMeta entry 嵌入 log 流(MetaHost.WriteBlock 走 AppendCore(isMeta: true);ReadLastBlock 走 cursor 找最后 IsMeta entry 的 payload)。无需独立 meta 引擎——临时 delta 文件场景语义(delta 用完即弃,meta 跟随 log 流一起存在/消失)。

7.4 2PC 悬干裁决

恢复时还原 LastPreparedSeq / LastCommittedSeq / PreparedTailAddress——TransactionLog.LoadAndReconcile 据此判 LastPreparedSeq > LastCommittedSeq(悬干)并驱动 Abort 按 PreparedTailAddress TruncateSuffix 回退(跨崩溃可用)。

7.5 扫盘算法细节

阶段 实现
起点 engine.MinAddress(已知帧边界)——非页起点(帧可跨扫描页,落在上一帧中段填充零里会断链)。
帧推进 OpenSequentialReader(Consistent 快照隔离,usePageCache=true)逐帧读 header + data + CRC + padding。
CRC 验收 每帧验证 footer CRC32C(cover = header + dataLen,与 Cursor 同口径)——撕裂/坏帧止步于前一有效帧。
物理截断帧容忍 ReclaimTail 打洞后 committed 边界落在帧中——读不满按实际数据解析(截断点前的 entry 完整保留);无数据 = 真 EOF。截断帧无 CRC/padding——直接按实际解析。
终止 magic 不连续 / dataLen 越界 / CRC 失败 = 空洞/EOF——返回最后一个有效帧尾。

cursor 起点 = 任意 LogicalAddress(不必帧边界):探测分流——帧头 magic 验证通过 → 正常页解析(帧头对齐,零 skip);entry 头 → 无帧头模式(cursor 内跳过 < startAddress 的 entry,页尾靠 TryDetectFrameBoundary 扇区探测下一页帧头)。断点续传重放用——避免每次从 MinAddress 全量重扫。