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把对方迭代中的页置 nullFlushUntilTail()/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 次 fsyncWriteMetaRecord(private protected):把内层 meta block 作为FLAG_ENTRY_IS_METArecord 追加到 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) = 132BMetaLayout(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 三级回退(同主流程):
hints.OverflowTailAddress注入- meta 的
OverflowTailAddress字段 OpenSequentialReader扫描溢出帧(逐帧 magic + Skip payload,恢复容忍不验 CRC,上层读时再校验)- 引擎
AllocatedTail近似
恢复后引擎尾对齐:_overflowTailAddress 落后于引擎物理尾时(撕裂写预留/Wasted 区间),ReclaimTail 退齐——否则新溢出帧从撕裂区中间分配,与遗留 Wasted 区间相交被读门拦截。