三模计算

注册单个计算函数，一次 onepath_compute_open() 即把它原生接到两路：流式变换（发布→订阅）与按需 RPC（查询→应答）。概念与设计要点见 三模计算场景。

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

数据类型

onepath_compute_t

typedef struct onepath_compute *onepath_compute_t;

三模计算句柄（不透明）。由 onepath_compute_open() 创建，onepath_compute_close() 销毁。

onepath_compute_sink_t

typedef struct onepath_compute_sink onepath_compute_sink_t;

计算结果输出汇（不透明）。计算函数经它产出结果：流式路径发射到 out_sign，RPC 路径回复当前查询。

onepath_compute_fn

typedef void (*onepath_compute_fn)(void *userdata, const char *sign,
                                   const void *in, size_t in_len,
                                   onepath_compute_sink_t *sink);

计算函数。对一条输入产出结果，经 onepath_compute_emit() 发射；不发射即丢弃该输入。

• 参数：
  • userdata — 透传的用户上下文
  • sign — 输入键（以 null 结尾）。流式路径为样本键，RPC 路径为查询键
  • in — 输入数据指针，可能为 NULL
  • in_len — 输入数据长度（字节）
  • sink — 结果输出汇

选项

onepath_compute_opts_t

typedef struct {
    const char        *in_sign;
    const char        *out_sign;
    const char        *serve_sign;
    onepath_compute_fn fn;
    void              *userdata;
    int                complete;
} onepath_compute_opts_t;

三模计算打开选项。in_sign 与 serve_sign 至少配置其一；都配则两路同开。

字段	类型	含义	默认
in_sign	const char *	流式输入订阅键；NULL 不启用流式变换	NULL
out_sign	const char *	流式结果发布键；NULL 回发到样本键	NULL
serve_sign	const char *	RPC 应答键；NULL 不启用按需 RPC	NULL
fn	onepath_compute_fn	计算函数（必填）	—
userdata	void *	透传给计算函数的上下文	NULL
complete	int	RPC 应答器完整性：1 = 完整，0 = 不完整	1

ONEPATH_COMPUTE_OPTS_DEFAULT

#define ONEPATH_COMPUTE_OPTS_DEFAULT { NULL, NULL, NULL, NULL, NULL, 1 }

onepath_compute_opts_t 的默认初始化宏。

函数

onepath_compute_open

int onepath_compute_open(onepath_session_t s,
                         onepath_compute_t *out,
                         const onepath_compute_opts_t *opts);

打开一个三模计算，把计算函数原生接到流式变换与按需 RPC。按 opts 启用：配了 in_sign 即声明订阅做 sub→fn→pub 流式变换；配了 serve_sign 即声明应答器做 fn(query)→reply 按需计算。

• 参数：
  • s — 会话句柄
  • out — 成功时写入计算句柄
  • opts — 打开选项（必填；fn 与 in_sign/serve_sign 之一必配）
• 返回值：ONEPATH_OK 成功，ONEPATH_ERR_PARAM 参数无效，ONEPATH_ERR_NOMEM 内存不足，ONEPATH_ERR 声明订阅/应答失败

onepath_compute_close

void onepath_compute_close(onepath_compute_t c);

关闭并销毁三模计算。注销订阅与应答，释放内部资源。

• 参数：c — 计算句柄，可为 NULL

onepath_compute_emit

int onepath_compute_emit(onepath_compute_sink_t *sink,
                         const char *sign,
                         const void *out, size_t len);

在计算函数内产出一条结果。可调用 0 次（丢弃）或多次（一进多出）。

• 参数：
  • sink — 传入计算函数的输出汇
  • sign — 结果键；传 NULL 时自动选择：流式路径用 out_sign（未配则用样本键），RPC 路径用查询键
  • out — 结果数据指针
  • len — 结果数据长度（字节）
• 返回值：ONEPATH_OK 成功，ONEPATH_ERR_PARAM 参数无效

内存与所有权

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

资源销毁顺序与通用约定见 内存管理。

相关指南

• 三模计算场景 — 设计要点、快速开始与限制
• 会话管理 — onepath_compute_open() 所需的会话句柄
• 发布与订阅 — 流式变换使用的发布/订阅原语
• 内存管理 — 句柄销毁顺序与生命周期