Table of Contents

VersionedMetadata 使用指南——版本链 N=2 轮转回收 / 单值元数据

给谁看:需要跨重启单值状态(水位/配置/锚点)的组件开发者 回答什么:VersionedMetadata 是什么 / Settings / 版本链 N=2 / 同步 vs 异步持久化 / 外部隔离传输 本篇只讲结构本身——Meta 横切协议(Disabled/Managed/Transport + IMetaTransport)见 meta.md 定位:Structures/ 6 子族之一,搭配件(与 Ring/Log 主结构搭配,跨重启单值状态)


0. 一句话总纲

VersionedMetadata = 版本链追加式单值 + N=2 轮转回收 + 崩溃安全(写一半 = 旧版本完好)。

  • 单值:每次 Write 把整条 payload 当一个版本追加到磁盘版本链,链头即当前值;
  • 内存工作副本(N≥2 对齐槽)让 Read 零 IO、Abort 零 IO(回退到上一版本);
  • 落盘 = 引擎 Allocate + Write + Flush,崩溃写到一半 = 链头 magic/CRC 不匹配 = 旧版本完好(断链天然容错);
  • PayloadSize 须 ≥ 托管块上界(3a 外部隔离传输场景,见 §2、§8 反模式 1)。

1. 定位

维度 内容
与主结构的关系 与 Ring/Log 主结构搭配——承载跨重启的单值状态(如 Ring 的 CommittedTailAddress 锚点、Session 的检查点水位、TimeSeries 的 dense 块水位)
与 Meta 横切件的关系 VersionedMetadata 是 Meta 横切件在结构层的具体实现——结构自身的水位(HighestVersionAddress 等)经 Meta 横切件持久化;横切协议(三模式 + IMetaTransport)见 meta.md
与 Index 的差异 Index 派生数据(可重建、判等闭环、依赖真相源);VersionedMetadata 是单值状态本体(追加流版本链,N=2 轮转回收)
与 Mirror 的差异 Mirror 是字节镜像(不知尺寸的整流式 AppendChunk);VersionedMetadata 是定长/变长单值(每次 Write 一条 record)

两种消费形态:

  1. 直接用——跨重启单值状态:构造 + Initialize + WaitForReady,按 Write/Read/Persist 用。
  2. 3a 外部隔离传输——把别的结构的 meta 块托管到 VersionedMetadata:用内置适配器 MetadataMetaTransport(源码 Meta/MetadataMetaTransport.cs),勿自写单槽文件(见 §8 反模式 2)。

为什么单值用版本链而不是单槽覆盖写:

  • 崩溃安全免费——单槽覆盖写要自理 torn write(写一半崩 = 数据撕裂),版本链追加 + 链头 magic/CRC 校验天然容错;
  • Abort 零 IO——回退上一版本只切内存镜像,不触盘;
  • 空间有界——N=2 轮转回收(ReclaimOldVersions),不会无界增长;
  • 跨结构复用——VersionedMetadata 自身实现 ITransactionParticipant,可注册进 TransactionLog 跨结构原子提交(3a 场景直接用 ext.Storage)。

3. 构造与生命周期

VersionedMetadata 无 Create 工厂——显式三步:构造(= 配置,零 IO)→ Initialize(同步启动后台恢复,立即返回)→ WaitForReady(观测等待恢复完成)。Dispose 幂等。

3.1 直接消费(最常见)

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

// ① 文件系统(介质平权——换介质 = 换一根 spec)
using var fs = TierFs.New("memory:");   // 或 "local:///path/to/dir"

// ② 配置(PayloadSize 必填;其余默认值即生产值)
var settings = new VersionedMetadataSettings(
    new StorageEngineOptions("session.ckpt", 16L * 1024 * 1024, enableSegmentation: false))
{
    PayloadSize = 64,                  // 单值结构体字节数
    MetaPolicyKind = MetaPolicyKind.Managed,   // O(1) 恢复水位;Disabled 走扫盘
};

// ③ 构造 + 启动 + 等就绪
using var md = new VersionedMetadata(fs, settings);
md.Initialize();                       // 同步 void,启动后台恢复后立即返回
md.WaitForReady();                    // 观测等待恢复完成(载入链头版本到内存镜像)

3.2 Write + Read + Abort(写读编排)

