Table of Contents

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

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

2. Settings 全参数

基类 LogSettings(承 Settings)+ 各实现类 sealed 子类。Settings 基类字段被所有结构共享(meta 三策略、主引擎选项)。

2.1 通用字段(LogSettings + Settings)

字段 类型 默认 说明
LogPageSizeBits int 22(4MB) 页 = 攒批缓冲 + DIO 对齐提交单位。PageSize = 1 << LogPageSizeBits。单 entry 不跨页——单 entry 必须 ≤ PageSize,大对象由调用方分片成多条 entry。
MetaPolicyKind MetaPolicyKind Disabled meta 持久化策略:Disabled(无 meta)/ Managed(独立 meta 引擎)/ Transport(嵌入式 meta entry 写入 log 流,或注入 IMetaTransport 外部传输)。
MetaOpaqueBytes int 0 外部可写入 opaque 区容量(字节)。启动后不可改。只做写侧约束——不参与盘上布局(meta 块四段自描述)。
MainEngine StorageEngineOptions "tc.log" 主引擎选项(引擎名/段几何/预分配/关闭行为)。
Name string "tc.log" 存储引擎名。
PreallocateFile bool true 创建时预分配文件空间。
DeleteOnClose bool false 关闭时删除存储引擎。跨重启组合必须 false。

2.2 EntryLog 专属字段(EntryLogSettings)

字段 类型 默认 说明
CommitInterval TimeSpan 10ms 组提交时间阈值。0 = 每次 Append 立即提交;-1ms(InfiniteTimeSpan)= 禁用时间维度(攒页/手动提交场景)。
MaxUnflushedBytes long 64KB 组提交字节阈值。0 = 字节维度立即满足;long.MaxValue = 禁用字节维度。
MaxUnflushedCount int 1000 组提交条数阈值。0 = 条数维度立即满足;int.MaxValue = 禁用条数维度。

三维度阈值仅用于构造默认 GroupCommitPolicy(commitPolicy 参数为 null 时启用)。三场景靠阈值配置表达(无需枚举选模式):

场景 CommitInterval MaxUnflushedBytes MaxUnflushedCount 说明
典型 WAL(默认) 10ms 64KB 1000 三维度兜底,崩溃窗口 ≤10ms
单条强制 0 0 0 每次 Append 立即提交(宜配 PersistenceMode.WriteThrough)
手动/2PC -1ms long.MaxValue int.MaxValue 不自动提交,靠 CommitAsync / TransactionLog 驱动

2.3 DeltaLog 专属字段(DeltaLogSettings)

无额外专属配置。构造时 MetaPolicyKind 缺省强制为 Transport(嵌入式 meta——临时 delta 文件场景语义)。两个构造重载均如此;调用方初始化器仍可覆盖。


4. API 详表

4.1 写

方法 签名 说明
Append LogicalAddress Append(ReadOnlySpan<byte> payload) 同步追加单条 entry,返回起始地址。超单页抛 InvalidOperationException。热路径 non-virtual。
AppendAsync ValueTask<LogicalAddress> AppendAsync(ReadOnlyMemory<byte> payload, CancellationToken ct = default) 异步对等版。当前实现同步完成(写路径锁内完成;页满 IO 重叠让位于锁串行)。
BeginAppendBatch AppendBatch BeginAppendBatch() 开启批量追加(ref struct,using 包裹)。批持写锁(批内本地游标零锁;Dispose 释放)。
AppendBatch.Append LogicalAddress Append(ReadOnlySpan<byte> entry) 批内同步追加。页满让渡轨(异步刷盘、不阻塞写线程);双页都在途背压同步等。
AppendBatch.AppendAsync ValueTask<LogicalAddress> AppendAsync(ReadOnlySpan<byte> entry, CancellationToken ct = default) 批内异步追加。三档:页有空间=同步快路;页满无背压=让渡同步完成;双页在途=唯一真异步点(孤儿认领协议)。
Flush void Flush() 同步屏障:提交当前页(末页)+ engine.Flush(fsync 落盘)。不推进 CommittedOffset。
FlushAsync ValueTask FlushAsync(CancellationToken ct = default) 异步屏障——真异步:数据写在写锁外等待(屏障 IO 不占写锁)。
CommitAsync ValueTask CommitAsync(CancellationToken ct = default) 显式提交:flush 落盘 + 推进 CommittedOffset + meta.Commit。保证 §7 不变量 CommittedOffset ≤ FlushedTail。
WaitForCommitAsync ValueTask WaitForCommitAsync(LogicalAddress untilAddress, CancellationToken ct = default) 阻塞等待 CommittedOffset ≥ untilAddress。

4.2 读 / 扫描

方法 / 成员 签名 说明
OpenCursor ILogCursor OpenCursor(LogicalAddress startAddress = default, LogicalAddress endAddress = default, bool verifyCrc = false, SnapshotMode snapshotMode = Consistent, bool leasePages = false) 打开扫描游标——引擎 OpenSequentialReader + PageFrame 整页校验。默认 endAddress = FlushedTail(已落盘水位)。
Replay long Replay(LogicalAddress fromAddress, EntryReplayHandler handler, bool verifyCrc = false) 回调式重放已 commit entry(零装箱)。便捷重载 Replay(handler, verifyCrc)。
ReplayAsync ValueTask<long> ReplayAsync(LogicalAddress fromAddress, AsyncEntryReplayHandler handler, bool verifyCrc = false, CancellationToken ct = default) 异步对等版。
ILogCursor.MoveNext bool MoveNext() 同步推进到下一条 entry。
ILogCursor.MoveNextAsync ValueTask<bool> MoveNextAsync(CancellationToken ct = default) 异步推进。
ILogCursor.CurrentAddress LogicalAddress 当前 entry 起始地址。
ILogCursor.CurrentPayload ReadOnlySpan<byte> 当前 entry payload(零拷贝——指向读帧内)。非 lease 模式禁跨 MoveNext 持有。
ILogCursor.CurrentPayloadMemory ReadOnlyMemory<byte> Memory 视图。lease 模式有效至 Dispose;非 lease 禁跨 MoveNext。
ILogCursor.CurrentIsMeta bool 当前 entry 是否为 meta。

