Table of Contents

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

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

2. Settings 全参数

SnapshotSettings 继承 Settings(MainEngine / MetaPolicyKind / MetaOpaqueBytes 公共面),StreamSnapshotSettings / IncrementalSnapshotSettings 各自派生。两子类公共字段相同,差异在专属配置。

参数 来源 StreamSnapshot 默认 IncrementalSnapshot 默认
MainEngine Settings 基 ("tc.snapshot", 256MB, enableSegmentation=true, preallocateFile=false) ("tc.snapshot.inc", 256MB, enableSegmentation=true, preallocateFile=false)
Name Settings 基 "tc.snapshot" "tc.snapshot.inc"
PreallocateFile Settings 基 false(按需增长,GB/TB 流式不预分配) false
DeleteOnClose Settings 基 false(跨重启必须保留) false
MetaPolicyKind Settings 基 Disabled(默认不装 meta——纯流式可走 Backward 扫描兜底) Disabled(增量快照强烈建议设 Managed——段表靠 opaque meta 落盘)
MetaOpaqueBytes Settings 基 0 须 ≥ 段表容量 = 8 + 段数上限 × 40(如 64 段 → ≥2576B)
SessionBufferSize SnapshotSettings 128KB(双 buffer 写会话/读会话单 buffer 大小) 128KB
CompactSegmentThreshold IncrementalSnapshotSettings 专属 — 8(段数达此值自触发 CompactSegments——低频全量重写)

便捷构造(无参 new StreamSnapshotSettings() / new IncrementalSnapshotSettings())即用默认值;要自定义注入 StorageEngineOptions。meta 装配:IncrementalSnapshot 段表 = opaque meta 载体,禁用 meta = 段表丢失 → 恢复只能 Backward 扫描兜底(O(N) 全盘),生产场景请开 Managed。

4. API 详表

4.1 StreamSnapshot

API 签名 行为
OpenWrite StreamFrameWriter OpenWrite() 物理起点续接开新帧写入器;flush 回调推进双水位(逻辑按 data.Length 非对齐、物理按对齐长度)
OpenWriteRange StreamFrameWriter OpenWriteRange(LogicalAddress start, LogicalAddress end) 指定逻辑区间开帧(物理续接、逻辑不推进——逻辑↔物理由 checkpoint 二分换算)
OpenRead StreamFrameReader OpenRead() 从 _truncatedAddress 读到 _writeAddress(剩余可读 = 区间长度)
OpenReadRange StreamFrameReader OpenReadRange(LogicalAddress start, LogicalAddress end) 指定逻辑区间读
StreamFrameWriter
WriteAsync ValueTask WriteAsync(ReadOnlyMemory<byte> data, ct) 写一个 entry(首次自动加帧头;CRC64 增量累积;EntryCount+1)。快速路径同步完成
Write void Write(ReadOnlySpan<byte> data) 同步轨
CompleteAsync ValueTask CompleteAsync(ct) 写帧尾(FooterMagic + TotalLength + EntryCount + Crc64)+ flush + 重置(可开新帧)
Complete void Complete() 同步轨
DisposeAsync ValueTask DisposeAsync() 未 Complete 的帧自动闭环(仅 using 也安全)
TotalDataLength long 当前帧已写 data 字节数
EntryCount long 当前帧 entry 条数
StreamFrameReader
ReadDataAsync ValueTask<int> ReadDataAsync(Memory<byte> dest, ct) 读 data(EOF 返回 0,自动解析校验 footer CRC64)。帧头 magic 非法抛 IOException
ReadAllChunksAsync IAsyncEnumerable<ReadOnlyMemory<byte>> ReadAllChunksAsync(ct) 64KB chunk 流式枚举
IsFooterValid bool footer 是否已解析且 CRC 通过(读至 data 末尾自动解析)
EntryCount / TotalLength / StoredChecksum long/long/ulong footer 字段(解析前为 0)

写流程:OpenWrite → WriteAsync × N → CompleteAsync → using 自动 Dispose。多帧:CompleteAsync 后 ResetFrame 内部复位,可直接继续 WriteAsync 开新帧。

// StreamFrameWriter 写 + Complete(多帧)
await using var writer = stream.OpenWrite();

// 帧一:写 N 个 entry
foreach (var entry in entriesChunk1)
    await writer.WriteAsync(entry, ct);
await writer.CompleteAsync(ct);   // 帧尾落盘 + flush + ResetFrame(EntryCount 清零)

// 帧二:紧接再写(首 WriteAsync 自动加新帧头)
await writer.WriteAsync(someEntry, ct);
await writer.CompleteAsync(ct);
// DisposeAsync 等价 CompleteAsync(若忘记 Complete 也安全闭环)

// 读回:校验 footer CRC64
await using var reader = stream.OpenRead();
var buf = new byte[64 * 1024];
int n;
while ((n = await reader.ReadDataAsync(buf, ct)) > 0)
    Consume(buf.AsSpan(0, n));
if (!reader.IsFooterValid) throw new InvalidDataException("帧 CRC 校验失败");

4.2 IncrementalSnapshot

