ubs-atomic 配置说明 ​

本文档说明 ubs-atomic 的构建配置项和运行时配置项，以及各配置项的取值范围、默认值和配置建议。

构建配置 ​

构建类型 ​

通过 build.sh -T <type> 指定构建类型，默认为 Release。

表 1 构建类型说明

build.sh 常用参数 ​

表 2 build.sh 参数说明

CMake 缓存变量 ​

表 3 CMake 变量说明

平台相关编译选项 ​

• ARM64（aarch64）平台自动附加 -march=armv8-a+lse，启用 LSE 原子指令。
• x86_64 平台不传入该选项，可直接本地编译（不在默认配套范围）。

安全编译选项 ​

Release 与 Debug 构建均默认启用安全编译选项（详见安全说明）。

资源规格配置 ​

锁对象共享内存大小 ​

锁对象直接构建在调用方提供的共享内存上，各锁对象的最小共享内存需求如下：

表 4 锁对象共享内存需求

建议为每个锁对象预留独立且对齐的共享内存区域，所有节点使用相同的地址布局。

共享内存规划 ​

ubs-atomic 不管理共享内存生命周期，调用方负责创建、映射、清零和销毁。共享内存域配置可参考 sample_code/share_mem/ubsm_region.conf：

request_size_mb=1024
hosts=computer01,computer02

运行时配置 ​

分布式读写锁配置 ​

锁配置（ub_lock_config_t，创建时固定） ​

表 5 ub_lock_config_t 配置项

加锁策略（ub_lock_policy_t，每次加锁可变） ​

表 6 ub_lock_policy_t 配置项

锁模式兼容性 ​

表 7 锁模式兼容矩阵

互斥锁/自旋锁超时 ​

ub_mutex_lock、ub_spin_lock 的 timeout_ms 参数为 0 时使用默认值 10000ms。自旋锁仅建议用于极短临界区，超时时间不宜设置过大。

通信队列配置 ​

全局通信配置（ub_comm_conf_t） ​

表 8 ub_comm_conf_t 配置项

Ring 配置（ub_ring_desc_t） ​

表 9 ub_ring_desc_t 配置项

拥塞阈值 ​

通过 ub_comm_queue_set_congestion_threshold 配置本地 Ring 拥塞阈值百分比：

• 取值范围 0~100，默认 80（即 80% 水位）。
• 0 表示所有非满状态都按拥塞处理。
• 只影响当前节点本地 Ring，远端生产者通过共享 Ring 对象读取新阈值。
• 达到阈值后发送返回 UB_COMM_SEND_CONGESTED，消息仍成功入队。

队列状态 ​

表 10 队列状态说明

心跳配置（ub_comm_queue_heartbeat_config_t） ​

表 11 心跳配置项

说明：本节点观察某个 peer 的实际超时窗口为 max(timeout_ms, peer heartbeat_interval_ms × 3, check_interval_ms × 2)。

日志配置 ​

通过 ub_atomic_set_log_level 设置日志输出阈值，通过 ub_atomic_register_log_func 注册自定义日志回调（回调内不应阻塞过久，如需保存日志内容应自行拷贝）。

表 12 日志级别

保留值与全局约束 ​

表 13 保留值与约束汇总

样例配置参考 ​

锁功能验证样例的节点/共享内存配置可参考 sample_code/ub_lock/dw_lock.conf：

self=NodeA
nodes=2
lock_shm=shm_ub_lock
shm.NodeA=shm_node1_export
shm.NodeB=shm_node2_export
ip.NodeA=192.168.100.100
ip.NodeB=192.168.100.101

共享内存创建方法参见 sample_code/share_mem/README.md。