// ① 写——返回版本号(单调递增);本调用按落盘策略决定是否立即 flush
long v1 = md.Write(stackalloc byte[] { /* 64B 结构体 */ });
//   v1 == 1(首次 Write 推进到 1;恢复载入过历史版本则从载入版本号续推)

// ② 读——零 IO;首次 Write 前 = 加载版本(盘上真实大小),Write 后 = 现热区
Span<byte> buf = stackalloc byte[64];
int n = md.Read(buf);                  // n = min(当前内容长度, buf.Length)

// ③ 零拷贝视图——仅 epoch 存活期内有效;跨 await 必须改走 Read(dst)
Span<byte> view = md.AsSpan();         // 同步栈内合法
ref var head = ref md.GetRef<long>();  // 强类型首字段引用(热路径零校验)

// ④ 显式持久化点——不注入 SyncPersistencePolicy 时 Write 不自动落盘,需手动触发
md.Persist();                          // 把内存镜像追加为版本链新版本 + flush + 写 meta

// ⑤ 2PC 编排(与 TransactionLog 协同——Prepare 即持久化点)
const long seq = 100;
md.Prepare(seq);                       // 追加新版本 + flush + 写 meta(LastPreparedSeq = seq)
md.ConfirmCommitted(seq);              // CAS 推进 LastCommittedSeq;新版本正式成为当前
//   失败路径:
md.Abort(seq);                         // 内存回退到上一版本(零 IO)+ ReclaimTail 回退悬干新版本

// ⑥ 头截断(后台周期调)——保留最近 N=MaxMemoryVersions 个版本,更老的从链尾方向回收
md.ReclaimOldVersions();

3.3 异步启动(注入恢复 hints)

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
var hints = new MetadataRecoveryHints
{
    HighestVersionAddress = knownHead,  // 上层最强知识——优先级最高(> meta > 扫盘)
    LastCommittedSeq = knownSeq,
};
md.Initialize(hints);                          // 恢复核心:启动主引擎就绪 → meta.Load → 三级回退
await md.WaitForReadyAsync(cts.Token);

3.4 Dispose

// 显式释放(幂等);底层引擎、meta 引擎、epoch、热区对齐内存、缓冲池一并释放
md.Dispose();
// 或异步释放(MetaPolicy 走异步轨)
await md.DisposeAsync().ConfigureAwait(false);

生命周期与全部 Structures 同构(详见 src/KernLab.Tier.Core/docs/lifecycle.md):OnInitializeBegin 启动主引擎 +(Managed 模式)并行启动 meta 引擎;恢复核心 WaitForDependenciesAsync 双 await 引擎就绪 → MetaPolicy.LoadAsync → 三级回退定位链头 → 加载链头版本到内存镜像。

变长档写读:MaxPayloadSize 启用后 Write 允许 ≤ 上限的任意长度,record 按实际长度落盘。CurrentPayloadLength 探测当前内容长度(固定档恒 PayloadSize;变长档随块增长)后分配读缓冲;AsSpan()/GetSpan<T>() 自动按当前实际长度切片。

3.5 文件系统与介质

  • IFileSystem 经组合根 TierFs 注入——介质平权:memory: / local:///path / s3://bucket 等 spec 切换零代码改动;
  • 引擎名隔离同 fs 子目录——多结构同 fs 时引擎名须唯一(如 "my-log" / "my-log.meta");
  • DeleteOnClose:跨重启组合(如 3a 托管)须 false(默认),否则 Dispose 时清盘;测试场景可设 true 自动回收;
  • SectorSize 从 _fs.Volume 静态属性读取——构造期可用,padding/热区分配安全。

8. 反模式

