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。 |
— |