ubs-atomic 接口说明 ​

说明 ​

ubs-atomic 对外提供 C ABI 接口，当前对外能力包括：

• 分布式读写锁（S/SX/X 模式）、分布式互斥锁、分布式自旋锁
• 分布式共享内存通信队列
• 分布式事务资源原子操作（含内存屏障）

头文件列表 ​

开发代码时所需的头文件如表 1所示。

表 1 头文件列表

三个头文件均使用 extern "C" 声明，C/C++ 程序均可直接引用；同一组通用日志接口（ub_atomic_register_log_func、ub_atomic_set_log_level）在三个头文件中均有暴露，链接时指向同一实现，任一头文件引入即可使用。

设置进程运行环境 ​

• 库和头文件的安装路径取决于软件包格式：

• RPM 安装产物位于系统库目录，通常无需额外设置 LD_LIBRARY_PATH；源码构建部署时，需将产物目录加入 LD_LIBRARY_PATH：

  bash

  export LD_LIBRARY_PATH=/path/to/lib:$LD_LIBRARY_PATH

• 编译链接示例：

  bash

  gcc my_app.c -I/usr/include -lubs-atomic -lpthread -lrt -o my_app

• 多进程/多节点场景下，所有参与方应使用相同版本的 libubs-atomic.so 和头文件，避免共享内存布局不一致导致的未定义行为。

• 组件本身不创建、不销毁共享内存对象，调用方需自行创建并映射共享内存（可参考 sample_code/share_mem），并保证在接口使用期间内存保持有效。

• 事务资源接口要求目标地址 8 字节对齐。

接口 ​

通用日志 ​

ub_atomic_register_log_func ​

接口功能

注册用户自定义日志函数。库内部产生日志时会调用该函数，未注册时使用内部默认日志行为。

接口格式

void ub_atomic_register_log_func(ub_atomic_log_func func);

参数说明

返回值

无。

ub_atomic_set_log_level ​

接口功能

设置日志输出阈值，低于阈值的日志不会输出。

接口格式

int ub_atomic_set_log_level(int level);

参数说明

返回值

分布式读写锁 ​

ub_rw_lock_create ​

接口功能

初始化分布式读写锁。在调用方提供的共享内存上构建锁对象，锁配置在创建时固定。

接口格式

void ub_rw_lock_create(ub_rw_lock_t *lock, const ub_lock_config_t *config, const ub_location_t *location);

参数说明

返回值

无。参数无效时直接返回。

ub_rw_lock_free ​

接口功能

释放分布式读写锁关联的本节点资源。

接口格式

void ub_rw_lock_free(ub_rw_lock_t *lock, const ub_location_t *location);

参数说明

返回值

无。

ub_rw_lock_s_lock / ub_rw_lock_x_lock / ub_rw_lock_sx_lock ​

接口功能

分别获取共享（S）锁、独占（X）写锁、共享排他（SX）锁。

接口格式

ub_lock_result_t ub_rw_lock_s_lock(ub_rw_lock_t *lock, const ub_lock_policy_t *policy, const ub_location_t *location);
ub_lock_result_t ub_rw_lock_x_lock(ub_rw_lock_t *lock, const ub_lock_policy_t *policy, const ub_location_t *location);
ub_lock_result_t ub_rw_lock_sx_lock(ub_rw_lock_t *lock, const ub_lock_policy_t *policy, const ub_location_t *location);

参数说明

返回值

ub_rw_lock_s_unlock / ub_rw_lock_x_unlock / ub_rw_lock_sx_unlock ​

接口功能

分别释放共享（S）锁、独占（X）写锁、共享排他（SX）锁。释放模式应与加锁模式匹配。

接口格式

ub_lock_result_t ub_rw_lock_s_unlock(ub_rw_lock_t *lock, const ub_lock_policy_t *policy, const ub_location_t *location);
ub_lock_result_t ub_rw_lock_x_unlock(ub_rw_lock_t *lock, const ub_lock_policy_t *policy, const ub_location_t *location);
ub_lock_result_t ub_rw_lock_sx_unlock(ub_rw_lock_t *lock, const ub_lock_policy_t *policy, const ub_location_t *location);

参数说明

返回值

ub_rw_lock_recover ​

接口功能

对异常失败进程持有或半写入的锁状态进行恢复清理。

接口格式