4.3 截断

方法 签名 说明
TruncatePrefix void TruncatePrefix(LogicalAddress address) 头截断:推进 BeginAddress 到 address。引擎 ReclaimHead 回收物理段。EntryLog retention 用。
TruncateSuffix bool TruncateSuffix(LogicalAddress address) 尾截断:回退 TailAddress 到 address。引擎 ReclaimTail + 页缓冲复位。EntryLog raft leader 切换用。返回 false = 地址无效。

4.4 水位

成员 签名 说明
BeginAddress LogicalAddress 起始地址 = engine.MinAddress(水位读引擎,Log 不自存)。
TailAddress LogicalAddress 当前写游标 = 最后一个已追加 entry 尾地址(含页缓冲内未落盘 entry)。
FlushedTail(internal) LogicalAddress 已落盘水位 = 最后一个已确认写完成 frame 的尾地址。游标扫描终点。
CommittedOffset(EntryLog) LogicalAddress 已 commit 的最高地址(commit 边界水位)。保证 ≤ FlushedTail。
LastCommitError(EntryLog) Exception? 最近一次提交错误。上层应周期查询以发现持久化失败。
LastCommittedSeq long 当前已提交序号(-1 = 未参与事务)。
LastPreparedSeq long 最近一次 Prepare 的 seq(恢复判定悬空事务用)。

4.5 2PC(ITransactionParticipant 六件套)

跨结构原子提交由 ITransactionParticipant 暴露,协调器 = Transactions/TransactionLog(写独立 commit record 文件驱动 Prepare/Confirm/Abort)。上层编排归 session.md。

方法 签名 说明
Prepare void Prepare(long seq) 事务准备:FlushUntil(tail) 数据落盘 + AppendMeta(tail) 写 meta(同一尾快照)。进入悬干状态——ConfirmCommitted 前崩溃恢复时丢弃。
PrepareAsync ValueTask PrepareAsync(long seq, CancellationToken ct) 异步对等版。
ConfirmCommitted void ConfirmCommitted(long seq) 确认提交:推进 LastCommittedSeq + 推进 _txRollbackTail + 触发 OnCommitted 回调。
Abort void Abort(long seq) 2PC 回滚:TruncateSuffix 回退到上一已确认提交边界,丢弃本轮悬干数据。守卫矩阵:seq ≤ LastCommittedSeq → no-op;陈旧 Abort → 仅复位记账;无既有提交边界 → 仅复位记账。
AbortAsync ValueTask AbortAsync(long seq, CancellationToken ct) 异步对等版。
OnCommitted void OnCommitted(long seq, Action callback) 注册 seq 的提交回调。已提交到更高 seq → 立即同步触发。

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

接口 / 类型 用途 内置实现
ILogCodec entry 头尾编解码——注入 LogBase 消除虚分发。HeaderSize(EntryLog=22B / DeltaLog=18B)/ Alignment(4B)/ MaxEntrySize(4MB)/ WriteHeader / TryReadHeader。 EntryLog.Codec / DeltaLog.Codec(均 internal sealed,构造期绑定)。
ICommitPolicy 提交策略——EntryLog group 提交引擎按策略判定"何时"触发提交(不决定"怎么"提交)。bool ShouldCommit(in CommitSnapshot)。 GroupCommitPolicy(internal 默认——三维度阈值兜底);恒提交/手动提交语义经自定义实现表达。
LogCursorFactory<out TLogCursor> 扫描游标工厂委托。参数:startAddress / endAddress / verifyCrc / snapshotMode(Consistent=快照隔离 / DirtyRead=游标锁)/ leasePages(true=换页不还池,CurrentPayloadMemory 有效至 Dispose)。 默认 PageFrameCursor(内嵌 LogBase.Cursor.cs)。
EntryReplayHandler / AsyncEntryReplayHandler 重放回调委托。参数:payload(零拷贝 Span)/ isMeta / entryAddress / ct。 —
ILogCursor 扫描游标接口(承 IStructureScanCursor)。CurrentAddress / EndAddress / CurrentPayload / CurrentPayloadMemory / CurrentEntryLength / CurrentIsMeta + MoveNext / MoveNextAsync。 PageFrameCursor(内嵌)。
LogMetaHeader meta 块规范头(12B,三段式 [Header 12B][Payload 80B+opaque][Crc32Footer 4B])。 —
LogMetaPayload meta payload(80B):BeginAddress / TailAddress / CommittedOffset / LastCommittedSeq / LastPreparedSeq / PreparedTailAddress(2PC Abort 回退点)。 —
CommitSnapshot 提交判定快照(喂给 ICommitPolicy):UnflushedBytes / UnflushedCount / SinceLastCommit。 —