Log——持久化机制与恢复协议
分册导航:log.md | [log-api.md](API 与工厂) | log-persistence.md | Log——Settings / API 详表 / 注入工厂 | Log——持久化机制与恢复协议
6. 持久化机制
[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 驱动 |
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. 恢复协议
| 优先级 |
来源 |
适用 |
① 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 临时文件场景近似水位)。 |
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 全量重扫。