ub_lock_result_t ub_rw_lock_recover(ub_rw_lock_t *lock, const uint32_t process_id, const ub_location_t *location);

参数说明

返回值

ub_rw_lock_query_holder ​

接口功能

查询本节点用于锁重建的最小持有者状态。

接口格式

ub_lock_result_t ub_rw_lock_query_holder(ub_rw_lock_t *lock, const ub_location_t *location, ub_lock_query_result_t *result);

参数说明

返回值

ub_rw_lock_rebuild ​

接口功能

根据集群各节点的查询结果，在新的共享内存锁对象上重建锁状态。

接口格式

ub_lock_result_t ub_rw_lock_rebuild(ub_rw_lock_t *old_lock, ub_rw_lock_t *new_lock, const ub_lock_rebuild_info_t *rebuild_info, const ub_location_t *location);

参数说明

返回值

分布式互斥锁 ​

ub_mutex_lock_create ​

接口功能

初始化分布式互斥锁。

接口格式

void ub_mutex_lock_create(ub_mutex_lock_t *lock);

参数说明

返回值

无。参数无效时直接返回。

ub_mutex_lock_free ​

接口功能

释放分布式互斥锁关联资源。

接口格式

void ub_mutex_lock_free(ub_mutex_lock_t *lock);

参数说明

返回值

无。

ub_mutex_lock ​

接口功能

获取分布式互斥锁。

接口格式

ub_lock_result_t ub_mutex_lock(ub_mutex_lock_t *lock, time_ms_t timeout_ms, const ub_location_t *location);

参数说明

返回值

ub_mutex_unlock ​

接口功能

释放分布式互斥锁。

接口格式

ub_lock_result_t ub_mutex_unlock(ub_mutex_lock_t *lock, const ub_location_t *location);

参数说明

返回值

分布式自旋锁 ​

ub_spin_lock_init ​

接口功能

初始化分布式自旋锁。

接口格式

void ub_spin_lock_init(ub_spin_lock_t *lock);

参数说明

返回值

无。参数无效时直接返回。

ub_spin_lock ​

接口功能

获取分布式自旋锁。等待期间不阻塞线程，持续尝试获取，适用于极短临界区。

接口格式

ub_lock_result_t ub_spin_lock(ub_spin_lock_t *lock, time_ms_t timeout_ms, const ub_location_t *location);

参数说明

返回值

ub_spin_unlock ​

接口功能

释放分布式自旋锁。

接口格式

ub_lock_result_t ub_spin_unlock(ub_spin_lock_t *lock, const ub_location_t *location);

参数说明

返回值

分布式通信队列 ​

ub_comm_queue_init ​

接口功能

初始化共享内存通信实例：创建本地 Ring，发布节点状态，并启动后台分发线程。

接口格式

int ub_comm_queue_init(ub_shm_comm_t *handle, ub_shm_area_t *init_region, ub_ring_region_map_t *ring_regions, ub_comm_conf_t *conf);

参数说明

返回值

说明：

• 第一个初始化成功的通信实例会被内部标记为分布式锁使用的实例。
• 集群最大节点数为 16；priority 取值 0~7，其中 0 为内部保留，业务 Ring 配置不得使用。
• 初始化成功后必须调用 ub_comm_queue_deinit 释放实例。

ub_comm_queue_deinit ​

接口功能

反初始化通信实例，停止后台线程并释放实例对象。

接口格式

int ub_comm_queue_deinit(ub_shm_comm_t *handle);

参数说明

返回值

ub_comm_queue_send ​

接口功能

向目标节点指定优先级 Ring 发送业务消息。

接口格式

int ub_comm_queue_send(ub_shm_comm_t *handle, const message_t *msg);

参数说明

返回值

ub_comm_queue_recv ​

接口功能

接收消息。当前主推的收包方式是注册回调（见 ub_comm_queue_register_process_func），不建议业务直接依赖本接口收包。

接口格式

int ub_comm_queue_recv(ub_shm_comm_t *handle, void *buffer, uint32_t length);

参数说明

返回值

ub_comm_queue_get_status ​

接口功能

查询指定节点、指定优先级 Ring 的流控状态快照。

接口格式

int ub_comm_queue_get_status(ub_shm_comm_t *handle, uint8_t node_id, uint8_t priority, ub_comm_queue_status_t *status);

参数说明

