Ring 使用指南——追加式 KV 环 / RCU 原地更新 / 环形驱逐
给谁看:用 Ring 作 KV 真相源 / WAL 的组件开发者 回答什么:Ring 是什么 / Settings 全参数 / 8 水位 / Codec 注入 / 写读 API / 恢复 / 反模式 本篇只讲机制——帧字节布局见源码;性能数字见
perf/structures-perf-baseline.md定位:Structures/ 6 子族之一,主结构(数据真相源),与 Log 并列 2 主结构
形态边界:本篇只讲定长键
BlittableRing<TKey>;变长键环VarKeyRing(40B 同构头 Magic "VRHD" + 记录体变长 prologue)见 tiervarkv.md 与 binary-format-spec §2.5b。
0. 一句话总纲
Ring = 固定槽数环形页池 + 全局单调逻辑地址 + 水位组(7 水位 CAS128 原子块 + tail 锁内推进)+ RCU 原地更新 + 环形驱逐
- 追加写返回
LogicalAddress(16B 结构SegId+Extension+Offset)= 取值句柄,地址永不重写 - 同尺寸 value 经
UpdateValue原地覆写(RCU 语义),同槽位复用 - 环形满自动驱逐最老页(Head 推进);地址空间永远单调向前
- 7 水位指针驻留 16B 对齐块经 CAS128 原子推进(cmpxchg16b 快路径 / 非对齐分片锁兜底),并发 Flush/Truncate 不会回退;
TailAddress不入原子块——分配热路径在_tailLock锁内推进(CAS 每写 +5ns 不可接受) - 地址运算只用
engine.GetDistance/engine.CalculationAddress(铁律:LogicalAddress.Offset跨段无意义,不参与算术)
1. 定位
- 与 Log 同为主结构:Ring 是数据真相源(record 流),Log 是操作流;二者均以
LogicalAddress为一等公民 - 与 Index 组合:Ring=真相源 / Index=派生数据;写编排正序:先 Ring.Write → 再 Index.Insert
- 与 Mirror/Snapshot 关系:Ring 自带
OpenSnapshotReader/Writer区间导出/导入能力(数据快照),与独立的mirror.md/snapshot.md形态无引用关系 - 与 Meta 关系:外部 opaque 经
SetOpaqueMeta随水位线原子落盘,是 Index 锚点 W 的搭车通道 - 与 StorageEngine 关系:结构层是 internal 使用者;文件系统 = 构造传哪个
IFileSystem(详见storage-engine.md)。引擎自恢复 MinAddress/AllocatedTail;Ring 自管 8 水位 - 与横切协议:meta 持久化经统一
IMetaPolicy(见meta.md);2PC 跨结构原子经ITransactionParticipant(协调器见session.md)
3. 构造与生命周期
3.1 [RingKey] 源生成器机制
开放泛型 BlittableRing<TKey> 的构造是 protected internal——消费面只经 [RingKey] 生成的封闭薄类(编译期封闭 + CreateAsync 工厂)。内置 long 已在 KernLab.Tier.Runtime 程序集声明,RingOfLong 开箱即用;自定义 Key 在消费程序集加一行:
[assembly: RingKey(typeof(OrderId))] // 产出 RingOfOrderId / HashOfOrderId / BTreeOfOrderId ...
分析器诊断不满足 unmanaged 约束的声明。绕过 [RingKey] 直接继承开放泛型 = CS0122 编译错(internal 不可见时绑定器误绑 IO 扩展同名方法)。
3.2 CreateAsync 工厂 = 构造 + Initialize + WaitForReadyAsync 一步就绪
using var fs = TierFs.New("memory:");
var settings = new BlittableRingSettings(new StorageEngineOptions("kv-ring", 64L << 20))
{
PageSize = 4096, MemorySize = 64 * 1024, MutableFraction = 0.5,
};
await using var ring = await RingOfLong.CreateAsync(settings, fs); // 就绪可读写
或分步(观察恢复进度 / 注入恢复窗口):
var ring = new RingOfOrderId(settings, fs);
ring.Initialize(); // 触发 OnInitializeBegin → 三引擎并行启动 + 恢复
ring.WaitForReady(); // 等恢复完成(默认四级回退)
3.3 写读最小用例(正序两步写 / 两段合口径读)
static LogicalAddress KvPut(RingOfLong ring, IIndex<long> index, long key, ReadOnlySpan<byte> value)
{
var addr = ring.Write(key, value); // ① 真相源先写,得地址
index.Insert(key, addr, LogicalAddress.Empty); // ② 索引后插(指向该地址)
return addr;
}
static bool KvTryGet(RingOfLong ring, IIndex<long> index, long key, Span<byte> buf, out int len)
{
len = 0;
var addr = index.Find(key); // ① 索引命中得地址
if (addr == LogicalAddress.Empty) return false;
len = ring.GetValue(addr, buf); // ② 真相源按址取值
return true;
}
3.4 Dispose
幂等(CAS 排他门 _disposeGate)。落盘契约(存储底线):先把 mutable 区 [FlushedUntilAddress, TailAddress) 落盘(FlushUntilCore 免门直走)→ 写 meta → 释放 meta 策略 → 释放页 native 内存。各步异常吞掉互不阻断(尽力落盘)。Dispose 与并发读写经 EnsureReady/EnsureNotDisposing fail-fast 隔离。
8. 反模式
| # | 反模式 | 后果 / 正解 |
|---|---|---|
| 1 | 写编排反序:先 index.Insert 再 ring.Write |
索引指向不存在的数据。正序:先 ring.Write 得地址 → 再 index.Insert |
| 2 | 零拷贝 span 跨 await:GetValueSpan 返回值跨 await 持有 |
span 仅同步栈内合法;跨 await/跨线程消费必须走拷贝 API(TryGetValue/GetValue)——API 形态强制,不依赖约定 |
| 3 | 绕过 [RingKey] 直接继承开放泛型:new BlittableRing<TKey>(...) |
CS0122 编译错(protected internal 闸门);封闭薄类是唯一消费面 |
| 4 | 跨实例组合 DeleteOnClose=true |
跨重启组合必须 DeleteOnClose=false(否则索引重建时真相源被清) |
| 5 | 给地址直达读加会话/索引:GetValue(addr) 前先 EnterScope 等 |
地址即句柄——GetValue(addr) 永久零税。读路径已退役 epoch 保护,调用方编排不必要 |
| 6 | TruncatePrefix 越过 FlushedUntilAddress |
抛 InvalidOperationException——未落盘数据会丢。截断点必须 ≤ FlushedUntilAddress |
| 7 | TruncateSuffix 落入已驱逐区(< SafeHeadAddress) |
抛——事务窗口横跨已驱逐页,无安全回退边界。Abort 前置窗口内不应发生大规模驱逐 |
| 8 | WriteBatch 跨 await 持有:ref struct 不跨 await,但 using 范围跨 await |
写锁语义——批窗口持 epoch,跨 await 持有 = epoch 嵌套警告。批在同步栈内开闭 |
| 9 | Overflow=Enabled 时分段写超阈值 | Write(key, prefix, value) 抛 InvalidOperationException——用连续 value 的 Write/WriteAsync |
| 10 | UpdateValue overflow→inline 回退时超原 inline 槽容量 |
抛——newValue.Length > originalInlineCapacity。原 inline 槽容量 = allocated - HeaderSize - keyLen |
| 11 | MetaPolicyKind=Disabled 时 SetOpaqueMeta | 抛——未开启 meta 持久化,opaque 登记被拒。配置 Managed/Transport 或移除 opaque 写入 |
| 12 | 跨特化开同一卷(RingOfLong 开 RingOfGuid 的卷) |
ValidateKeySizeAnchor fail-fast——盘上 KeySize 与实例 TKey 不符,避免静默 key 损坏 |
9. 想深入?指路
| 想懂什么 | 去哪 |
|---|---|
| 总览(七结构选型 / 组合 KV / 恢复模型) | structures.md |
| 横切协议(opaque 搭车 / 块格式 / 自定义传输 / 锚点 W) | meta.md |
| Session 协调协议(写/读/检查点三 op、悬挂裁决、故障模型) | session.md |
| 引擎使用(读写/水位/恢复/Compact/段表) | storage-engine.md / segment-table.md |
| Lease 协议(raft 共识 lease) | lease-protocol.md |
| 同族其他结构 | log.md / index.md / versioned-metadata.md / mirror.md / snapshot.md |
| 性能基线(点查/写/恢复/并发扩展) | perf/structures-perf-baseline.md |
| 记录帧/水位块的精确字节布局(互操作解析手册) | binary-format-spec.md |
| 源码(base/Settings/Contracts/各 partial) | src/KernLab.Tier.Runtime/Structures/Ring/ |
机制级细节(CAS128 水位基座、帧字节布局、溢出分块骨架、2PC 内部状态机、撕裂重同步扫描器)按需从源码注释与内部设计稿(不随包发布)查阅——使用面不需要这些细节;能力全集以类型 XML 注释为准。
分册导航:ring.md | [ring-api.md](API 与工厂) | ring-persistence.md | Ring——Settings / API 详表 / 注入工厂 | Ring——持久化机制与恢复协议