Table of Contents

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——持久化机制与恢复协议