Table of Contents

VersionedMetadata——Settings / API 详表 / 注入工厂

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

2. Settings 全参数

VersionedMetadataSettings(继承 MetadataSettings ← Settings 基类公共 meta 配置):

字段 类型 默认 说明
MainEngine StorageEngineOptions "tc.metadata",单段 16MB,不分段,不预分配 主引擎选项。Metadata 版本链默认单段稀疏按需增长(元数据是结构体级小数据)
PayloadSize int 必填 元数据结构体字节数(写入 payload 大小,自动向上对齐到扇区)。3a 托管场景须 ≥ meta 块上界(12B 头 + 水位 struct + MetaOpaqueBytes + 4B 尾)
MaxPayloadSize int? null 变长档写入上限。null = 固定档(Write 截断/补零到 PayloadSize);非 null 且 > PayloadSize = 变长档(Write 允许 ≤ 上限任意长度,record 按实际长度落盘,超上限 fail-fast 抛)
MaxMemoryVersions int 2 内存多版本保留窗口(N≥2 是 Abort 零 IO 底线,可配更高支持 MVCC)。构造时强制 Math.Max(2, value)
MetaPolicyKind MetaPolicyKind Disabled meta 横切件三模式:Disabled(扫盘恢复)/ Managed(独立 .meta 引擎)/ Transport(外部 IMetaTransport)——见 meta.md §1
MetaOpaqueBytes int 0 外部 opaque 区容量(写侧约束,不参与盘上几何)。3a 托管场景按调用方需要配置

跨重启改 PayloadSize 合法:恢复载入的历史版本按其盘上真实 PayloadLength 完整交付(不补零、不截断);本次运行的新版本按新 PayloadSize 几何落盘。版本链混尺寸由各 record 头部自述几何支撑。

MaxPayloadSize 何时用:keyed 分区元数据(如 TimeSeries dense 水位块——n 随序列增长,每次 Write 的块长动态)。固定档消费者(Queue/Blob 等)逐字节行为不变。


4. API 详表

API 签名 说明
写 long Write(ReadOnlySpan<byte> data) 把 data 写入内存镜像,推进版本号,按落盘策略触发持久化。固定档:长截短补;变长档:超 MaxPayloadSize 抛。返回新版本号(单调递增;恢复后从载入版本续推)
持久化 void Persist() 强制把内存镜像作为新版本追加到磁盘版本链 + flush + 写 meta。内容未变跳过(防重复/防缩容零覆写)
读(拷贝) int Read(Span<byte> dst) 零 IO 读当前内容。加载版本优先(首次 Write 前按盘上真实大小交付);Write 后 = 热区。返回实际读取字节数
读(零拷贝) Span<byte> AsSpan() 当前内容 0-copy Span 视图。仅 epoch 存活期内有效——并发写/Abort 可能使其失效
读(强类型引用) ref T GetRef<T>() where T : unmanaged 当前内容首字节按 T 重解释的引用(热路径 GetRefUnsafe 零校验)
读(强类型 Span) Span<T> GetSpan<T>() where T : unmanaged 按 T 重解释的 Span。要求内容大小与 sizeof(T) 对齐——历史大小 ≠ PayloadSize 时可能抛
热路径读 int ReadNoEpoch(Span<byte> dst) 不含 epoch 进出的读(供已持 epoch 的 scope/batch 内调)。裸调危险
当前长度 int CurrentPayloadLength { get; } 加载版本按盘上真实长度 / 热区按最近 Write 长度。分配读缓冲前探测用
水位·链头 LogicalAddress HighestVersionAddress { get; } 链头/最新版本地址
水位·链尾 LogicalAddress LowestVersionAddress { get; } 链尾/最老版本地址(头截断回收边界)
水位·版本号 long CurrentVersion { get; } 当前版本号(单调递增,0 = 空链/无数据)
扇区大小 uint SectorSize { get; } 引擎扇区大小(padding/对齐计算用)
头截断 void ReclaimOldVersions() 回收旧版本磁盘空间——保留最近 N=MaxMemoryVersions 个版本,更老的从链尾方向 ReclaimHead(epoch 保护:等 readers 退出后回收)
Opaque 写 void SetOpaqueMeta(ReadOnlySpan<byte> data) 登记外部 opaque meta 进策略缓冲,随下次水位提交原子落盘。Disabled 抛 InvalidOperationException;超 MetaOpaqueBytes 抛 ArgumentException
Opaque 读 ReadOnlySpan<byte> ReadOpaqueMeta() 读最近已提交块内的 opaque 字节视图。无数据/Disabled 时为空 Span
2PC 见下表 ITransactionParticipant 六件套

