Table of Contents

ShmRing —— SPSC 共享内存门铃环

同机进程间低时延数据通路:内存映射段上的变长帧环形队列,配内核门铃唤醒。 零依赖叶子原语(仅本包);性能实测见 perf/shm-ring-perf.md。

1. 定位

是什么:单写单读(SPSC)共享内存门铃环——Create 创建一段双环(A→B / B→A 各一条), 对端 Open 接入,双向各自严格一写一读。不落盘不恢复:崩溃即检脏 fail-fast,由使用方决策重建。

不是什么(与 KernLab.Tier.Runtime 的存储引擎级 Ring 的边界):

维度 Runtime Ring(存储引擎级) ShmRing(本件)
落盘 持久化 + 恢复重放 不落盘——检脏 fail-fast
并发 多写者窗口 严格 SPSC(一端一写者,契约红线)
地址 全局单调逻辑地址 环内 64 位位置(容量取模)
依赖 Runtime 全套引擎 零依赖叶子

何时用:同机进程间的调用域指令流、遥测流、低时延信令——需要把内核从数据通路移除的场景 (门铃往返 p50 见 性能报告,默认档为环回 UDS 的约 1/7)。

2. 快速上手

using KernLab.Tier.Core.Ipc;

// 创建方(一段双环,两方向各一档背压)
using var ring = ShmRing.Create(new ShmRingOptions
{
    Name = "app.call-channel",           // Windows 为跨进程接入名;Unix 匿名段仅作诊断标签
    CapacityBytes = 1 * 1024 * 1024,     // 单环容量,2 的幂,≥4KB
});
var a = ring.EndpointA;   // A 端:写 A 环 + 读 B 环
var b = ring.EndpointB;   // B 端:写 B 环 + 读 A 环

// 写(批尾一次门铃)
a.Writer.Write(stackalloc byte[] { 1, 2, 3 });

// 读(按等待策略阻塞至有帧)
var frame = b.Reader.Read();
Console.WriteLine($"收到 {frame.Length} 字节");
b.Reader.Advance();       // 消费——写侧空间随之放开

对端进程接入(本进程双线程同用一段时无须 Open,直接用 EndpointA/B):

using var peer = ShmRing.Open(new ShmRingOpenOptions
{
    Name = "app.call-channel",           // 与创建方同名(Windows)
    ExpectedGeneration = 0,              // 重连时传上次记录的 Generation——不符即拒绝(对端曾重建)
});
var myEndpoint = peer.EndpointB;          // 接入方用 B 端,与创建方的 A 端配对

3. 概念

  • 段:一段 = 控制块 + 双环数据区。控制块存魔数/版本/容量/代数/创建者与双环位置;运行期热路径只碰本环 的 head/tail(各占独立缓存行,无伪共享)。
  • 帧:[4B 长度][payload][对齐垫],帧长 8 字节对齐。长度位 0 保留为"未提交"标记——空帧不可表达, 信号类诉求走 Signal()(门铃即信号帧)。帧体永不跨越环折返点:放不下时写跳转标记、落到环起点, 读侧透明穿越——原位切片因此始终连续。
  • 门铃:跨进程唤醒信号,计数合并语义(无等待者的信号积攒不丢)。每段四只、按环成对: 数据门铃(写→读)+ 空间门铃(读→写,仅 BlockWriter 档启用)。
  • 原位切片:TryRead 返回的 ReadOnlySpan 直指映射内存(零拷贝),有效期至 Advance—— BlockWriter 档下写者无法覆写在读帧(空间判据以 head 为界)。
  • 代数与检脏:段每次整体重建代数 +1;接入方记录 Generation,重连以 ExpectedGeneration 校验, 不符即拒绝打开。检脏 fail-fast 是契约:不做持久化恢复、不做重放、不做部分帧修补。

4. 怎么选

等待策略(WaitStrategy,各进程自选,只影响 Read/Write 的阻塞方式):

档 行为 选它当
Hybrid(默认) 有界自旋(默认 8µs,HybridSpinMicros 可调)未中转门铃阻塞 绝大多数场景——时延与 CPU 的平衡点
BusySpin 纯自旋(实测 RTT p50 ≈1µs) 专核低时延通路,接受烧一个核
Blocking 门铃睡眠零 CPU 后台遥测/低频通路,时延不敏感

背压档(RingABackpressure/RingBBackpressure,创建时按环设定,随段快照生效):

