通道与调用面
CellChannel:宿主侧会话句柄——一次握手完成后所有交互都经它:调用、取消、回调服务分发、
遥测消费、drain。
调用
var result = await channel.InvokeAsync(
"app.echo", // 装载点键
CellCodecIds.None, // codecId(载荷词汇归使用方)
payload, // ReadOnlyMemory<byte>
deadline: TimeSpan.FromSeconds(2)); // 可选;到期宿主侧兜底失败
- callId 单调分配;在途调用有界(缺省 1024),超限=背压拒绝新调用(不挤在途)。
- deadline 到期:宿主侧立刻失败(
DeadlineExceeded),同时向容器发取消——两头不悬挂。 - 返回
ResultFrame:ErrorCode+CodecId+Payload。非 Success 即调用失败, 细节取证在容器 stderr(处理委托抛出的异常不进线内)。
取消
await channel.CancelAsync(callId); // 发 Cancel 帧;容器侧处理委托收到 ct 取消
容器侧处理委托以 CancellationToken 收尾:取消响应速度取决于委托体对 ct 的配合。
回调(容器 → 宿主)
容器内 pack 可以反向调用宿主注册的服务——键+委托,requestId 多路复用,await 期间可并发发起:
channel.RegisterCallbackService("host.config.get",
static (payload, ct) => ValueTask.FromResult<ReadOnlyMemory<byte>>(LoadConfig(payload)));
未注册键的回调以 PackNotFound 应答(不悬挂容器)。
遥测
channel.TelemetryBatch += batch => Sink.Write(batch);
- 容器侧有界队列、满则丢最旧——遥测永不阻塞调用路径;
- 心跳期空批到达=活性信号(监督器的心跳失联判定即基于此节奏);
- best-effort 语义:宿主不收也不影响容器。
drain 与退出
await channel.SendByeAsync(drainWindowMilliseconds: 2000);
// 容器:停接新调用 → 在途收尾或窗口到期 → 退出码 0
容器退出码只有两个:0=drain/父退出正常终态;11=运行期致命(stderr [cell] fatal: 取证)。
载体选择
| 载体 | 声明 | 适用 |
|---|---|---|
| 环回 TCP(缺省) | Carrier = "tcp" |
全平台、零额外设施 |
| UDS | Carrier = "uds"(仅 Unix) |
去 IP 栈,延迟更低 |
| 共享内存 | Carrier = "shm" |
同机低时延——数据直写映射内存,数据通路零系统调用(仅门铃一次);段建立与传递全自动,对使用方零感知 |
| InProcess | InProcessTransport |
测试同构——单测秒级纪律的载体底座 |
各载体往返延迟实测见性能基线(数字单源在那,不在此复制)。
各载体同一套通道语义、同一套对抗测试等价复跑——载体替换对协议与使用方零感知。
低时延档(shm 忙轮询)
shm 载体读侧等待策略可选:混合档(缺省——有界自旋后转门铃阻塞,零 CPU 等待)与 忙轮询档(自旋+让渡,p50 再快一半以上,代价=每方向一个核)。低时延档是连接级协商契约:
var options = new CellProcessStartOptions
{
Carrier = "shm",
ShmWaitStrategy = ShmRingWaitStrategy.BusySpin, // 宿主要求+经 spawn 转发容器
// ...
};
宿主要求低时延而容器未以同策略启动=策略错位,握手即失败(fail-fast,绝不静默降级)—— 低时延是部署承诺,不是可观测的意外。
反模式
| 症状 | 为什么错 | 正确形态 |
|---|---|---|
复用 ResultFrame.Payload 跨调用 |
帧体缓冲池化归还——读到的是脏数据 | 留存即 ToArray() |
忽略 ErrorCode 只看 Payload |
失败回执的 Payload 为空,错误被静默吞 | 先判 ErrorCode == Success |
| 高频小调用无 deadline | 挂死容器永久占坑 | 每类调用给deadline,让兜底失败可观测 |
| 把 shm 载体当跨机方案 | 共享内存仅同机语义(映射段不跨机) | 跨机走 TCP 载体(网络语义归监督器) |
| 大帧直接上 shm 缺省容量 | 单环缺省 1MB,帧长上限按容量预算 | 大载荷场景 spawn 时显式 ShmRingCapacityBytes(2 的幂) |