Table of Contents

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

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

6. 持久化机制

6.1 版本链追加

每次 checkpoint 写一个完整新版本追加到流尾,不重写旧帧。链经 PreviousVersion(帧尾字段)回跳:

  • WholeMirror:全局单链,PreviousVersion = 上一 checkpoint 链头(首版本 = Invalid——Empty 是合法 seg0@0,不能当哨兵)。
  • PagedMirror:per-page 多链,PreviousVersion = 该页上一帧头(页首版本 = Invalid)。

帧长任意字节边界——v2 流式帧教义:格式零长度字段,帧长 = 尾位 − 头(推导的事实)。下一帧起点 = 本帧尾末(AllocatedTail 恒贴已写尾,帧间零间隙)。

6.2 EndSession flush

WholeMirror.EndSession 内部调 _engine.Flush()——数据落盘到设备(fsync)。非 2PC 用法在此即持久(单 checkpoint 自包含);2PC 用法下 Prepare 再 flush 是幂等加固。

PagedMirror 逐页不 flush(性能优先)——WritePage 只 EndFrame,落盘由 Prepare 统一 flush。

为何 Prepare 是 2PC 持久化点:数据 fsync 先于 meta fsync——断电时 meta 绝不标记 data 未落盘的 commit 点(设计决策:data fsync → meta fsync 严格偏序,崩溃一致性核心保证)。崩溃在 Prepare 后 Commit 前:seq 未推进 → 恢复按 meta 裁决尾截断悬干(一致)。

6.3 N=2 轮替回收

ConfirmCommitted 自动调 ReclaimOldVersions:保留窗口 = 当前 + 上一 checkpoint,更老物理回收(_engine.ReclaimHead 头截断——punch hole 清零旧帧 magic,链头重建后失效帧不可再定位)。

  • WholeMirror:ComputeRetainFloor 返回全局第二新地址(无第二新回退链头自身 = 不回收)。
  • PagedMirror:返回所有页 keepAddr 的最小值(引擎 MinAddress 是全局水位,只能推进到所有页都同意回收的地址——否则误删某页在用版本)。
  • keepAddr == Empty 时基类守卫保守跳过本轮(Empty 是合法地址,下轮补收——正确性优先)。

6.4 Transport 嵌入 meta 帧

MetaPolicyKind.Transport 模式下,meta block 作为 IS_META 帧追加进镜像流(统一帧机制——meta 帧是宿主流的一等公民):

  • 写:基类 WriteEmbeddedMetaBlockCore 走帧三拍 + FLAG_ENTRY_IS_META(不参与数据版本链——PreviousVersion=Invalid、版本号用当前值不推进、EndFrame 对 IS_META 跳过 OnRecordAppended),只追加在流尾供找回。
  • 读:ScanLastEmbeddedMetaBlockCore 前向帧走链单步原语扫描收集 IS_META 帧(结构完好即收——payload 交 meta policy 自校验)。
  • 默认回落:未注入 IMetaTransport 时基类自装配 MetaHost 嵌套类(实现 IMetaTransport)——无需独立 meta 引擎 / 独立文件。

6.5 2PC 协议

Prepare:_engine.Flush() + WriteMeta()(LastPreparedSeq + 悬干水位落 meta)。 ConfirmCommitted:CAS 推进 LastCommittedSeq + 子类 OnConfirmSession(链头推进)+ N=2 头截断 + 刷新 meta + 触发回调。 OnCommitted:注册链式回调(已提交到更高 seq 时立即同步触发)。 Abort:见下。

6.6 Abort 语义 = 丢弃未确认会话

if (seq <= LastAbortedSeq) return;           // 幂等
if (_sessionActive) {
    OnAbortSession();                         // 子类清 pending(WholeMirror=ClearPendingFrame;PagedMirror=_sessionWrites.Clear())
    if (_lastRecordEnd > _committedChainEnd) {
        _engine.ReclaimTail(_committedChainEnd);  // 物理丢弃悬干(引擎退化 AllocatedTail)
        _lastRecordEnd = _committedChainEnd;
    }
    _sessionActive = false;
}
LastPreparedSeq = LastCommittedSeq;          // 回退 Prepare 点
LastAbortedSeq = seq;
WriteMeta();

关键不变量:committed 链头未被会话触碰(Abort 不动 committed);尾截断只丢悬干;LastPreparedSeq 回退到 LastCommittedSeq。

2PC Abort 演示——v1 提交后 v2 写完 + Prepare → Abort:

using var mirror = new WholeMirror(fs, new WholeMirrorSettings());
mirror.Initialize();
mirror.WaitForReady();

// v1:写完 → Prepare → Confirm(落定提交)
WriteCheckpoint(mirror, 8192, 0x11);          // BeginSession + AppendChunk + EndSession
mirror.Prepare(seq: 1);
mirror.ConfirmCommitted(seq: 1);
var v1Addr = mirror.HighestVersionAddress;    // 已提交链头

// v2:写完 → Prepare → Abort(悬干整体回退)
WriteCheckpoint(mirror, 8192, 0x22);
mirror.Prepare(seq: 2);
mirror.Abort(seq: 2);                          // 尾截断物理丢弃 [committedChainEnd, AllocatedTail)

