连接接管：XS_TAKEOVER 的第三条路

本章导读

25.1 引入

三态的边界在第 4 章画过：XS_OK 交还连接继续 keep-alive、XS_FALLBACK 交给静态层。第三态 XS_TAKEOVER 的语义是"这条连接从现在起归我"——驱动撤出事件处理，之后的收发、超时、关闭全部由应用逻辑决定。典型场景：HTTP Upgrade 到私有协议、代理隧道、需要跨请求长会话的推送网关。

25.2 接管语义

• 接管点：从 RequestProc 返回 TAKEOVER 那一刻起，连接不再被 HTTP 驱动消费
• 事件表：应用接管后换成自己的事件处理（不得替换为非法状态）
• 回收契约：连接对象最终仍由 XServer Destroy——你经营它，但不拥有它的析构；Close 终态同时释放该连接持有的代租约
• 字节同步：接管前你已消费/写出的字节仍受驱动核对——半截 HTTP 请求 + TAKEOVER 的组合会被一致性校验拒绝

25.3 pull 模式实战

func_test 里有一个接管回显的真实用例，模式如下（异步拉取收发）：

typedef struct TakeoverCtx {
    XS_HostInfo*  pHost;      /* 需要跨线程时按所有权规则处理 */
    xnetstream*   tcp;        /* 或 tls：接管后的传输层 */
} TakeoverCtx;

static XS_RequestResult RequestProc(XS_HttpReq* pReq)
{
    if ( !IsUpgradeTarget(pReq) ) return XS_FALLBACK;

    /* 1. 先写出协议要求的应答字节（如 101 Switching Protocols）*/
    /* 2. 建接管上下文 */
    TakeoverCtx* pCtx = xrtCalloc(1, sizeof(TakeoverCtx));
    pCtx->tcp = pReq->tcp;

    /* 3. 挂异步读：数据到达进回调（测试用例用独立线程 + RecvAsync）*/
    StartTakeoverLoop(pCtx);

    return XS_TAKEOVER;   /* 连接归我 */
}

刚才发生了什么：接管循环里你对 pCtx->tcp 用普通 xrt 流 API 收发——就像它在 ch23 里那样。区别只是这条流的"出身"是 HTTP 连接，而你决定它后续说什么协议。

25.4 终态与回收

• 你必须最终 Close：接管即承诺——忘记关闭的连接会一直占着（idle_timeout 是兜底而非设计路径）
• Close 走流 API 的关闭语义；XServer 在连接终态回调里 Destroy 并释放代租约——所以旧代能等接管连接全部结束才回收（reload_matrix 验证过这个时序）
• 接管上下文（pCtx）的释放跟着 Close 走——与 WS/TCP 注册表同构的清理模式

25.5 契约

• 接管线：返回 TAKEOVER 前必须完成协议应答字节；接管后驱动不再消费该连接。
• 终态线：应用负责最终 Close；Destroy 与租约释放由 XServer 在终态完成。
• 上下文线：接管上下文生命周期绑定连接终态，注册表式清理。

常见错误

编程练习