Table of Contents

Meta 策略契约(Meta/)

MetaPolicyKind(四档)

档 语义
Disabled(缺省) no-op——不持久化(纯派生重放结构免 meta 税);SetOpaqueMeta 抛错、2PC Prepare 静默 no-op(恢复裁决不可用——组合有效性由产品层保证,见 #713 拍板)
Managed 独立 meta 引擎(.meta 文件)+ 固定块覆盖写 + Magic/CRC 校验——O(1) 恢复正路
Transport 统一传输——上层注入 IMetaTransport 实例(自定义介质:单槽文件/远程/KV);未注入回落结构自身存储流(MetaHost:追加 IS_META record + 倒序扫描)
  • 基类 Settings.MetaPolicyKind 缺省 Disabled;各产品 Builder 显式选定 (家族现状:Queue/TS/Collections/Wal/TierKv = Managed、DeltaLog = Transport、VarKv = Disabled)。
  • 组合控制源头原则:meta 是底层结构策略(原语中立);产品提供什么公开契约就配什么底座—— 拦截落产品装配期,禁加在原语上(TierKv Disabled 档 routine 调 PrepareAsync,原语拦截 = breaking)。

IMetaTransport(传输契约——策略与介质的唯一通道)

  • 写完整 meta block / 读最后一条——块格式与 CRC 完全由策略负责([Header][Payload][Footer Crc32C]), 传输只搬字节,不承担完整性校验;
  • 读写统一 Span/Memory 零中间拷贝;空 = 无数据(ReadLastBlock 返回 Empty span, 不用 null);视图有效至本传输下一次调用(留存必须立即拷贝);last-write-wins,同步/异步对等。

IMetaLayout / IMetaPolicy / MetaPolicyFactory

  • IMetaLayout<THeader,TPayload>:HeaderSize/PayloadSize(自述布局)/Magic/Version/序列化委托 ——旧块短 payload 零扩展降级(新字段读默认值不抛)。
  • IMetaPolicy:Load/LoadAsync(恢复读回)+ WriteHeader/WritePayload/Commit(Async)(落盘) ——DisabledMetaPolicy 全成员 no-op;TransportMetaPolicy 未注入传输时构造回落 MetaHost。
  • MetaPolicyFactory:MetaPolicyKind → IMetaPolicy 单点映射(构造期 ??= 收口—— 注入工厂与默认实现同一条 kind→policy 映射,无匿名 lambda)。

反模式

  1. 产品公开了依赖 meta 的契约(原子批/版本高水位/水位持久化)却把策略留在 Disabled—— 底座缺失是产品层组合错误(对照 #713)。
  2. IMetaTransport 实现里解析块内容或做 CRC——格式归策略,传输只搬字节。
  3. 新格式 payload 旧块兼容走抛错——零扩展降级(短 payload 补零解读,新字段读默认值)。

源码:Meta/(MetaPolicyKind / IMetaPolicy / IMetaLayout / IMetaTransport / MetaPolicyFactory)。 行为面:meta.md。