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 协调器编排 |