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):
PageSize是 2 的幂 / [4KB, 1GB]MemorySize ≥ PageSize且整除为 2 的幂页数PageCount ≤ MaxPageCountSegmentGrowthLimit ≥ PageSizeMutableFraction ∈ (0,1)开区间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) |