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 |