// 不变量 1:链头回退到 v1
mirror.HighestVersionAddress.Should().Be(v1Addr, "Abort 应回退链头到上一已提交 checkpoint");
// 不变量 2:版本号不推进
mirror.CurrentVersion.Should().Be(1, "Abort 不推进 checkpoint 版本号");
// 不变量 3:LastPreparedSeq 回退到 LastCommittedSeq
((ITransactionParticipant)mirror).LastPreparedSeq.Should().Be(1);
// 不变量 4:已提交 checkpoint 不受 Abort 影响——v1 CRC 完整可读
var dst = new byte[8192];
mirror.ReadChunk(v1Addr, 0, dst);
dst[0].Should().Be(0x11, "已提交 checkpoint 不受 Abort 影响");
mirror.Verify(v1Addr).Should().BeTrue("Abort 尾截断后 v1 CRC 完整");

WholeMirror vs PagedMirror Abort 差异:机制在基类统一执行;子类 OnAbortSession 只清各自的 pending 状态:

  • WholeMirror:ClearPendingFrame()(清 _hasPendingFrame / _pendingFrameHead / _pendingFrameFooter)。
  • PagedMirror:_sessionWrites.Clear()(清会话内逐页写入记录——committed 各页链头未被会话触碰)。

PagedMirror Abort 的多链原子性:会话 2 写 page 0 + page 1 两页后 Abort,两页的 v2 写入一起回退,page 0/1 各自链头仍指向 v1——单链故障不会污染多链整体。


7. 恢复协议

7.1 三级回退(DefaultMirrorRecovery)

Initialize → 后台恢复核心 OnRecoveryCoreAsync(hints, ct):

  1. hints 优先:MirrorRecoveryHints.HighestVersionAddress / LastCommittedSeq——上层已知水位直接注入。
  2. meta Load(O(1) 水位):MetaPolicyKind != Disabled 时 await MetaPolicy.LoadAsync → 读 MirrorMetaPayload(版本链两端 + LastCommittedSeq + LastPreparedSeq)。
  3. 扫盘兜底:ScanAndRebuild 按版本号定位链头——Single 走尾锚快速路径(Locate(尾 magic, Last) 直达最新数据帧 + PreviousVersion 回跳 N=2 第二新),PerKey 全走链按 PageId 重建各链头。

7.2 悬干裁决

meta.LastPreparedSeq > LastCommittedSeq → 最后一批帧(按最高会话版本号识别)视为悬干,_engine.ReclaimTail 物理丢弃。无 meta(Disabled / 损坏)= 无裁决依据,扫到状态视为已提交。

7.3 按版本号截断(与 Snapshot 恢复差异)

维度 Mirror Snapshot
截断坐标系 版本号(会话版本号识别"最后一批未裁决 record") 字节(按 CommittedTail 截断)
保留版本数 N=2(当前 + 上一 checkpoint) 1(最新基线)
悬干回退 meta prepared > committed 时尾截断物理丢弃 无版本概念——纯流式
多链 PagedMirror per-page 独立链头(按 PageId 重建) 不适用

7.4 帧判定链零长度依赖

恢复扫盘的"什么是有效帧"裁决链——格式本身不含长度字段,靠三件套判定:

层 判据 假命中的兜底
候选提名 双 magic 值匹配(头 magic + 尾 magic) 假 magic 必经 CRC 裁决淘汰
结构校验 Version == CurrentVersion + flags 的 CRC 算法位(CRC64/CRC32C) 版本/flags 不符直接否
头尾版本一致 footer.MirrorVersion == header.MirrorVersion 假尾缩窗继续倒扫
权威帧 最新帧(WholeMirror 尾锚路径)走 CRC 全验 旧代只验结构不读体——旧代损坏不遮新代

关键性质:帧长任意字节边界(v2 alignment=1);payload 埋诱饵(payload 内塞双 magic)不影响本帧 CRC(覆盖域原样入算);旧代损坏不遮新代(尾锚只看最新方向 + PreviousVersion 链对旧代只验结构不读体)。

7.5 恢复 hints 注入

var hints = new MirrorRecoveryHints
{
    HighestVersionAddress = knownHeadAddr,    // 已知链头(上层注入,优先于扫盘)
    LastCommittedSeq      = 100,             // 已知提交点
};
mirror.Initialize(hints);                    // 注入恢复提示
mirror.WaitForReady();

7.6 整体流程一览

  ┌─────────────────────────────────────────────────────────────┐
  │ Initialize() ──> OnInitializeBegin (主引擎 + meta 引擎并行启动) │
  ├─────────────────────────────────────────────────────────────┤
  │          WaitForDependenciesAsync (双引擎 join)              │
  ├─────────────────────────────────────────────────────────────┤
  │           OnRecoveryCoreAsync(hints, ct) 恢复核心           │
  │  1. MetaPolicy.LoadAsync → 读 MirrorMetaPayload (O(1) 水位) │
  │  2. 三级回退:hints → meta → 扫盘定位链头                    │
  │  3. 悬干裁决:meta.LastPreparedSeq > LastCommittedSeq →     │
  │     尾截断物理丢弃(按最高会话版本号识别)                    │
  │  4. ScanAndRebuild:Single 走尾锚快速路径;PerKey 全走链    │
  │     按 PageId 重建各链头                                     │
  ├─────────────────────────────────────────────────────────────┤
  │             MarkReady → IsReady=true 可读写                 │
  └─────────────────────────────────────────────────────────────┘

性能特性:Managed meta 模式下恢复 O(1)(读水位块即得链头);Disabled / meta 损坏走扫盘——WholeMirror 尾锚路径直达最新帧(一次 Locate(尾 magic, Last) + 倒扫本帧头 + PreviousVersion 回跳 N=2 第二新),PagedMirror 全走链按 PageId 重建(每页独立链头,扫盘代价与页数线性)。