档 满环行为 选它当
BlockWriter(默认) Write 阻塞等空间(空间门铃反向通知);TryWrite 返回 false 调用域/指令流——不许丢帧
DropOldest 覆盖最旧未消费帧,DroppedCount 递增 遥测域——只关心最新值

两环可各设一档(调用域 + 遥测域双环诉求的直接映射)。

5. 怎么用

写侧(ShmRingWriter):

API 语义
Write(ReadOnlySpan<byte>) 阻塞写:BlockWriter 档满环等待空间;DropOldest 档满环覆盖。批尾自动鸣铃
TryWrite(ReadOnlySpan<byte>) 非阻塞:BlockWriter 满环 false;DropOldest 恒 true。不鸣铃
WriteBatch(IReadOnlyList<ReadOnlyMemory<byte>>) 合批写入,批尾只鸣一次铃(门铃去抖是批的意义)
Signal() 手动鸣数据门铃(写完 TryWrite 系列后收口 / 纯信号帧)

读侧(ShmRingReader):

API 语义
Read() 阻塞读一帧(按等待策略);检脏即抛
TryRead(out ReadOnlySpan<byte>) 非阻塞原位切片(零拷贝);Advance 前有效;不鸣铃不等待
TryRead(Span<byte>, out int) 拷贝形态(内置消费);目标不足不消费
Advance() 消费在读帧(BlockWriter 档唤醒等待空间的写者)
DroppedCount / IsBroken / IsWriterDead 丢帧计数 / 检脏态 / 对端存活(跳帧可观测,禁静默)

计数器:WrittenFrames/WrittenBytes、ReadFrames/ReadBytes——守恒检查 written == read + dropped(DropOldest 档)是自检利器。

超限帧:payload 为空(长度位 0 保留)或超过 MaxFrameBytes(默认容量一半,防"帧大于空位"死锁) 在入口抛 ArgumentOutOfRangeException。

6. 反模式

  1. 环内只存字节,禁存指针——跨进程地址空间不同,任何引用语义一律用段内 offset 表达。
  2. TryWrite 后忘 Signal——TryWrite 是低阶原语不鸣铃;阻塞中的 Read 只认门铃。 高阶入口(Write/WriteBatch)已自动收口,混用低阶入口时必须自己 Signal()。
  3. Unix 跨进程接入不传门铃描述符——Open 不带 DoorbellFileDescriptors 会新建私有门铃, 阻塞等待收不到对端信号(同进程成对使用才合法)。跨进程必须传创建方 DuplicateDoorbellDescriptors() 的复制品(四只成组,见 §7 样例)。
  4. DropOldest 档长期持有原位切片——写者可覆盖最旧帧,在读切片可能失效; 遥测消费要么拷贝形态读,要么读到即 Advance。
  5. 把检脏当可恢复错误——ShmRingBrokenException 是重建信号(管理面拉起对端换代), 不是可重试异常;检脏后继续读持续抛。
  6. 同环多写者/多读者——严格 SPSC 是契约红线;多对一聚合在环外做(每对端一条环)。
  7. 创建方提前释放段——段生命周期归创建方:创建方 Dispose 后接入方仅能读元数据, 段载体由双方各自释放份额,创建方最后释放收尾。

7. 跨进程接入(Unix 形态:描述符传递)

Unix 段载体为匿名形态(文件系统零残留),跨进程经进程间描述符传递:创建方传出 5 个描述符 (1 段 + 4 门铃,槽位序 = 段, Bell0..Bell3),接收方按序拼装 Open 选项:

// 创建方:经既有流式通道(如 Unix 域套接字 SCM_RIGHTS)传出
int[] fdsToSend = [ring.DuplicateDescriptor(), .. ring.DuplicateDoorbellDescriptors()];

// 接收方:收到 5 个描述符后
using var peer = ShmRing.Open(new ShmRingOpenOptions
{
    FileDescriptor = received[0],
    DoorbellFileDescriptors = received[1..5],   // 四只成组——阻塞等待的跨进程通路
    ExpectedGeneration = 0,                     // 重连时传上次 peer.Generation
});

描述符传递本身属通道职责(Unix 域套接字 sendmsg/recvmsg 附带数据,创建方与接入方各实现一次), 本原语不内置通道。Windows 无此步骤:段与门铃均按名接入,双方同 Name 即同对象。

8. 想深入