Table of Contents

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

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

2. Settings 全参数

读 MirrorSettings.cs + Settings.cs 基类。两子类配置项差异:PagedMirrorSettings 增 LogPageSizeBits,WholeMirrorSettings 无专属字段。

参数 类型 WholeMirror 默认 PagedMirror 默认 说明
MainEngine StorageEngineOptions 单段稀疏(enableSegmentation=false, preallocateFile=false, segmentGrowthLimit=64MB) 同左 Mirror 版本链是单段追加流——分段默认关,稀疏按需增长
Name string "tc.mirror" "tc.mirror" 引擎名(便捷构造默认值)
PreallocateFile bool false false 创建时不预分配文件
DeleteOnClose bool false false 跨重启组合必须 false(否则恢复时真相源被清)
MetaPolicyKind MetaPolicyKind Disabled Disabled meta 持久化策略;Managed 起独立 meta 引擎,Transport 嵌入主流,Disabled 不持久化水位
MetaOpaqueBytes int 0 0 外部 opaque 容量;启动后不可改
LogPageSizeBits int — 22(PageSize=4MB) 仅 PagedMirror;PageSize = 1 << LogPageSizeBits,与源结构页对齐

N=2 轮替是固定策略(保留当前 + 上一 checkpoint),不设配置项。段增长上限 DefaultSegmentGrowthLimit = 64MB 是 const 常量。

便捷构造(推荐起点):

var wholeSettings   = new WholeMirrorSettings();                                   // 默认单段稀疏
var pagedSettings   = new PagedMirrorSettings { LogPageSizeBits = 12 };            // PageSize=4096(测试轻量)

完整构造(自定义段几何 / hints / 清理策略):

var settings = new WholeMirrorSettings(
    new StorageEngineOptions("kv.mirror", 64L << 20, enableSegmentation: false)
        .WithDeleteOnClose(false))
{
    MetaPolicyKind   = MetaPolicyKind.Managed,
    MetaOpaqueBytes  = 256,
};

4. API 详表

Mirror 子族 API 按形态分三组:WholeMirror 三拍会话 / PagedMirror 逐页写读 / 共有 2PC 六件套。所有 API 同步执行(引擎 IO 同步原生);异步轨 PrepareAsync / AbortAsync 实质等价同步(引擎 flush/截断原生仅同步)。

4.1 WholeMirror——三拍会话 + 读门面

API 签名 行为
BeginSession LogicalAddress BeginSession() 分配会话版本号 + 帧三拍之一(圈头区 + 写瘦头——不预留、不知尺寸)。返回帧头地址(调用方持有,用于后续读 / 定位)
AppendChunk void AppendChunk(ReadOnlySpan<byte> chunk) 帧三拍之二:顺序追加 payload chunk(圈地 + 复写 + CRC64 边写边累积——零缓冲不驻内存)。单线程契约:逐段追加
EndSession LogicalAddress EndSession() 帧三拍之三:CRC 收官落尾 + _engine.Flush()。返回帧尾末地址。帧保持 pending 直到 ConfirmCommitted / Abort
ReadChunk int ReadChunk(LogicalAddress frameHead, long offsetInPayload, Span<byte> dst) 按 payload 偏移读切片(拷贝交付)。返回实际读取字节数
GetFrameInfo MirrorFrameInfo? GetFrameInfo(LogicalAddress frameHead) 帧几何账目(payload 长 = 尾位 − 头 − 头结构——零长度字段,长度是推导的事实)
GetPayloadLength long GetPayloadLength(LogicalAddress frameHead) 帧 payload 长度(推导)。无有效帧尾返回 0
Verify bool Verify(LogicalAddress frameHead) 流式分段重读重算 CRC(头 + 体 + 尾前缀 对 尾 Crc 字段——大帧不驻内存)

三拍契约:BeginSession → AppendChunk × N → EndSession 必须同一线程顺序执行;EndSession 之后才能开下一个会话(否则抛"上一帧未收官")。EndSession 只 flush 数据,不推进 LastCommittedSeq——2PC 提交点走 ConfirmCommitted。

三拍会话完整示例——大镜像零缓冲流式写:

