三模计算便捷 API

可用性：完整版（Full）专属。头文件 onepath_compute.h 面向完整版提供；精简版（Tiny） 下相关声明在头文件中即被剔除，误用在编译期即报错——这是一条明确的能力边界。

一、设计要点

三模计算便捷 API 让你注册单个计算函数，一次声明即把它接到两条通路：对数据流做就地变换 （发布→订阅），以及对外提供按需计算服务（查询→应答）。

• 一次注册，两路覆盖：onepath_compute_open() 按选项启用
  • 流式变换：订阅 in_sign，对每条样本调用计算函数，把结果发布到 out_sign；
  • 按需 RPC：在 serve_sign 上应答查询，对每个查询调用计算函数并回复结果。
• 统一计算函数：流式与 RPC 共用同一计算函数签名，从输入产出 0..N 条结果，经输出汇 sink 发射。
• 一进多出：计算函数可对一条输入发射多条结果，也可不发射（丢弃）。

二、快速上手

#include <onepath.h>
#include <onepath_compute.h>
#include <ctype.h>

/* 计算函数: 把输入转大写后产出 (流式与 RPC 共用) */
static void upper_fn(void *ud, const char *sign, const void *in, size_t n,
                     onepath_compute_sink_t *sink)
{
    char buf[256];
    if (n >= sizeof buf) n = sizeof buf - 1;
    for (size_t i = 0; i < n; i++)
        buf[i] = (char)toupper((unsigned char)((const char *)in)[i]);
    onepath_compute_emit(sink, NULL, buf, n);   /* sign=NULL: 流式用 out_sign, RPC 用查询签名 */
}

int main(void)
{
    onepath_session_t s;
    onepath_open(&s);

    onepath_compute_opts_t opts = ONEPATH_COMPUTE_OPTS_DEFAULT;
    opts.in_sign    = "demo/compute/in";    /* 流式输入 */
    opts.out_sign   = "demo/compute/out";   /* 流式输出 */
    opts.serve_sign = "demo/compute/rpc";   /* 按需 RPC */
    opts.fn         = upper_fn;

    onepath_compute_t c;
    onepath_compute_open(s, &c, &opts);

    /* 此后: 发布到 in_sign 的数据被变换后到达 out_sign;
     *       查询 serve_sign (带负载) 得到变换后的应答。 */

    onepath_compute_close(c);
    onepath_close(s);
    return 0;
}

配套示例程序 onepath_compute_node（compute / feed / watch / call 四角色）给出完整可运行 版本。

三、计算函数与输出汇

计算函数：流式路径下 sign 为样本签名、in 为样本负载；RPC 路径下 sign 为查询 签名、in 为查询负载（可能为 NULL/0）。两条路径共用同一函数。

输出汇 onepath_compute_emit：在计算函数内调用以产出一条结果。首个参数 sign 传 NULL 时自动选择输出签名——流式路径用 out_sign（未配则回发到样本签名），RPC 路径用 查询签名。可调用多次产出多条结果，或不调用以丢弃该输入。

计算函数完整签名、选项字段、输出汇原型与各 *_DEFAULT 取值见 三模计算 API。

四、所有权与限制

• onepath_compute_open 写出的句柄归调用者所有，用完须 onepath_compute_close。
• onepath_compute_emit 的 out 指针只需在调用期间有效（内部立即发布或回复）。
• 计算函数在内部线程上被调用；若访问共享状态，请自行加锁。
• in_sign 与 serve_sign 必须至少配置一个，否则 onepath_compute_open 返回参数错误。
• 流式变换是无状态的逐条处理；若需窗口 / 聚合等有状态计算，请在 userdata 内自行维护 状态并加锁。

详见 内存管理。

与多模冗余的区别

三模计算是单节点两通路便捷封装。若需要多个 worker 冗余计算 + 投票选举的容错，见 多模冗余 XMR——两者正交、可叠加。

API 参考

完整的函数签名、选项结构体 onepath_compute_opts_t、计算函数与输出汇类型、各 *_DEFAULT 宏见 三模计算 API。