Table of Contents

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

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

2. Settings 全参数

BlittableRingSettings 是 RingSettings 的 sealed 派生——无额外字段(key 长度由 TKey 类型参数提供 sizeof(TKey))。所有可配置项在基类 RingSettings。

参数 默认 说明
PageSize AlignmentConst.Alignment32M 页大小(字节)。校验:2 的幂 / [4KB, 1GB]。DIO 对齐契约下限
MemorySize AlignmentConst.Alignment16G 总内存容量(字节)。校验:≥ PageSize 且整除为 2 的幂页数。PageCount = MemorySize/PageSize 是派生量,不在 Settings 直配
MaxPageCount 8192 页数上界。页数过多(PageSize 太小)扫描/驱逐开销随页数线性增长,校验时拒绝
MutableFraction 0.9 mutable 区占比 (0,1) 开区间。决定 mutable→readonly 转换点(ReadOnlyLag = MutableFraction × (PageCount-1) × PageSize)
Preallocate false 构造时是否全量预分配所有页(false = 懒分配,按需 Allocate)
OverflowPolicy Disabled 溢出策略(WiscKey 式 KV 分离)。Disabled=Value 内联主 record;Enabled=Value > MinOverflowSize 时分离到溢出引擎
MinOverflowSize 0 Value 溢出阈值(字节)。Enabled 时 0 = 全部溢出
ClockCacheCapacity null 冷页缓存槽位。null=按 ColdReadRatio 派生(默认);显式设置覆盖 ratio,向上取整到 2 的幂
ColdReadRatio 0.25 冷回源比例 [0.0, 1.0]。0.0=不缓存(每次冷读走设备);1.0=缓存全部页(近乎全热)
ColdRecordBufferLimit AlignmentConst.Alignment1M 单条 record 部分页回源的 buffer 上限。超过此值时回退到整页路径(LoadColdPage)。校验:须 ≥ HeaderSize
MainEngine — StorageEngineOptions,主引擎配置(引擎名 / 段大小 / 预分配 / 删 onClose / DirectIo / Hints 等)。构造时直传
MetaPolicyKind — meta 策略模式(Managed / Transport / Disabled)。Managed=独立 meta 引擎;Transport=外部传输(未注入回落 MetaHost 嵌入 ring 流);Disabled=不持久化(opaque 拒写)
MetaOpaqueBytes 256 opaque 槽字节数(结构级缺省;初始化器可覆盖)。上限受 IMetaPolicy 容量约束

构造校验(fail-fast,RingBase.Validate——源码 Structures/Ring/RingBase.cs):

  1. PageSize 是 2 的幂 / [4KB, 1GB]
  2. MemorySize ≥ PageSize 且整除为 2 的幂页数
  3. PageCount ≤ MaxPageCount
  4. SegmentGrowthLimit ≥ PageSize
  5. MutableFraction ∈ (0,1) 开区间
  6. ColdRecordBufferLimit ≥ HeaderSize

4. API 详表(按功能分组)

4.1 写

方法签名 用途
LogicalAddress Write(TKey key, ReadOnlySpan<byte> value) 公开写入。大 value 自动溢出(按 OverflowPolicy)。永不返回 Empty
LogicalAddress Write(TKey key, ReadOnlySpan<byte> prefix, ReadOnlySpan<byte> value) 分段写入(免临时数组拼接);Overflow=Enabled 时超阈值抛——用连续 value 的 Write/WriteAsync
LogicalAddress WriteTombstone(TKey key) 写墓碑(FLAG_RINGRECORD_TOMBSTONE + 空 value);恢复时 RecordKey.IsTombstone 过滤
ValueTask<LogicalAddress> WriteAsync(TKey key, ReadOnlyMemory<byte> value, CancellationToken ct = default) 公开异步写。inline 快路径同步完成(零 async 开销);溢出慢路径真异步
ValueTask<LogicalAddress> WriteTombstoneAsync(TKey key, CancellationToken ct = default) 异步墓碑写(同步完成)
void UpdateValue(LogicalAddress addr, ReadOnlySpan<byte> newValue) RCU 原地更新。四分支翻转:overflow→overflow/inline→overflow/overflow→inline(受原 inline 槽容量约束,超抛)/inline→inline
ValueTask UpdateValueAsync(LogicalAddress addr, ReadOnlyMemory<byte> newValue, CancellationToken ct = default) 异步版。纯 inline 翻转同步完成;溢出翻转走 WriteOverflowAsync
WriteBatch BeginWriteBatch() 批量写(ref struct,using 包裹)。多写者各持独占窗口段,批内无锁推进;详见 §4.6

WriteBatch.Append 签名:

LogicalAddress Append(TKey key, ReadOnlySpan<byte> value);
LogicalAddress Append(TKey key, scoped ReadOnlySpan<byte> prefix, scoped ReadOnlySpan<byte> value);

