Table of Contents

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

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

6. 持久化机制

6.1 页池状态机(4 态)

mutable → readonly → flushed → evicted
   ↑          │             │            │
   │          │             │            │
   └──────────┴─────────────┴────────────┘
            (slot 循环复用:pageSeq & PageCountMask)
  • mutable:当前写者活跃区,TryAllocate 推进 TailAddress
  • readonly:页面冻结,等待 flush。ReadOnlyAddress 推进经 PageAlignedShiftReadOnlyAddress(页边界对齐)
  • flushed:已写引擎(AsyncFlushPages 把页内容 Write 回它对应的引擎地址——同地址 100% 确定)。FlushedUntilAddress 推进
  • evicted:旧页回收(head 推进 FreePage)。HeadAddress / SafeHeadAddress 推进

页池固定 N 槽(PageCount = MemorySize/PageSize),slot = pageSeq & PageCountMask 循环复用。地址单调递增永不回退,写满一圈淘汰旧页(FASTER hybrid log 模型)。_emptyPageCount 默认 PageCount-1(最大 mutable 区);_headOffsetLagBytes = (PageCount-1) × PageSize 决定 mutable 区大小 + 自动驱逐触发点;_readOnlyLagBytes = MutableFraction × (PageCount-1) × PageSize 决定 mutable→readonly 转换点。

6.2 FlushedUntilAddress 推进路径

  • FlushUntil(untilAddress) / FlushUntilAsync:持久化契约面(写穿 + fsync)。_flushGate 串行门保证并发 flush 区间不重叠——「读水位快照 → 迭代刷页 → 推进水位」三步原子,避免两个并发 flush 的区间重叠触发关页链 Shift→OnPagesClosed→FreePage 把对方迭代中的页置 null
  • FlushUntilTail() / FlushUntilTailAsync:tail 原子快照(tail 在 _tailLock 内原子读取,读与用之间不被并发推进混入;快照之后的并发写入由后续 flush 覆盖,水位 CAS128 单调)
  • WriteThroughUntil(untilAddress):容量写穿(驱逐链专用,零 fsync)——页复用前数据已在设备,进程崩溃安全,断电窗口归上层 checkpoint/Committed 档承担

flush 路径必调 InvalidateColdPageCache(页内容随追加演进,flush 后缓存快照即陈旧——W6 缺陷根因修复:不失效则同页后续冷读永久供陈旧快照,resolver 回读 key 不匹配 → Find=Empty)。

在途 flush 登记与关页 worker 互斥(_ongoingCloseLock 内登记区间,worker 走到与在途区间相交的页即停止本轮回收,由下一次关页触发续走)。

6.3 meta 持久化(IRingMetaPolicy)

  • WriteMeta / WriteMetaAsync:更新 meta 缓冲(水位 + payload)+ Commit 落盘。flushedUntilOverride 参数:Transport 回落 MetaHost 时的 1-fsync Prepare 优化——先记 dataTail 再随数据同页 flush,避免 Managed 那种"先 flush 再记水位"的 2 次 fsync
  • WriteMetaRecord(private protected):把内层 meta block 作为 FLAG_ENTRY_IS_META record 追加到 TailAddress(纯内存写:分配 tail + 写 header + 写 payload + CRC + Seal,零 device IO;落盘靠 Prepare 末尾 FlushUntil)。flags 顺序约定:写 header 时就设全 IS_META|VALID|SEALED,再 FillCrc(CRC 覆盖含 flags 字段),最后 Seal 幂等
  • BuildMetaPayload:7 LogicalAddress(Begin/FlushedUntil/SafeReadOnly/ReadOnly/Tail/OverflowTail/CommittedTail,各 16B = 112B)+ LastCommittedSeq(8B) + LastPreparedSeq(8B) + KeySize(4B) = 132B
  • MetaLayout(sealed 嵌套):实现 IMetaLayout<RingMetaHeader, RingMetaPayload>——12B 规范 header + 结构化 payload + opaque 插槽;旧块短 payload 零扩展降级(新字段读默认值,优雅不抛)
  • MetaHost(sealed 嵌套):Transport 未注入传输时的回落——meta record 作为 FLAG_ENTRY_IS_META 追加到 ring 流末尾;读回 = 倒序扫 ring 流找最后一条有效 IS_META record 的 payload

详见 meta.md。

