Table of Contents

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

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

6. 持久化机制

6.1 版本链 N=2 轮转回收

  • 磁盘:版本链追加流——每次落盘 = Allocate(recordSize).Start + Write(addr, span) + Flush。record 几何 = [Header 42B][Payload 实际长][Padding 扇区对齐],CRC32C in Header(覆盖 Header 除 Crc 自身 + Payload + Padding)。
  • 内存:N 个对齐槽(AlignedMemoryManager,pinned native,零 GC)。Write 在覆盖 [0] 前先把 [0] 滑到 [1](保留为 Abort 零 IO 回退源)。N≥2 是底线——MaxMemoryVersions 强制 Math.Max(2, value)。
  • 轮转回收:ReclaimOldVersions 按 MaxMemoryVersions 保留窗口——[keepAddr, highest] = 最近 N 个版本,更老的从链尾方向 ReclaimHead。epoch 保护(BumpCurrentEpoch 等 readers 退出后回收)。
  • 逐 record 自身几何推进:链上 record 尺寸可能不同(PayloadSize 跨重启变更后新旧混尺寸),扫描/回收按每条 record 头部自述的 PayloadLength+PaddingLength 跳进——统一 record 步进会落在旧 record 中段,断链静默丢数据。

版本 record 42B Header 布局(MetadataHeader,源生成器 [BinaryLayout] 生成 codec):

偏移 长度 字段 说明
0 4 MagicValue 魔数 = RecordMagic.VersionedMetadata,块身份校验
4 2 Version 头版本号(major=1, minor=0),ValidEquals 校验
6 2 Flags DefaultFlags = FLAG_CRC32C \| FLAG_PAYLOAD_4B;meta record 叠加 FLAG_ENTRY_IS_META
8 4 PayloadLength 元数据结构体字节数(payload 实际长度)
12 2 PaddingLength 扇区对齐填充字节数
14 16 PreviousVersion 版本链指针,指向上一版本(链尾为 LogicalAddress.Empty)
30 8 MetadataVersion 版本号(单调递增;调用方按版本号寻址/恢复定位)
38 4 Crc CRC32C(覆盖 Header 除 Crc 自身 + Payload + Padding)

6.2 同步 vs 异步持久化策略对比

策略 ShouldPersist(version) 何时落盘 适用 代价
不注入(默认) (不调) 仅 Prepare / Persist 显式触发 上层用 2PC 编排提交点(如 Session) Write 不自动落盘——崩在 Prepare 前 = 丢失
SyncPersistencePolicy 恒 true 每次 Write 立即 AppendVersionToDisk + flush 单值独立持久化(不参与 2PC) 每次 Write 强制 IO(最高一致性,最低吞吐)
AsyncPersistencePolicy 恒 false Prepare / Persist 显式触发 高频写、容忍延迟落盘(提交点自控) Write 不自动落盘(策略仅是恒 false 谓词——无后台线程);崩在显式 Prepare/Persist 前 = 丢失未提交版本

Prepare 无论何种策略都强制 flush——2PC 协议要求 Prepare 即持久化点(WriteAsync 不保证落盘)。

6.3 内存热窗口(Abort 零 IO 的关键)

Write 在覆盖热区 [0] 前,先把 [0] 滑到 [1],使 [1] 始终持有上一版本镜像:

[0] = 当前版本(最近 Write 的目标)
[1] = 上一版本(Abort 零 IO 回退源;写覆盖前的镜像)
[2..N-1] = 更老版本(MaxMemoryVersions > 2 时支持 MVCC)
  • 拷贝顺序从高索引往低索引([N-1] ← [N-2] ← ... ← [1] ← [0]),避免 [0]→[1] 覆盖 [1] 旧值前未读到;
  • 变长档槽增长:EnsureHotSlotSize(needed) 按需重分配整组槽(max(needed, 当前×2) 对数摊薄,上限 _hotCapacity),搬移既有镜像;固定档恒跳过(槽尺寸 = PayloadSize);
  • 冷热分离:恢复载入的历史版本按盘上真实 PayloadLength 从自持 PinnedBufferPool 租借只读缓冲,不进按当前配置分配的读写热区——历史大小 ≠ 当前 PayloadSize 时不补零、不截断;首次 Write 后当前内容切到热区,加载版本归还池(两次 Write 后不可达);
  • Abort 回退分支:会话内有 Write(_currentVersion > _baseVersion)时——两次以上写走热-热回退([1]→[0]);单次写且前置 = 加载版本走冷-热回退(_serveLoaded = true,回到恢复载入的历史版本完整大小)。

6.4 崩溃安全