同一 WriteBatch 不可并发调用;不同批各持窗口可并发。Dispose 释放 epoch。

4.2 读(内容自愈读)

判据 = SafeSnapshotTail(addr < 水位 → 页池直读;≥ → 设备读 / 自愈回退)。热直读经 magic + CRC 校验,失败自动回退设备重读——驱逐复用/撕裂/残留不产生假数据(读到设备权威快照或空/NotFound,由上层定夺)。

方法签名 返回 / 语义
int GetValue(LogicalAddress addr, Span<byte> destination) 拷贝交付;0 = 无有效记录(未命中/墓碑/校验失败)
bool TryGetValue(LogicalAddress addr, Span<byte> destination, out int written) 拷贝交付;false = 未命中/墓碑/校验失败。跨 await 消费必须走此形态
ReadOnlySpan<byte> GetValueSpan(LogicalAddress addr) 零拷贝切片——仅同步栈内合法。空 span = 无有效记录。溢出 record 回退 thread-static 缓冲拷贝
RecordKey<TKey> GetKey(LogicalAddress addr) 拉到 key(+ value 长度 + flags + 地址)。无有效记录抛 InvalidOperationException(fail-fast)
bool TryGetKey(LogicalAddress addr, out TKey key) 读 key 的 NotFound 形态。false = 无有效记录
ValueTask<RecordKey<TKey>> GetKeyAsync(LogicalAddress addr, CancellationToken ct = default) 异步单条 key 读;热区同步快路径,冷区真异步整页回源
ValueTask<int> GetValueAsync(LogicalAddress addr, Memory<byte> destination, CancellationToken ct = default) 异步 value 拷贝读;溢出走 ReadOverflowAsync
ValueTask<(TKey Key, bool Success)> TryGetKeyAsync(LogicalAddress addr, CancellationToken ct = default) 异步 key 读的 NotFound 形态
void GetRecords<THandler>(ReadOnlySpan<LogicalAddress> addresses, THandler handler) where THandler : IReadOnlyRecordHandler<TKey> 批量读(按页号聚簇,减少冷区回源次数)。无有效记录的地址跳过(不回调 handler.Handle)
RingRecordFields GetFields(LogicalAddress addr) 读 record header 字段(轻量)
Span<byte> GetSpan(LogicalAddress addr, int length) 不暴露 byte*,页池 native 内存可写窗口。调用方保证页未驱逐回收
void EnterEpoch() / void ExitEpoch() epoch 读保护协议实现(IEpochProtected)。读路径已退役——读安全性由内容自愈读不变式承担;写/驱逐 drain 仍使用
long GetByteDistance(LogicalAddress from, LogicalAddress to) 公开字节距离(队列积压/滞后 lag 度量原语)

4.3 水位(全列——8 个逻辑水位;7 个入 CAS128 原子块,tail 锁内推进)

水位 含义 持久化层
BeginAddress 头截断边界(= engine.MinAddress,此地址前数据已回收) 持久化层(meta 必存)
FlushedUntilAddress 落盘边界(此地址前已写引擎,恢复可信数据上限 W) 持久化层(meta 必存)
SafeReadOnlyAddress 安全只读水位——epoch 保护下 readonly 区推进目标(读者可安全读至此处) 持久化层(meta 必存)
ReadOnlyAddress 只读水位——此地址前页面冻结(等待 flush 后驱逐) 持久化层(meta 必存)
TailAddress 写游标——下一条 record 的分配地址(TryAllocate 单调推进)。★ 唯一不入 CAS128 块的水位——分配热路径 _tailLock 锁内推进 持久化层(meta 必存)
HeadAddress 驱逐边界——此地址前的旧页已被回收(head 随 flush/驱逐推进) 内存水位层(永不落盘——RingMetaPayload 无此槽;恢复时从 BeginAddress 重建)
SafeHeadAddress 安全驱逐边界(epoch 保护下的驱逐推进目标) 内存水位层
ClosedUntilAddress 关页边界——此地址前的页已关闭(新写入不得落在其前) 内存簿记层(永不落盘,恢复时初始化为 SafeHeadAddress)

CAS128 块成员 = Begin / FlushedUntil / SafeReadOnly / ReadOnly / Head / SafeHead / ClosedUntil(7 个, RingBase.Watermarks 基座);TailAddress 分配热路径锁内推进(_tailLock)。

辅助:TakeSafeSnapshotTail()(lock 内采集——之前全部 header 完整可见,扫描游标构造快照 + 读路径热冷分档判据)。8B 距离水位 _safeSnapshotTailDist/_headDist 经 Interlocked CAS-max 发布 / Volatile 读,热路径无锁无撕裂。

4.4 截断