6.4 与 StorageEngine 关系

  • 主引擎构造期 Create(纯装配零 IO),OnInitializeBegin 内 Initialize(非阻塞)
  • 溢出引擎(OverflowPolicy=Enabled 时构造,引擎名 .overflow 后缀,与主引擎同 fs、同几何)
  • meta 引擎(MetaPolicyKind=Managed 时构造,引擎名 .meta 后缀,段大小 ≥ 1MB,不分段)
  • 三引擎在 OnInitializeBegin 并行启动,WaitForDependenciesAsync 异步 join;引擎就绪由 DefaultRingRecovery.RecoverAsync 开头 WaitForReadyAsync 保证
  • 水位线归结构层:引擎自恢复 MinAddress/AllocatedTail,结构水位走 meta/扫盘,不下传
  • _dataStart 构造时由首次 Allocate 确定(GetDistance 锚点,100% 确定);pageSeq = GetDistance(_dataStart, addr) >> PageSizeBits;pageIntra = GetDistance(_dataStart, addr) & PageSizeMask
  • 热路径快路径:同段(Ring 单段是常态)时 DistanceFromDataStart = 纯 long 减法,零引擎调用;跨段才 fallback 到 engine.GetDistance

7. 恢复协议

7.1 四级回退(DefaultRingRecovery.OnRecoveryCoreAsync)

① RingRecoveryHints.RecoveredTail(外部主动注入最高优先级)
   → hints.FlushedUntilAddress(次选)
② meta(O(1) 正路):MetaPolicy.LoadAsync → RingMetaPayload
   + KeySize 锚点校验(防拿错特化开同一卷,fail-fast)
   + 2PC 水位还原(LastCommittedSeq/LastPreparedSeq/CommittedTailAddress)
③ 引擎 CommittedTail(已落盘区域)
④ 扫盘找 torn write 边界:
   MagicLocator 倒序找最后含 magic 的页(Monotone 快速档)
   → ForwardScanRecordsAsync 前向逐页扫 record,CRC 校验求精
   → 同页撕裂重同步(坏帧按对齐粒度步进续扫,不连带丢同页后续有效帧)

7.2 RingRecoveryHints 注入

public readonly struct RingRecoveryHints
{
    public LogicalAddress? BeginAddress { get; init; }
    public LogicalAddress? HeadAddress { get; init; }
    public LogicalAddress? FlushedUntilAddress { get; init; }
    public LogicalAddress? RecoveredTail { get; init; }            // 上层快照场景注入,优先于扫盘
    public LogicalAddress? OverflowTailAddress { get; init; }      // 溢出引擎尾
}

7.3 自愈读(read-protection-tiering v2)

不变式(读安全性由不变式承担,不依赖调用方编排):

  • I1 写穿先行:addr < FlushedUntilAddress → 数据已在引擎
  • I2 水位内完整:addr < SafeSnapshotTail → 页池必有完整 record(写者写完才推进水位)
  • I4 内容指纹:magic + CRC32C 校验

读分档判据 = IsHotRecord(dist):head ≤ addr < SafeSnapshotTail → 页池直读;addr < head → 页已回收(强制设备读,防同形记录复用别名假数据);addr ≥ SafeSnapshotTail → 设备读。热直读经 magic+CRC 校验失败自动回退设备重读——页池与设备互为自愈。

7.4 锚点 W 与 Index 协议

① Ring.CreateAsync → 恢复水位;锚点 W = ring.ReadOpaqueMeta()
   (无锚点 / 损坏 / W 越过当前尾 → 回退 BeginAddress——宁可旧多重放)
② index 拉流重放:ScanAsync(W, TailAddress) 逐条 Insert 自建
   (Hash/SortedIndex 有主存储帧时优先载帧,见 structures.md §4)

锚点 W = 索引上次主存储 dump/重放完成的水位,经 Ring 的 opaque 随水位线原子落盘;每次 dump/重放后 ring.SetOpaqueMeta(W) 即可。详见 meta.md。

7.5 溢出引擎尾恢复

RecoverOverflowTail 三级回退(同主流程):

  1. hints.OverflowTailAddress 注入
  2. meta 的 OverflowTailAddress 字段
  3. OpenSequentialReader 扫描溢出帧(逐帧 magic + Skip payload,恢复容忍不验 CRC,上层读时再校验)
  4. 引擎 AllocatedTail 近似

恢复后引擎尾对齐:_overflowTailAddress 落后于引擎物理尾时(撕裂写预留/Wasted 区间),ReclaimTail 退齐——否则新溢出帧从撕裂区中间分配,与遗留 Wasted 区间相交被读门拦截。