三模计算便捷 API

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

概述

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

一、设计要点

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

二、快速开始

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

/* 计算函数: 把输入转大写后产出 (流式与 RPC 共用) */
static void upper_fn(void *ud, const char *key, 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);   /* key=NULL: 流式用 out_key, RPC 用查询键 */
}

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

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

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

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

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

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

三、API 参考

int  onepath_compute_open(onepath_session_t s, onepath_compute_t *out,
                          const onepath_compute_opts_t *opts);
void onepath_compute_close(onepath_compute_t c);
int  onepath_compute_emit(onepath_compute_sink_t *sink, const char *key,
                          const void *out, size_t len);

函数	说明
onepath_compute_open(s, &out, opts)	打开三模计算；opts.fn 必填，in_key/serve_key 至少配其一
onepath_compute_close(c)	关闭并销毁；注销订阅与应答；NULL 安全
onepath_compute_emit(sink, key, out, len)	在计算函数内产出一条结果

计算函数 onepath_compute_fn

void fn(void *userdata, const char *key,
        const void *in, size_t in_len, onepath_compute_sink_t *sink);

• 流式路径：key 为样本键，in 为样本负载；
• RPC 路径：key 为查询键，in 为查询负载（可能为 NULL/0）。

输出汇 onepath_compute_emit

key 传 NULL 时自动选择输出键：流式路径用 out_key（未配则回发到样本键），RPC 路径用 查询键。可调用多次产出多条结果，或不调用以丢弃该输入。

选项 onepath_compute_opts_t

字段	含义	默认
in_key	流式输入订阅键；NULL 不启用流式	NULL
out_key	流式结果发布键；NULL 回发样本键	NULL
serve_key	RPC 应答键；NULL 不启用 RPC	NULL
fn	计算函数（必填）	—
userdata	透传给计算函数	NULL
complete	RPC 应答器完整性	1

创建 / 销毁配对

创建	销毁
onepath_compute_open	onepath_compute_close

四、所有权与内存

• onepath_compute_open 写出的句柄归调用者所有，用完须 onepath_compute_close。
• onepath_compute_emit 的 out 指针只需在调用期间有效（内部立即发布或回复）。
• 计算函数在内部线程上被调用；若访问共享状态，请自行加锁。

详见 内存管理。

五、限制与注意事项

• 本组 API 面向完整版提供；其它变体下头文件声明不可见。
• in_key 与 serve_key 必须至少配置一个，否则 onepath_compute_open 返回参数错误。
• 流式变换是无状态的逐条处理；若需窗口 / 聚合等有状态计算，请在 userdata 内自行维护 状态并加锁。

与多模冗余的区别

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