API 签名 行为
AppendSegmentAsync ValueTask<long> AppendSegmentAsync(long n0, IAsyncEnumerable<ReadOnlyMemory<byte>> chunks, ct) 追加段:[Header 14B][N₀ 8B][chunks][Footer 28B] 一帧 → 2PC 提交 → 段表注册(追加)+ meta 原子落盘。返回 n0。段数达阈值自触发合并。单写者——并发/重入抛 InvalidOperationException
ImportSegmentAsync ValueTask<long> ImportSegmentAsync(long n0, IAsyncEnumerable<ReadOnlyMemory<byte>> chunks, ct) 替换段(raft 快照安装语义):写完整镜像段 → 段表替换为单段(旧段物理回收)。chunk 流异常 = Abort 回滚——新段清除、旧快照完好
ReadAllChunksAsync IAsyncEnumerable<ReadOnlyMemory<byte>> ReadAllChunksAsync(ct) 顺序流式读全部段(跳过每段 N₀ 前缀)= 最新快照条目流。段级 CRC64 校验失败抛 InvalidDataException
ReadSegmentDataAsync IAsyncEnumerable<ReadOnlyMemory<byte>> ReadSegmentDataAsync(int index, ct) 段 i 的数据流(测试/诊断用;越界抛)
CompactSegmentsAsync ValueTask CompactSegmentsAsync(ct) 合并全部段为新基线段(读全段拼接 → 写新帧 → 截旧段 → 段表=单段 + meta 落盘)。低频——成本 = 一次全量写
ClearAsync ValueTask ClearAsync(ct) 清空全部段(截断全量 + 段表空 + meta 落盘)
SegmentCount int 段数(内存段表,含最新段)
LatestN0 long 最新段覆盖点 N₀(无段=0)
GetSegmentN0 long GetSegmentN0(int index) 段 i 的 N₀(单调递增;越界抛)

段格式:[Header 14B][N₀ 8B][chunks...][Footer 28B]。N₀ = 段自描述覆盖点(raft apply 序号),独立读一段可知其覆盖点。段表(opaque meta 载体)= [count 4B][pad 4B][条目 40B × N],每条目 = LogicalStart 16B + PhysStart 16B + N₀ 8B。

段表恢复 + 阈值合并示例:

// 追加段(raft 快照:n0 = apply 序号)
await inc.AppendSegmentAsync(applyIndex, ProduceChunksAsync(ct), ct);
// 段数 ≥ CompactSegmentThreshold(默认8) → 自触发 CompactSegmentsCoreAsync
//   合并 = 一次全量重写为新基线段(覆盖点 N₀ 不变)+ 旧段物理回收 + 段表=单段 + meta 落盘

// raft 快照安装(替换语义):导入完整镜像段,段表替换为单段
await inc.ImportSegmentAsync(applyIndex, ProduceFullImageAsync(ct), ct);

// 恢复后读最新快照(段表驱动逐段顺序拼接)
await foreach (var chunk in inc.ReadAllChunksAsync(ct))
    Consume(chunk);
// 段级帧 CRC64 失败抛 InvalidDataException

// 显式合并(不依赖阈值)
await inc.CompactSegmentsAsync(ct);

单写者契约:AppendSegmentAsync / ImportSegmentAsync / CompactSegmentsAsync / ClearAsync 互斥(_writing 0/1 闸门);并发/重入抛 InvalidOperationException。raft 快照低频串行天然契合。多生产者场景须外部队列汇聚。

4.3 共有(SnapshotBase)

API 签名 行为
三水位
WriteAddress ref LogicalAddress 逻辑写尾(非对齐)
PhysicalWriteAddress ref LogicalAddress 物理写尾(扇区对齐,DIO 写基准)
TruncatedAddress ref LogicalAddress 逻辑截断点(头截断推进)
Size long 流大小 = WriteAddress - TruncatedAddress
写
Append / AppendAsync void Append(ReadOnlySpan<byte>) / ValueTask AppendAsync(ReadOnlyMemory<byte>, ct) append(可回滚——双水位推进;空数据 no-op)
Overwrite / OverwriteAsync void Overwrite(LogicalAddress, ReadOnlySpan<byte>) / ... 不可回滚——原位覆写破坏旧数据,2PC 不覆盖
截断(按字节)
TruncatePrefix void TruncatePrefix(LogicalAddress address) 头截断(业务调,回收已读头部)+ 推进 TruncatedAddress
TruncateSuffix void TruncateSuffix(LogicalAddress address) 尾截断(2PC Abort 内部)+ 写窗口作废
ReclaimRange void ReclaimRange(LogicalAddress? from, LogicalAddress? to) 区间 PunchHole
2PC(ITransactionParticipant)
Prepare / PrepareAsync void Prepare(long seq) flush + meta.Commit(记 LastPreparedSeq + 水位)
ConfirmCommitted void ConfirmCommitted(long seq) CAS 推进 LastCommittedSeq + 推进 CommittedWriteAddress(Abort 回退点)
Abort / AbortAsync void Abort(long seq) TruncateSuffix(CommittedWriteAddress) 回滚 append 部分(Overwrite 不可回滚)
OnCommitted void OnCommitted(long seq, Action callback) 注册提交回调(已提交到更高 seq 立即同步触发)
meta opaque
SetOpaqueMeta void SetOpaqueMeta(ReadOnlySpan<byte> data) 登记外部 opaque(随下次水位提交原子落盘)。Disabled 抛 InvalidOperationException;超 MetaOpaqueBytes 抛 ArgumentException
ReadOpaqueMeta ReadOnlySpan<byte> ReadOpaqueMeta() 读最近已提交 opaque(无/禁用 = 空)
地址算术
AdvanceAddress LogicalAddress AdvanceAddress(LogicalAddress addr, long delta) 段感知地址推进/回退
Distance long Distance(LogicalAddress from, LogicalAddress to) 段感知两地址间字节距离
SectorSize int 设备扇区大小
DioAlignment int(protected) max(SectorSize, 4096)——保证 DIO 兼容