2PC 六件套(ITransactionParticipant,对齐 Log/Ring 范式,独立协议与数据写正交):

成员 语义
Prepare(long seq) / PrepareAsync(long seq, CancellationToken ct) 记录回退快照 → 追加新版本到磁盘链头 + flush + 写 meta。内容未变跳过追加。数据 flush 原生同步,异步版仅 meta 走 MetaPolicy.CommitAsync
ConfirmCommitted(long seq) CAS 推进 LastCommittedSeq + 持久化 meta(刷新水位)+ 清空 Abort 回退快照 + 触发回调。seq ≤ current 时 no-op
Abort(long seq) / AbortAsync(long seq, CancellationToken ct) 内存窗口回退到上一版本(零 IO)+ 尾截断 ReclaimTail 回退悬干新版本 + flush + 写 meta。幂等——恢复时可能对同一 seq 多次调
OnCommitted(long seq, Action callback) 注册提交回调(链式触发)。已提交到更高 seq 时立即同步触发
long LastCommittedSeq { get; } 当前已提交 seq(恢复/运行时读)
long LastPreparedSeq { get; } 最近 Prepare 的 seq。恢复裁决悬干用(> 协调者 committedSeq = 悬干,丢弃)

5. 自定义注入工厂

构造参数支持注入(默认实现满足绝大多数场景;替换走命名委托/接口注入,禁匿名 lambda):

注入项 接口/类型 默认实现 注入方式
Codec IMetadataCodec VersionedMetadata.Codec(私有嵌套 sealed,JIT 去虚化) 经 protected MetadataBase 构造第一参数——子类继承传
恢复算法 IRecovery<MetadataRecoveryHints> DefaultMetadataRecovery(三级回退:hints → meta → 扫盘) 构造参数 recovery
Meta 策略工厂 MetaPolicyFactory<MetadataMetaHeader, MetadataMetaPayload> CreateMetaPolicyDefault(按 MetaPolicyKind 映射 Managed/Transport/Disabled) 构造参数 metaPolicyFactory——命名委托,禁匿名 lambda
Meta 传输 IMetaTransport Transport 模式回落 MetaHost(meta 块作为 IS_META record 嵌入版本链流) 构造参数 metaTransport——3a 外部隔离用 MetadataMetaTransport 或自实现
Epoch LightEpoch 内部 new 自管(进 Resources 统一释放) 构造参数 epoch——多结构共享同一实例时注入
持久化策略 IPersistencePolicy 不注入 = 写路径不自动落盘(仅 Prepare/Persist 强制 flush) 构造参数 persistencePolicy——SyncPersistencePolicy / AsyncPersistencePolicy
Logger ILogger null 构造参数 logger

Contracts 类型(Structures/Metadata/Contracts/):

类型 角色
MetadataRecordFields 版本 record 业务字段包(Flags/PayloadLength/PaddingLength/PreviousVersion/MetadataVersion),codec 读写 header 时传参
MetadataMetaHeader meta 水位 Header(12B 纯规范:Magic/Version/Flags/PayloadLength/PaddingLength),走 [BinaryLayout] 源生成 codec
MetadataMetaPayload meta 水位 Payload(48B:HighestVersionAddress/LowestVersionAddress/LastCommittedSeq/LastPreparedSeq)
MetadataRecoveryHints 恢复提示(HighestVersionAddress? / LastCommittedSeq?),外部主动注入——最高优先级
IMetadataCodec 版本 record codec 接口(HeaderSize/Magic/WriteHeader/TryReadHeader/FillCrc/VerifyCrc/ReadVersion 等)
IPersistencePolicy / SyncPersistencePolicy / AsyncPersistencePolicy 落盘策略——见 §6