# 反模式 后果 / 正确做法
1 PayloadSize < 托管块上界(3a 场景) WriteBlock 抛 ArgumentException(fail-fast 不截断)。正确:PayloadSize ≥ 12B 头 + 水位 struct(48B)+ MetaOpaqueBytes + 4B 尾,留余量更稳
2 自写单槽文件存 meta(3a 场景) 独自写盘要自理 torn write 原子性、落盘顺序(data 先 meta 后)、崩溃恢复一致性、2PC 提交链路。正确:用 MetadataMetaTransport 托管到 VersionedMetadata(版本链天然容错 + N=2 轮转有界 + 2PC 已实现)
3 绕过 PersistencePolicy 自改落盘时机 一致性失守——Async 策略下 Write 不落盘(落盘只在显式 Prepare/Persist 调用点,调用方线程同步执行),崩在提交点前 = 丢失。正确:需要每次 Write 落盘就注入 SyncPersistencePolicy;上层编排走 2PC(Prepare+ConfirmCommitted)
4 跨 await 持有 AsSpan() / GetRef<T>() 视图 视图仅 epoch 存活期内有效——并发写/Abort 可能使其失效。正确:跨 await 走 Read(dst)(拷贝交付)
5 用地址值 == LogicalAddress.Empty 判断"链头未找到" Empty 是合法地址(地址空间起点,首版本链头就是 Empty)。正确:恢复代码用 headFound 布尔标志(已是这样实现的)
6 统一 record 步进扫描版本链 PayloadSize 跨重启变更后新旧混尺寸,统一步进会落在旧 record 中段 → 静默断链丢数据。正确:按每条 record 头部自述 PayloadLength+PaddingLength 跳进
7 Disabled 模式下 SetOpaqueMeta 期望被接受 抛 InvalidOperationException(禁用即报错,不静默吞)。正确:需要 opaque 就配 Managed/Transport
8 把 meta 块当独立提交路径(自流嵌入 3b 之外的语义) 已废除——自拍水位独立成块 = 并发水位回退 + 被内部提交冲掉。正确:opaque 只登记,随水位提交原子落盘(meta.md §4)

9. 想深入?指路

想懂什么 去哪
源码 src/KernLab.Tier.Runtime/Structures/Metadata/(VersionedMetadata / MetadataBase.* / Contracts/)
Meta 横切协议(三模式 + IMetaTransport + opaque 搭车 + 块格式) meta.md
Session 协调协议(写/读/检查点三 op、悬挂裁决) session.md
引擎使用(Allocate/Write/Flush/Reclaim/Compact) storage-engine.md
段几何 / 段表 segment-table.md
Lease 协议 lease-protocol.md
同族结构 ring.md / log.md / index.md / mirror.md / snapshot.md
总览(七种结构选型 / 组合 KV / 反模式) structures.md

机制级细节(record 42B header 字段全表、扫盘 64KB 页步进、_hotSlotSize 增长策略、Abort 回退分支条件)按需从源码 XML 注释与内部设计稿(不随包发布)查阅——使用面不需要这些细节;能力全集以类型 XML 注释为准。


10. FAQ

问题 答案
Write 后立刻 Read 不到新值? 不会——Write 同步更新内存镜像,Read 零 IO 读内存。但磁盘上不一定有——不注入 SyncPersistencePolicy 时 Write 不自动落盘,崩在 Persist/Prepare 前磁盘链头仍是旧版本(恢复后读旧值)。
MaxMemoryVersions 配 1 行不行? 不行——构造强制 Math.Max(2, value)。N=1 时 Write 覆盖前无可保留的旧版本镜像,Abort 只能冷-热回退到加载版本(无法热-热回退到上一 Write)。N=2 是 Abort 零 IO 的几何底线。
跨重启改 PayloadSize 安全吗? 安全——历史版本按盘上真实 PayloadLength 从自持池租借只读缓冲,不补零不截断完整交付;本次运行的新版本按新 PayloadSize 几何落盘。版本链混尺寸由每条 record 头部自述几何支撑(扫描/回收按各自 PayloadLength+PaddingLength 跳进)。
Prepare 后 Abort 之间还能 Read 到新值吗? 能——Prepare 已追加新版本到磁盘链头并 flush,但 LastCommittedSeq 未推进;内存镜像也是新值。Abort 后才回退(内存 + 磁盘链头 + 版本号一并回退到 _prepareSnapshotAddress)。
Disabled 模式恢复慢吗? 慢——扫盘 O(链长/盘),最大扫 64MB。GB/TB 级单值状态强烈建议开 Managed(O(1) 读水位)。VersionedMetadata 单值场景一般几 KB 到 MB,扫盘可接受;3a 托管场景按主流结构大小判断。
变长档下 AsSpan() 返回的 span 长度? 当前内容长度(加载版本按盘上真实 PayloadLength / 热区按最近 Write 长度)。不是 PayloadSize,也不是 MaxPayloadSize——按当前实际镜像切片。CurrentPayloadLength 是探测入口。

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