天然容错——无需 WAL:

  • 写到一半(torn write):链头 record magic/CRC 不匹配 → 恢复时 TryReadHeader 返回 false → 链断在上一合法 record(旧版本完好);
  • 内存镜像未落盘:恢复时从盘上链头载入(旧版本);
  • Prepare 后 Commit 前:磁盘链头是 Prepare 追加的新版本,但 LastCommittedSeq 未推进——恢复时 LastPreparedSeq > LastCommittedSeq 即悬干,Abort 触发尾截断 ReclaimTail 回退(按 record 自身几何 + _lastAppendedRecordSize)。

6.5 外部隔离传输(3a 托管)

把别的结构的 meta 块托管到 VersionedMetadata——用内置适配器 MetadataMetaTransport:

using KernLab.Tier.Core.IO;
using KernLab.Tier.Runtime.Meta;
using KernLab.Tier.Runtime.Structures;
using KernLab.Tier.Runtime.Structures.Metadata;

using var fs = TierFs.New("local:///var/lib/myapp");

// ★ PayloadSize 须 ≥ meta 块上界:12B 头 + 水位 struct + MetaOpaqueBytes + 4B 尾
//   MetadataMetaPayload = 48B;按调用方 MaxMetaOpaqueBytes 估算后留余量更稳
var hostSettings = new VersionedMetadataSettings(
    new StorageEngineOptions("my-log.meta", 1L << 20, enableSegmentation: false))
{
    PayloadSize = 4096,                       // 留足余量(远大于 64 + MetaOpaqueBytes)
    MetaPolicyKind = MetaPolicyKind.Disabled, // 托管结构自身水位走扫盘(无嵌套 meta)
};

// 构造 + 启动(适配器内部 Initialize;首次读写 WaitForReady 就绪)
using var ext = new MetadataMetaTransport(fs, hostSettings);

// 注入到 Log/Ring/Mirror 等主结构的 settings.MetaPolicyKind = Transport 时使用
var logSettings = new EntryLogSettings(
    new StorageEngineOptions("my-log", 64L << 20)) { MetaPolicyKind = MetaPolicyKind.Transport };
using var log = new EntryLog(fs, logSettings, metaTransport: ext);

// ★ 适配器语义:WriteBlock = Write + Persist + flush + ReclaimOldVersions(N=2 轮转有界)
//   ReadLastBlock = 内存镜像零 IO 读 + 按统一布局自述裁剪为变长精确块
//   需要 2PC 跨结构原子提交时经 ext.Storage(VersionedMetadata 自身已实现 ITransactionParticipant)

WriteBlock 即 meta fsync 点(data 在调用链先行落盘);3a 语义下主结构主流水位线零影响——meta 块写入与主结构引擎完全解耦(详见 meta.md §6.3)。


7. 恢复协议

DefaultMetadataRecovery(继承 RecoveryBase<MetadataRecoveryHints> 模板,三级回退——对齐 meta.md §6.2 全结构统一优先级):

① WaitForDependenciesAsync:等主引擎 + meta 引擎(Managed 模式)双 await 全异步轨就绪
② MetaPolicy 装配(恢复核心钩子内——依赖引擎就绪)
③ meta.LoadAsync(水位 O(1);Disabled no-op)
④ 三级回退定位链头:
   1. hints(外部注入 HighestVersionAddress——最高优先级)
   2. meta payload(HighestVersionAddress + LastCommittedSeq + LowestVersionAddress——O(1))
   3. 扫盘按版本号定位 Head(无 meta / meta 损坏兜底)
⑤ LoadVersionToMemory(head):按 record 自身 PayloadLength 从自持 PinnedBufferPool 租借只读缓冲
   ——历史大小 ≠ 当前 PayloadSize 时不补零不截断,完整交付

扫盘:从 MinAddress 正向扫,按每条 record 自身 PayloadLength+PaddingLength 跳进,magic 不匹配 = 链结束。最后一条合法数据 record = 链头(最高地址 = 最新写入)。跳过 IS_META record(Transport 自流嵌入模式的 meta block 不参与数据版本号定位,几何跳进照常)。

链头判定细节:

  • 不用地址值 == LogicalAddress.Empty 判断"有没有找到"——Empty 是合法地址(地址空间起点,首版本链头就是 Empty);用 headFound 布尔标志;
  • 链头 = 最高地址的数据 record——不用版本号比较:同一版本号可能被多次持久化(Write 落盘 + Prepare 再落盘),版本号相同但地址递增,最新地址才是当前链头;
  • 扫盘 64KB 页步进(ScanProbePageSize)用于 magic 首扫定位起点;几何跳进后逐 record 头校验;最大扫盘 64MB 防失控。

与 Meta 横切件配合:

  • 结构自身水位(HighestVersionAddress 等)经 Meta 横切件持久化(MetaPolicyKind 三模式);
  • 3a 场景下 VersionedMetadata 自身被 MetadataMetaTransport 包成别的结构的 meta 介质——结构自身的水位走 Managed(嵌套 .meta.meta 引擎)或 Disabled(扫盘)。