错误处理

OnePath 采用统一错误码约定：所有可失败的函数返回 int，ONEPATH_OK（值为 0）表示成功，负值表示具体错误。销毁类函数（onepath_*_destroy、onepath_close、release 函数）返回 void，不会失败。

错误码枚举

错误码	值	含义
ONEPATH_OK	0	成功
ONEPATH_ERR	-1	通用错误
ONEPATH_ERR_PARAM	-2	参数无效
ONEPATH_ERR_NOMEM	-3	内存分配失败
ONEPATH_ERR_CONN	-4	连接 / 会话失败
ONEPATH_ERR_TIMEOUT	-5	操作超时
ONEPATH_ERR_CLOSED	-6	通道已关闭 / 资源已销毁
ONEPATH_ERR_UNSUPPORTED	-7	当前变体 / 运行环境不支持此功能

几个高频语义

• ONEPATH_ERR_TIMEOUT：非阻塞接收（*_try_recv）暂无数据时也返回此码，属正常轮询结果，不是故障。
• ONEPATH_ERR_CLOSED：阻塞接收返回此码通常表示对端回复 / 数据已全部收完，是正常的循环终止条件。
• ONEPATH_ERR_UNSUPPORTED：某能力在当前运行环境不可用时返回（例如网络拓扑感知在个别环境）。注意 full 独占的 3 组 API 在 tiny 下是编译期报错而非此运行期码——详见 变体选择。

获取可读描述：onepath_strerror

const char *onepath_strerror(int err);

把错误码转换为人类可读的静态字符串。返回的指针指向静态存储区，无需释放。

int rc = onepath_open(&s);
if (rc != ONEPATH_OK) {
    fprintf(stderr, "打开会话失败: %s\n", onepath_strerror(rc));
    return 1;
}

推荐的错误处理范式

判等 ONEPATH_OK，失败时打印 onepath_strerror 并妥善清理已创建的资源：

onepath_session_t s;
if (onepath_open(&s) != ONEPATH_OK) {
    fprintf(stderr, "无法打开会话\n");
    return 1;
}

onepath_publisher_t pub;
int rc = onepath_declare_publisher(s, &pub, "demo/hello", NULL);
if (rc != ONEPATH_OK) {
    fprintf(stderr, "声明发布者失败: %s\n", onepath_strerror(rc));
    onepath_close(s);          /* 回滚已创建的会话 */
    return 1;
}

接收循环里，用 ONEPATH_ERR_CLOSED 作为自然的终止条件：

onepath_reply_t reply;
while (onepath_reply_recv(rx, &reply) == ONEPATH_OK) {
    /* ... 处理 reply ... */
    onepath_reply_release(&reply);
}
/* 循环退出 = 通道关闭，所有回复已收完 */

资源清理与配对规则详见 内存管理。