共享内存（SHM）

共享内存（SHM）API 提供 OnePath 的同机零拷贝传输能力，分两条通道：配置里一次开启的「同机自动 SHM」，以及对任意大小消息强制零拷贝的「手动 SHM 池」。

可用性：完整版（Full）专属；精简版（Tiny）头文件中相关声明被剔除，误用会在编译期报错。 完整的概念说明、阈值调优与性能特征见专题指南 同机零拷贝共享内存（SHM）。

数据类型

onepath_shm_pool_t

typedef struct onepath_shm_pool *onepath_shm_pool_t;

共享内存池句柄（仅 Full 变体）。由 onepath_shm_pool_create 创建，用于显式分配零拷贝发布缓冲；不再使用时由 onepath_shm_pool_destroy 销毁。NULL 表示无效句柄。

选项

onepath_shm_opts_t

typedef struct {
    size_t message_size_threshold;  /* 触发 SHM 的最小消息字节; 0 = 所有消息都走 SHM */
    size_t pool_size;               /* SHM 池字节; 0 = 引擎默认 16 MB */
} onepath_shm_opts_t;

「同机自动 SHM」的配置参数，传给 onepath_config_enable_shm。任意字段填 0 表示该项取引擎默认值。

字段	类型	含义	默认
message_size_threshold	size_t	触发零拷贝缓冲的最小消息字节；0 = 所有消息都走 SHM	3072
pool_size	size_t	SHM 池字节；0 = 引擎默认	16 MB

阈值只决定缓冲类型

阈值只决定单条消息是否走零拷贝缓冲，不改变同机会话间是否经过网络栈。默认 3072 通常是安全选择，无需为小包特意调低。详见 SHM 指南。

函数

自动 SHM 配置

onepath_config_enable_shm

仅 Full 变体可用

该接口在 Tiny 变体下于头文件中被剔除，误用会在编译期报错。

int onepath_config_enable_shm(onepath_config_t cfg,
                              const onepath_shm_opts_t *opts);

启用同机自动共享内存传输。开启后，同一台机器上的不同 OnePath 会话之间，大于等于阈值的消息会自动经共享内存零拷贝传输；用户继续使用普通发布 / 订阅 API，无需手动管理内存池。跨机会话之间自动回退到普通网络传输。

• 参数：
  • cfg — 配置句柄
  • opts — 高级参数；传 NULL 取全默认。字段填 0 表示该项用默认
• 返回值：ONEPATH_OK 成功，ONEPATH_ERR_PARAM（cfg 为空），ONEPATH_ERR（写入失败）
• 注意：需在打开会话前的配置里调用一次；典型流程见 SHM 指南

onepath_config_t cfg;
onepath_config_new(&cfg);
onepath_config_enable_shm(cfg, NULL);          /* 全默认：阈值 3072 字节，池 16 MB */
onepath_open_with_config(&session, cfg);
onepath_config_destroy(cfg);

手动 SHM 池

手动 SHM 池从内存池显式分配零拷贝缓冲，用于对任意大小消息强制确定性零拷贝。通常只需同机自动 SHM；手动池保留为极致延迟 / 吞吐基准的高级通道。

onepath_shm_pool_create

int onepath_shm_pool_create(onepath_session_t s,
                            onepath_shm_pool_t *out,
                            size_t pool_size);

创建共享内存池，用于零拷贝发布。

• 参数：
  • s — 会话句柄（当前未使用，保留参数）
  • out — 成功时写入 SHM 池句柄
  • pool_size — 内存池大小（字节）
• 返回值：ONEPATH_OK 成功
• 注意：使用前需先在配置中调用 onepath_config_enable_shm；不再使用时由 onepath_shm_pool_destroy 销毁

onepath_publisher_put_shm

int onepath_publisher_put_shm(onepath_publisher_t pub,
                              onepath_shm_pool_t pool,
                              const void *data, size_t len);

通过 SHM 零拷贝发布数据：数据先拷贝到 SHM 缓冲区，然后零拷贝发送。若 SHM 分配失败，自动回退为普通拷贝发送。

• 参数：pub — 发布者句柄；pool — SHM 池句柄；data — 数据指针；len — 数据长度（字节）
• 返回值：ONEPATH_OK 成功

onepath_put_shm

int onepath_put_shm(onepath_session_t s, const char *sign,
                    onepath_shm_pool_t pool,
                    const void *data, size_t len);

通过 SHM 一次性写入（无需先声明发布者）。

• 参数：s — 会话句柄；sign — 路标（sign）字符串；pool — SHM 池句柄；data — 数据指针；len — 数据长度（字节）
• 返回值：ONEPATH_OK 成功

onepath_shm_pool_destroy

void onepath_shm_pool_destroy(onepath_shm_pool_t pool);

销毁共享内存池。

• 参数：pool — SHM 池句柄，可为 NULL
• 注意：确保所有使用该池的发布已完成后再销毁；NULL 可安全传入

内存与所有权

创建 / 获取	销毁	所有权说明
onepath_shm_pool_create	onepath_shm_pool_destroy	池句柄归调用者所有，须在会话关闭前销毁

onepath_config_enable_shm 仅写入配置项，不分配 SHM 资源；池的实际创建由 onepath_shm_pool_create 完成。销毁顺序遵循「后创建先销毁」：先销毁所有发布者等使用池的资源，再销毁池，最后关闭会话。完整规则见 内存管理。

相关指南

• 同机零拷贝共享内存（SHM） — 概念说明、阈值调优、跨机行为与性能特征