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()+FireTransactionCallbacksAbort(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 |