using var mirror = new WholeMirror(fs, new WholeMirrorSettings());
mirror.Initialize();
mirror.WaitForReady();

// 任意总长——边写边知,EndSession 时才完成 CRC 收官
const long TotalSize = 10000;
var data = new byte[TotalSize];
Array.Fill(data, 0xAB);

var frameHead = mirror.BeginSession();                    // 帧三拍之一:圈头 + 写瘦头
mirror.AppendChunk(data.AsSpan(0, 6000));                 // 帧三拍之二:追加任意段
mirror.AppendChunk(data.AsSpan(6000));                    // 继续追加(无需告知总长)
var frameEnd = mirror.EndSession();                       // 帧三拍之三:CRC 落尾 + flush

// 几何推导(零长度字段)+ CRC 流式验证
mirror.GetPayloadLength(frameHead).Should().Be(TotalSize, "像长 = 尾位 − 头 − 头结构(推导)");
mirror.Verify(frameHead).Should().BeTrue("写后 CRC64 应一致");

// 按 payload 偏移读切片(拷贝交付,跨 await 也安全)
var dst = new byte[TotalSize];
int n = mirror.ReadChunk(frameHead, 0, dst);
// n == TotalSize;dst 与 data 逐字节相等

说明:

  • BeginSession 不知镜像总尺寸即可圈头——CRC64 边写边累积,EndSession 收官落尾时才需要全帧一致;大镜像(GB 级)零缓冲不驻内存。
  • EndSession 后帧仍 pending(未裁决);走 2PC 时由 ConfirmCommitted / Abort 决定最终可见性。不走 2PC 的单 checkpoint 用法,EndSession 后即可读(committed 链头仍按 HighestVersionAddress 取)。
  • 读侧 ReadChunk 拷贝交付——跨 await / 跨线程消费合法;零拷贝形态请用 Ring 的 GetValueSpan(同栈内合法,详见 ring.md)。

4.2 PagedMirror——逐页写读

API 签名 行为
WritePage LogicalAddress WritePage(long page, long startPage, ReadOnlySpan<byte> pageBytes, long logicalAddress = 0) 写一页(追加该页版本链新帧)。首个写入自动开启 checkpoint 会话。pageBytes > PageSize 截断;< PageSize 记 FLAG_LAST_PARTIAL。返回帧头地址
ReadPage (int bytesRead, bool isValid) ReadPage(long page, long startPage, Span<byte> dest) 读该页 committed 链头:帧几何推导 payload 长 → 读 payload → 全帧 CRC32C 验证。无该页 / 空链 / 帧损毁返回 (0, false)
PageSize int PageSize(只读) 1 << LogPageSizeBits

多链语义:page 是 per-page 链键(独立链头 + 第二新)。startPage 是会话起始页(语义锚点,不参与寻址)。可乱序:会话内 WritePage(2, ...) → WritePage(0, ...) → WritePage(1, ...) 合法,多链互不影响。会话内每页首写记录 previous = Invalid(链尾哨兵——Empty 是合法 seg0@0,不能当哨兵)。

逐页写读示例——乱序写 + 多链原子提交:

using var mirror = new PagedMirror(fs, new PagedMirrorSettings { LogPageSizeBits = 12 });
mirror.Initialize();
mirror.WaitForReady();

// 乱序写三页——多链互不影响;首写自动开启 checkpoint 会话
byte[] fills = [0x00, 0x11, 0x22];
mirror.WritePage(2, 0, MakePage(4096, fills[2]), logicalAddress: 200);
mirror.WritePage(0, 0, MakePage(4096, fills[0]), logicalAddress: 0);
mirror.WritePage(1, 0, MakePage(4096, fills[1]), logicalAddress: 100);
mirror.Prepare(seq: 1);                  // 多链整体 Prepare(数据 flush + meta 落盘)
mirror.ConfirmCommitted(seq: 1);          // 多链整体 Confirm(逐页链头推进)

// 每页读自己链头——乱序写不影响读
for (byte p = 0; p < 3; p++)
{
    var dst = new byte[4096];
    var (n, valid) = mirror.ReadPage(p, 0, dst);
    // n == 4096;valid == true;dst[0] == fills[p]
}