4.4 2PC 编排(跨结构原子性)

SnapshotBase 实现 ITransactionParticipant——可参与 Transactions/TransactionLog 协调器驱动的跨结构原子性(详见 session.md)。Snapshot 侧的 2PC 语义:

  • Prepare(seq):_engine.Flush() + 记 LastPreparedSeq + WriteMeta()(meta 落盘 prepared 水位——悬干状态)
  • ConfirmCommitted(seq):CAS 推进 LastCommittedSeq + 推进 CommittedWriteAddress(Abort 回退基准)+ WriteMeta() + FireTransactionCallbacks
  • Abort(seq):TruncateSuffix(CommittedWriteAddress) 回滚 append 部分(Overwrite 不可回滚)+ WriteMeta()
  • OnCommitted(seq, callback):注册回调(已提交到更高 seq 立即同步触发——链式触发)
// Snapshot 单独走 2PC(IncrementalSnapshot 内部即用——段写事务)
long seq = 1;
stream.Prepare(seq);              // flush + meta 记 prepared
stream.ConfirmCommitted(seq);     // CAS 推进 committed + CommittedWriteAddress 推进
// 后续 Abort(seq-1) 不影响;CommittedWriteAddress 是新的回退基准

// 异常路径
stream.Abort(seq);   // TruncateSuffix(CommittedWriteAddress)——append 部分回滚,Overwrite 不回滚

IncrementalSnapshot.AppendSegmentAsync 内部即走 2PC:Prepare(seq) → ConfirmCommitted(seq) → 段表注册 + meta 落盘;chunk 流异常 = Abort(seq)——尾截断回滚(新段物理清除,旧段完好)。这是会话模式一致性核心(详见 session.md)。

5. 自定义注入工厂

SnapshotBase 构造接受三个可选注入参数;子类(StreamSnapshot/IncrementalSnapshot)转发到基类构造。

注入点 类型 用途
recovery IRecovery<SnapshotRecoveryHints>? 恢复算法实例(默认走 CreateRecovery() 工厂——StreamSnapshot=DefaultSnapshotRecovery、IncrementalSnapshot=IncrementalRecovery)。注入实例则跳过工厂
metaPolicyFactory MetaPolicyFactory<SnapshotMetaHeader, SnapshotMetaPayload>? meta 策略工厂委托(MetaPolicyKind → IMetaPolicy);默认走 CreateMetaPolicyDefault——Managed/Transport/Disabled 三选一。自定义注入可替换 Managed 实现
metaTransport IMetaTransport? Transport 模式的传输实例(默认回落到内嵌 MetaHost——meta 块作为 IS_META 帧追加进快照流)
Contracts
ISnapshotCodec internal sealed StreamFrameCodec 流式帧 codec——Header/Footer 读写、magic 校验。两子类共用同一实例(构造期 new StreamFrameCodec() 注入基类)
ISnapshotWriteSession IDisposable, IAsyncDisposable 双 buffer flush 流水线写会话——WriteAsync/Write/WriteSmall/FlushIfFullAsync/FlushAsync/OnFlushed 事件
ISnapshotReadSession IAsyncDisposable 双 buffer 异步预读读会话——ReadAsync/LogicalStart/LogicalEnd/PhysicalEnd(物理/逻辑偏移分离)
SnapshotMetaHeader 12B struct meta 三段式 header(MagicValue/Version/Flags/PayloadLength/PaddingLength)
SnapshotMetaPayload 80B struct meta payload(三水位 + CommittedWriteAddress + LastCommittedSeq/LastPreparedSeq)
SnapshotRecoveryHints readonly struct 恢复提示(WriteAddress?/PhysicalWriteAddress?)——上层注入已知水位,优先于扫盘
SnapshotRecordFields readonly record struct 帧字段包(Header: Flags/PayloadLength/PaddingLength;Footer: TotalLength/EntryCount)
StreamFrameCodec internal sealed ISnapshotCodec 默认实现——两子类共用
ITransactionParticipant 接口 SnapshotBase 实现——2PC 协调器(Transactions/TransactionLog)驱动跨结构原子性,详见 session.md