方法签名 语义
void TruncatePrefix(LogicalAddress address, bool truncateDevice = false) 头截断——推进 BeginAddress。前置:address ≤ FlushedUntilAddress(否则抛——未落盘数据会丢)。truncateDevice=true 调 engine.ReclaimHead(失败不阻断逻辑截断)
void TruncateSuffix(LogicalAddress address) 尾截断——D2 决策唯一异常路径(放松"地址单调不回退"铁律)。回退四件套:物理回收(engine.ReclaimTail)+ 内存水位条件回退(各字段独立判断)+ 页池清零 + 冷缓存失效。守卫:address 不得落入已驱逐区(< SafeHeadAddress)

4.5 快照

方法签名 语义
IRingSnapshotReader OpenSnapshotReader(LogicalAddress begin = default, LogicalAddress end = default) 创建快照读取器(pull 模式)。默认区间 [BeginAddress, TailAddress)。冷热透明分流(FlushedUntilAddress 判据)
IRingSnapshotWriter OpenSnapshotWriter(LogicalAddress begin, LogicalAddress end) 创建快照写入器(push 模式)。begin..end 超出当前 AllocatedTail 时先整段预留 Allocate。填完所有数据须调 Complete 推进 TailAddress 到 end

IRingSnapshotReader:long Length / int Read(Span<byte> buf) / ValueTask<int> ReadAsync(Memory<byte> buf, CancellationToken ct),页级流式支持 GB/TB。 IRingSnapshotWriter:void Write(ReadOnlySpan<byte> buf) / ValueTask WriteAsync(ReadOnlyMemory<byte> buf, CancellationToken ct) / void Complete() / ValueTask CompleteAsync(CancellationToken ct)。

4.6 批量写

BeginWriteBatch() 返回 ref struct WriteBatch(using 包裹)。窗口模型:每个批 = 独占页段窗口——领取时在 _tailLock 内把 tail 一次性推进到窗口尾(预留段,批独占);批内 record 分配完全无锁(页内游标推进,零锁零 EnsureSpace)。多写者各持窗口并发写——锁竞争从"每 record 一次"降到"每窗口一次"。

4.7 扫描

方法签名 语义
IRingScanCursor OpenScanCursor(LogicalAddress begin = default, LogicalAddress end = default) 打开扫描游标(默认区间 [BeginAddress, TailAddress);工厂注入或默认 SequentialRingScanCursor)。整段持 epoch
IAsyncEnumerable<(TKey Key, LogicalAddress Address, bool IsTombstone)> ScanAsync(LogicalAddress begin, LogicalAddress end, CancellationToken ct = default) 范围扫描异步迭代器(包装 OpenScanCursor,冷区真异步 IO)。仅吐用户数据 record(过滤 FLAG_ENTRY_IS_META);墓碑旗标随三元组吐出
IAsyncEnumerable<(TKey Key, LogicalAddress Address, bool IsTombstone)> ScanAsync(CancellationToken ct = default) 全量扫描(BeginAddress 到 TailAddress)
long SpanPages(LogicalAddress from, LogicalAddress to) 两地址间页跨度(P1 扫描模式选择器成本模型输入)
LogicalAddress GetFlushedWatermark() IKeyResolver 契约——派生结构后台持久化的 footer 锚点 W(= FlushedUntilAddress)

4.8 2PC(ITransactionParticipant 六件套)

方法签名 语义
void Prepare(long seq) / ValueTask PrepareAsync(long seq, CancellationToken ct) 事务准备:落盘数据 + meta 至"悬干"状态。Transport 回落 MetaHost = 1 次 fsync(meta record 随数据同页 flush 原子落盘);Managed/注入 Transport/Disabled = 2 次 fsync(FlushUntil 先 + WriteMeta 后)。经 _prepareGate 串行
void ConfirmCommitted(long seq) 推进 LastCommittedSeq,触发回调;推进 _txRollbackTail(提交边界,随 meta 持久化为 CommittedTailAddress)
void OnCommitted(long seq, Action callback) 注册 seq 回调;已提交到更高 seq 立即同步触发
void Abort(long seq) / ValueTask AbortAsync(long seq, CancellationToken ct) 2PC 回滚——TruncateSuffix(_txRollbackTail) 回退到上一已确认提交边界,丢弃本轮悬干数据。守卫矩阵:seq ≤ LastCommittedSeq=no-op;seq ≠ LastPreparedSeq=陈旧;无既有提交边界/无悬干数据 = 仅复位记账

LastCommittedSeq / LastPreparedSeq 公开只读(恢复 / 运行时读)。

4.9 Opaque meta 搭车