末页短 payload:pageBytes.Length < PageSize 时 codec 自动置 FLAG_LAST_PARTIAL,ReadPage 返回实际字节数(不补齐),调用方按 (bytesRead, isValid) 处理。

4.3 共有——水位 / 版本号 / 2PC 六件套

API 签名 行为
Prepare void Prepare(long seq) 2PC Prepare:_engine.Flush() + WriteMeta()(记录 LastPreparedSeq + 悬干水位)。数据 fsync 先于 meta fsync——断电时 meta 绝不标记 data 未落盘的 commit 点
PrepareAsync ValueTask PrepareAsync(long seq, CancellationToken ct) Prepare 异步轨(实质同步完成)
ConfirmCommitted void ConfirmCommitted(long seq) CAS 推进 LastCommittedSeq + 推进链头(子类 OnConfirmSession)+ N=2 立即头截断回收最老 + 刷新 meta + 触发回调。seq ≤ current 时 no-op
Abort void Abort(long seq) 尾截断回退悬干新 checkpoint:物理丢弃 [_committedChainEnd, AllocatedTail) + 回退会话链头状态 + meta。seq ≤ LastAbortedSeq 时幂等 no-op
AbortAsync ValueTask AbortAsync(long seq, CancellationToken ct) Abort 异步轨
OnCommitted void OnCommitted(long seq, Action callback) 注册提交回调(已提交到更高 seq 时立即同步触发;锁外触发避免死锁)
ReclaimOldVersions void ReclaimOldVersions() N=2 头截断显式入口(ConfirmCommitted 自动调;业务也可显式调)。保留窗口由子类 ComputeRetainFloor 决定
((ITransactionParticipant)mirror).LastCommittedSeq long 已提交 seq(Volatile.Read)
((ITransactionParticipant)mirror).LastPreparedSeq long 已 Prepare seq(Volatile.Read)

Abort 语义 = 丢弃未确认会话:会话 active 才回退;committed 链头未被会话触碰(只清 pending,不碰 committed);尾截断物理丢弃悬干(引擎退化 AllocatedTail);LastPreparedSeq 回退到 LastCommittedSeq。


5. 自定义注入工厂(Contracts)

契约 / 类型 用途 注入通道
IMirrorCodec 帧格式 codec(Header/Footer 读写 + magic/CRC 模式校验 + 链拓扑声明) 构造期由子类自带(WholeMirror.Codec / PagedMirror.Codec),不暴露注入——格式固定
MirrorMetaHeader meta 水位 Header(12B 纯规范:magic "MMHD" + version + flags + payload 长度段) 经 MetaPolicyFactory<MirrorMetaHeader, MirrorMetaPayload> 注入策略
MirrorMetaPayload meta 水位 Payload(48B:版本链两端 + LastCommittedSeq + LastPreparedSeq) 同上
MirrorFrameHeader 帧头(32B:magic + version + flags + PageId + LogicalAddress + MirrorVersion) 不注入——盘上格式
MirrorFrameFooter 帧尾(40B:magic + version + flags + PreviousVersion + MirrorVersion + Crc) 不注入——盘上格式
MirrorFrameInfo 帧几何账目值类型(head→footer 对 + 头尾字段快照) 读 API 返回
MirrorRecoveryHints 恢复提示(HighestVersionAddress? + LastCommittedSeq?) Initialize(hints) 注入;优先级最高(高于 meta、扫盘)
MetaPolicyFactory<MirrorMetaHeader, MirrorMetaPayload> meta 策略工厂委托 构造参数 metaPolicyFactory——默认按 MetaPolicyKind 内联三模式(Managed/Transport/Disabled)
IMetaTransport Transport 模式的 meta 传输 构造参数 metaTransport——未注入回落到内部 MetaHost(嵌入主流的 IS_META 帧)
IRecovery<MirrorRecoveryHints> 恢复算法实例 构造参数 recovery——默认 DefaultMirrorRecovery(基类内置)
ITransactionParticipant 2PC 六件套(Prepare/ConfirmCommitted/OnCommitted/Abort/LastCommittedSeq/LastPreparedSeq) MirrorBase 实现此接口,经 TransactionLog 协调器编排