三模存储

把「订阅摄入 + 应答查询」的分布式存储样板收敛为单个 store 对象：一次 onepath_store_open() 即原生绑定发布→订阅、查询→应答、持久请求→应答三条通路。概念与设计要点见 三模存储场景。

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

数据类型

onepath_store_t

typedef struct onepath_store *onepath_store_t;

三模存储句柄（不透明）。由 onepath_store_open() 创建，onepath_store_close() 销毁。

onepath_store_emit_fn

typedef void (*onepath_store_emit_fn)(void *emit_ctx, const char *sign,
                                      const void *val, size_t len);

自定义后端在 query 内向调用方逐条投递匹配条目的发射函数。对每个匹配条目调用一次。

• 参数：
  • emit_ctx — 透传的发射上下文
  • sign — 条目键（以 null 结尾）
  • val — 条目值指针
  • len — 条目值长度（字节）

onepath_store_backend_t

typedef struct {
    void *ctx;
    int  (*put)(void *ctx, const char *sign,
                const void *val, size_t len);
    int  (*del)(void *ctx, const char *sign);
    void (*query)(void *ctx, const char *sign,
                  onepath_store_emit_fn emit, void *emit_ctx);
    void (*destroy)(void *ctx);
} onepath_store_backend_t;

自定义存储后端操作集。opts.backend 为 NULL 时使用内置内存表；非空时全部写读改由此处接管。实现须自行保证线程安全。

成员	说明
ctx	透传给各回调的后端上下文
put	写入/更新一个键值；订阅摄入到 PUT 时在摄入线程上调用
del	删除一个键；订阅摄入到 DELETE 时在摄入线程上调用
query	遍历与 sign 相交的条目，对每条调用 emit(emit_ctx, sign, val, len)；在应答线程上调用
destroy	关闭时释放后端资源，可为 NULL

线程安全

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

选项

onepath_store_opts_t

typedef struct {
    const onepath_store_backend_t *backend;
    size_t                         num_bins;
    int                            complete;
} onepath_store_opts_t;

三模存储打开选项。传 NULL 给 onepath_store_open() 即全部取默认值。

字段	类型	含义	默认
backend	const onepath_store_backend_t *	自定义后端；NULL 用内置内存表	NULL
num_bins	size_t	内置表桶数；0 取默认 256	0
complete	int	应答器完整性：1 = 完整，0 = 不完整	1

ONEPATH_STORE_OPTS_DEFAULT

#define ONEPATH_STORE_OPTS_DEFAULT { NULL, 0, 1 }

onepath_store_opts_t 的默认初始化宏。

函数

onepath_store_open

int onepath_store_open(onepath_session_t s,
                       onepath_store_t *out,
                       const char *sign,
                       const onepath_store_opts_t *opts);

打开一个三模存储，原生绑定订阅摄入与查询应答。成功后该存储即在 sign 上：订阅数据变更（PUT 写入、DELETE 删除）；应答一次性查询与持久请求器查询，返回与查询键相交的条目。写入与读取均经由三条通路完成，无需另设本地读写接口。

• 参数：
  • s — 会话句柄
  • out — 成功时写入存储句柄
  • sign — 存储负责的路标（sign），如 "demo/store/**" 下的通配键
  • opts — 打开选项，传 NULL 取全默认（内置内存表）
• 返回值：ONEPATH_OK 成功，ONEPATH_ERR_PARAM 参数无效，ONEPATH_ERR_NOMEM 内存不足，ONEPATH_ERR 声明订阅/应答失败

onepath_store_close

void onepath_store_close(onepath_store_t st);

关闭并销毁三模存储。注销订阅与应答，释放内置表或调用自定义后端的 destroy。

• 参数：st — 存储句柄，可为 NULL

onepath_store_count

size_t onepath_store_count(onepath_store_t st);

返回当前存储的条目数（只读观测）。供监控与测试用；自定义后端若未提供计数能力则返回 0。

• 参数：st — 存储句柄
• 返回值：条目数；st 为 NULL 时返回 0

内存与所有权

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

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

相关指南

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