三模存储便捷 API

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

概述

OnePath 暴露三条核心通路：发布→订阅、查询→应答、持久请求→应答。要用它们搭一个分布式 存储节点，过去需要自己拼装一个订阅者（摄入数据变更）、一个应答器（响应查询）以及一套 键值存储。三模存储便捷 API 把这套样板收敛为单个 store 对象。

一、设计要点

• 一次声明，三模绑定：onepath_store_open() 在给定键表达式上同时接好
  • 订阅摄入：收到 PUT 写入、收到 DELETE 删除；
  • 应答查询：响应一次性查询与持久请求器查询，返回与查询键相交的条目。
• 默认内置内存表：opts 传 NULL 即用内置线程安全键值表，二进制安全。
• 可插自定义后端：通过 opts.backend 注入自有 / 持久化存储，把摄入与查询接到自有 实现之上。
• 写读统一走通路：写入由发布方经发布→订阅完成，读取由查询方经查询→应答完成；存储 对象本身不提供本地读写接口，只提供只读的条目计数用于观测。

二、快速开始

#include <onepath.h>
#include <onepath_store.h>

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

    /* 在 demo/store 下的通配键上启动三模存储 (默认内置内存表) */
    onepath_store_t st;
    onepath_store_open(s, &st, "demo/store/**", NULL);

    /* 此后: 任意节点 onepath_put 到匹配键即被存储,
     *       任意节点 onepath_get 该键即可读回。 */

    onepath_store_close(st);
    onepath_close(s);
    return 0;
}

配套示例程序 onepath_store_node（store / put / get / del 四角色）给出完整可运行版本。

三、API 参考

int    onepath_store_open(onepath_session_t s, onepath_store_t *out,
                          const char *keyexpr, const onepath_store_opts_t *opts);
void   onepath_store_close(onepath_store_t st);
size_t onepath_store_count(onepath_store_t st);

函数	说明
onepath_store_open(s, &out, keyexpr, opts)	打开三模存储；opts=NULL 取全默认（内置内存表）
onepath_store_close(st)	关闭并销毁；注销订阅与应答，释放后端；NULL 安全
onepath_store_count(st)	返回当前条目数（只读观测）；自定义后端返回 0

选项 onepath_store_opts_t

字段	含义	默认
backend	自定义后端 ops；NULL 用内置内存表	NULL
num_bins	内置表桶数	0 → 256
complete	应答器完整性（1=完整）	1

自定义后端 onepath_store_backend_t

成员	调用时机	说明
ctx	—	透传给各回调的上下文
put(ctx, key, val, len)	订阅摄入到 PUT 时	写入 / 更新一个键值
del(ctx, key)	订阅摄入到 DELETE 时	删除一个键
query(ctx, keyexpr, emit, emit_ctx)	收到查询时	遍历与 keyexpr 相交的条目，对每条调用 emit(emit_ctx, key, val, len)
destroy(ctx)	onepath_store_close 时	释放后端资源，可为 NULL

线程安全

put/del 在订阅摄入线程上调用，query 在应答线程上调用；自定义后端须自行保证线程 安全（内置内存表已自带锁）。

创建 / 销毁配对

创建	销毁
onepath_store_open	onepath_store_close

四、所有权与内存

• onepath_store_open 写出的句柄归调用者所有，用完须 onepath_store_close。
• 内置内存表对传入的键 / 值做拷贝；自定义后端的拷贝策略由实现自行决定。
• 自定义后端 query 中 emit 的 val 指针只需在 emit 调用期间有效（内部会立即作为 应答发出）。

详见 内存管理。

五、限制与注意事项

• 本组 API 面向完整版提供；其它变体下头文件声明不可见。
• 应答只返回键与值；若需携带编码 / 元信息，请在值内自行编排。
• 存储容量受进程内存约束；大规模或需持久化时请通过 opts.backend 接入自有后端。
• 摄入是异步的：发布方写入后，存储侧经订阅线程入库存在毫秒级传播延迟，随后查询即可读回。

与多模冗余的区别

三模存储是单节点三通路便捷封装。若需要多副本投票的冗余容错，见 多模冗余 XMR——两者正交、可叠加。