方法签名 语义
void SetOpaqueMeta(ReadOnlySpan<byte> data) 写外部 opaque meta(stage 进策略缓冲,随下一次水位提交原子落盘)。唯一消费者形态:TierKV 组合层登记 index 镜像锚点 W。MetaPolicyKind=Disabled 时拒写
ReadOnlySpan<byte> ReadOpaqueMeta() 读最近已提交块;空 = 未写入/未开启 meta 持久化——空即答案
IMetaPolicy<RingMetaHeader, RingMetaPayload> MetaPolicy { get; } 构造期装配(永非 null 纯读)

5. 自定义注入工厂

接口 / 类型 职责 默认实现 自定义注意
IRingCodec record 三段式 codec(header/CRC/字段偏移/单字段读) BlittableRing.Codec 暴露 HeaderSize / Alignment / Magic / CrcOffset / PayloadLengthOffset;TryReadHeaderLight 热路径轻量门(magic+长度上界+Flags),免全量 header 解码——本进程写入页池热读专用;设备回源/恢复走全量 TryReadHeader
RingRecordFields record 业务字段包(Flags / PayloadLength / PaddingLength / PreviousAddress)—— readonly record struct — codec 读写 header 时传参
RecordKey<TKey> Key + ValueLength + Flags + Address 组合返回值 — IsOverflow / IsMeta / IsTombstone 旗标属性
IKeyResolver<TKey> Index 注入 Ring 时必需的判等闭环契约 RingBase<TKey> 实现 TryGetKey / GetFlushedWatermark / ScanAsync 三成员;扫描详见 §4.7
IRingScanCursor 扫描游标,扩 IStructureScanCursor SequentialRingScanCursor(嵌套 sealed) CurrentAddress / NextAddress / BeginAddress / EndAddress / GetFields() / CurrentRecordSize;自定义经 RingCursorFactory<out TRingScanCursor> 委托注入
RingCursorFactory<out TRingScanCursor> 扫描游标工厂委托 (begin, end) => cursor null = 默认 SequentialRingScanCursor 自定义经构造参数 cursorFactory 注入
IRingSnapshot 快照统一抽象(pull/push 分离) RingSnapshot<TRing>(嵌套) Reader(begin, end) / Writer(begin, end);自定义经构造参数 ringSnapshot 注入
RingSnapshotReaderFactory / RingSnapshotWriterFactory 快照读写器工厂委托 null = 默认 RingSnapshotReader / RingSnapshotWriter 自定义经构造参数 snapshotReaderFactory / snapshotWriterFactory 注入
IRingSnapshotReader 快照读取器——pull 模式,页级流式 — Length / Read(Span) / ReadAsync(Memory, ct);IDisposable + IAsyncDisposable
IRingSnapshotWriter 快照写入器——push 模式,Complete 收口 — Write(ReadOnlySpan) / WriteAsync(ReadOnlyMemory, ct) / Complete() / CompleteAsync(ct)
OverflowPolicy(enum) 溢出策略 Disabled / Enabled Disabled Enabled = WiscKey 式 value 分离,溢出引擎与主引擎同 fs
RingMetaPayload(struct) 7 个 LogicalAddress(Begin/FlushedUntil/SafeReadOnly/ReadOnly/Tail/OverflowTail/CommittedTail)+ LastCommittedSeq + LastPreparedSeq + KeySize — [BinaryLayout] 源生成器产出 codec;旧块短 payload 零扩展降级
RingMetaHeader(struct) meta header 规范字段(MagicValue / Version / Flags / PayloadLength / PaddingLength,12B) — Magic="RMHD",CurrentVersion=major 1/minor 0
AddressInfo(internal struct) 溢出指针(Address + Size,24B) — 旧版 8B 位压缩在 LogicalAddress(16B) 模型下不适用
OverflowRecordHeader(internal struct) 溢出帧头 18B(Magic+Version+Flags+PayloadLen+PadLen+Crc32C) — Magic "OVRF",Alignment=4
IReadOnlyRecordHandler<in TKey> 批量读回调接口 — Handle(LogicalAddress address, TKey key, int valueLength, ushort flags)——flags 是 RecordFlags 内部位
MetaPolicyFactory<RingMetaHeader, RingMetaPayload> meta 策略工厂委托 kind => policy CreateMetaPolicyDefault Managed / Transport(未注入 transport 回落 MetaHost)/ Disabled 三模式
IMetaTransport Transport 模式的外部 meta 传输 MetaHost(嵌套,回落:meta record 嵌入 ring 流) 自定义经构造参数 metaTransport 注入
IRecovery<RingRecoveryHints> 恢复策略 DefaultRingRecovery(四级回退) 自定义经构造参数 recovery 注入;裸写 IRecovery 与 LifecycleBase 闸门不同步——继承 RecoveryBase<RingRecoveryHints>
LightEpoch epoch 保护 自建 自定义共享经构造参数 epoch 注入(ResourceOwnership.Referenced)