返回值

说明：返回的是原子快照，适合维测和流控估计，不提供强一致队列长度语义。

ub_comm_queue_set_congestion_threshold ​

接口功能

设置当前节点本地指定业务 Ring 的拥塞阈值百分比。远端生产者写入该 Ring 时会通过共享 Ring 对象读取到新阈值。

接口格式

int ub_comm_queue_set_congestion_threshold(ub_shm_comm_t *handle, uint8_t priority, uint32_t congestion_threshold_percent);

参数说明

返回值

ub_comm_queue_config_heartbeat ​

接口功能

设置和/或查询当前通信实例的本地心跳配置。

接口格式

int ub_comm_queue_config_heartbeat(ub_shm_comm_t *handle, const ub_comm_queue_heartbeat_config_t *request, ub_comm_queue_heartbeat_config_t *effective);

参数说明

返回值

说明：本节点观察某个 peer 的实际超时窗口为 max(timeout_ms, peer heartbeat_interval_ms * 3, check_interval_ms * 2)，用于避免节点间心跳配置不一致导致误判。

ub_comm_queue_check_ready ​

接口功能

查询指定节点是否已完成通信队列初始化。

接口格式

bool ub_comm_queue_check_ready(ub_shm_comm_t *handle, const uint8_t node_id);

参数说明

返回值

ub_comm_queue_register_process_func ​

接口功能

为指定业务消息类型注册处理回调。

接口格式

int ub_comm_queue_register_process_func(ub_shm_comm_t *handle, uint8_t msg_type, ub_func_type_t func_type, ub_callback_t func, void *ctx);

参数说明

返回值

说明：同一个 msg_type 重复注册会覆盖旧回调；已被分发线程取出或已投递线程池的消息可能仍使用旧回调执行。

分布式事务资源 ​

ub_dist_tx_res_init ​

接口功能

初始化分布式事务资源原子值，将目标值置为 0。

接口格式

int ub_dist_tx_res_init(uint64_t *handle);

参数说明

返回值

ub_dist_tx_res_set ​

接口功能

设置分布式事务资源的值。

接口格式

int ub_dist_tx_res_set(uint64_t *handle, uint64_t value);

参数说明

返回值

ub_dist_tx_res_get ​

接口功能

读取分布式事务资源当前值。

接口格式

int ub_dist_tx_res_get(uint64_t *handle, uint64_t *out_val);

参数说明

返回值

ub_dist_tx_res_fetch_add ​

接口功能

对分布式事务资源执行原子加法，并返回加法前的旧值。使用 acq_rel 语义。

接口格式

int ub_dist_tx_res_fetch_add(uint64_t *handle, uint64_t value, uint64_t *out_val);

参数说明

返回值

ub_dist_tx_res_add ​

接口功能

对分布式事务资源执行原子加法（无 fetch 版本），不返回旧值。使用 release 语义，可优化为更轻量指令，适用于仅需累加不需旧值的场景。

接口格式

int ub_dist_tx_res_add(uint64_t *handle, uint64_t value);

参数说明

返回值

ub_dist_tx_res_fetch_xor ​

接口功能

对分布式事务资源执行原子异或并返回旧值。使用 acq_rel 语义。

接口格式

int ub_dist_tx_res_fetch_xor(uint64_t *handle, uint64_t value, uint64_t *out_val);

参数说明

返回值

ub_dist_tx_res_compare_exchange ​

接口功能

对分布式事务资源执行原子比较并交换（CAS）。若 handle 指向的值等于 *expected，则原子替换为 desired；否则将当前值写入 *expected。使用 acq_rel（成功）/ acquire（失败）语义，strong 语义，不发生伪失败。

接口格式

int ub_dist_tx_res_compare_exchange(uint64_t *handle, uint64_t *expected, uint64_t desired, int *success);

参数说明

返回值

ub_dist_tx_res_fence ​

接口功能

统一内存屏障接口。根据 order 参数插入对应强度的编译器屏障和硬件屏障，所有变体均包含 compiler barrier。

接口格式

int ub_dist_tx_res_fence(ub_fence_order_t order);

参数说明

返回值

错误码 ​

通用日志接口返回码 ​

分布式锁返回码 ​

通信队列返回码 ​

事务资源返回码 ​

使用样例 ​

完整的可编译样例参见仓库 sample_code/ 目录：