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(扫盘)。