Table of Contents

通道与调用面

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 的幂)

想深入