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. 反模式
- 环内只存字节,禁存指针——跨进程地址空间不同,任何引用语义一律用段内 offset 表达。
TryWrite后忘Signal——TryWrite是低阶原语不鸣铃;阻塞中的Read只认门铃。 高阶入口(Write/WriteBatch)已自动收口,混用低阶入口时必须自己Signal()。- Unix 跨进程接入不传门铃描述符——
Open不带DoorbellFileDescriptors会新建私有门铃, 阻塞等待收不到对端信号(同进程成对使用才合法)。跨进程必须传创建方DuplicateDoorbellDescriptors()的复制品(四只成组,见 §7 样例)。 - DropOldest 档长期持有原位切片——写者可覆盖最旧帧,在读切片可能失效;
遥测消费要么拷贝形态读,要么读到即
Advance。 - 把检脏当可恢复错误——
ShmRingBrokenException是重建信号(管理面拉起对端换代), 不是可重试异常;检脏后继续读持续抛。 - 同环多写者/多读者——严格 SPSC 是契约红线;多对一聚合在环外做(每对端一条环)。
- 创建方提前释放段——段生命周期归创建方:创建方
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. 想深入
- 性能报告——门铃往返 RTT / 吞吐实测与选型结论
../COORDINATION.md——Core 积木全景与本件在并发原语族中的位置