queue

裁剪与依赖

启用子模块时必须显式启用依赖宏；公共头会在依赖缺失时拒绝编译。SPSC、MPSC 和 MPMC 核心不依赖线程、锁、信号量或任务体系。

公共契约

xrtQueueCapacity 把非零最小容量向上取整到 2 次幂。支持范围为 1 到 XRT_QUEUE_MAX_CAPACITY；零容量报告 XERR_ARGUMENT，超过上限报告 XERR_RANGE。

xqueueresult 将并发流控与运行库错误分开：

xqueuebatchresult 同时返回状态和实际处理数量。批量操作允许部分成功，此时 Result 为 XQUEUE_OK，Count 小于请求数。请求数为零是无副作用的成功操作，不要求数组指针非空。

所有非空批量指针数组和单元素 Pop 输出都必须按指针对齐，并且不能与队列结构或内部环重叠。实现只检查本次实际访问的批量前缀；违反条件设置 XERR_ARGUMENT、返回 XQUEUE_ERROR，且不领取槽位、不移动游标、不写输出。公开结构的存储地址、容量、掩码或游标关系损坏时设置 XERR_STATE，不会把损坏的容量差用于环访问。

队列保存原始指针值，不拥有指针目标，也不限制空指针元素。空指针元素由 xqueueresult 与真正的空队列区分。

等待、期限和取消不是基础队列结果。后续等待包装层使用统一的 xwaitresult，不会把同步原语依赖反向引入队列核心。

SPSC

xspscqueue 只允许一个生产者执行入队、批量入队和关闭，只允许一个消费者执行弹出、批量弹出和排空。状态查询可以由其他线程调用。违反角色数量约束属于调用方错误，库无法在不损失热路径性能的情况下检测。

生产者通过 release 发布尾游标，消费者通过 acquire 取得元素；消费者以 release 发布头游标，生产者以 acquire 复用槽位。生产者必须在最后一次入队完成后调用 xrtSPSCQueueClose。消费者观察到关闭后会再次确认尾游标，因此不会把关闭发布前的最后一批元素遗漏为已排空。

MPSC

xmpscqueue 允许多个生产者并发执行入队和批量入队，只允许一个消费者执行弹出、批量弹出和排空。状态查询可以由其他线程调用。实现继承旧版 XRT 已验证的有界序列槽环，但用 32 位模运算代替旧版 64 位游标，避免 32 位目标上昂贵的 64 位原子操作。

每个槽位以 release 发布序号和元素，消费者以 acquire 取得；消费者释放槽位后，生产者才可在下一轮复用。容量上限为 2^30，因此序号差转换为有符号 32 位值时，即使游标跨越 UINT32_MAX 也不会混淆空槽、就绪槽和已越过槽。

MPSC 提供非阻塞的尝试式 API，但不声明形式化的 lock-free 进度保证：生产者取得尾部区间后若被长期挂起，唯一消费者必须等待该 FIFO 前缀发布。需要可等待、期限和取消的调用方，应使用后续同步/任务阶段提供的等待适配层，核心队列不会引入线程和同步原语依赖。

MPMC

xmpmcqueue 允许多个生产者并发入队，也允许多个消费者并发弹出。生产者热路径与 MPSC 共用同一份内部序列槽实现；消费者通过 CAS 领取头部的一个槽或一个连续批量区间。两套公开 API 分别表达不同角色合同，不要求调用方接触通用基类或函数指针。

MPMC 与 MPSC 使用相同的 32 位模序号、2^30 容量上限、release/acquire 发布关系和热游标隔离。x86 目标使用 64 字节隔离跨度，AArch64 与 PowerPC64 目标使用 128 字节隔离跨度；这是布局规则，不承诺等同于运行 CPU 的实际缓存行大小。它同样提供非阻塞尝试式 API，但不声明形式化的 lock-free 进度保证：已经取得头尾区间后暂停的线程可能暂时阻塞 FIFO 前缀或槽位复用。

示例

可运行范例位于 examples/containers/queue_spsc/main.c。

MPSC 的批量范例位于 examples/containers/queue_mpsc/main.c。

MPMC 的批量范例位于 examples/containers/queue_mpmc/main.c，多线程竞争由 tests/containers/test_queue_mpmc_threads.c 完整演示。

性能门禁

dev/bench/queue/bench_queue_pointer.c 测量 SPSC、MPSC、MPMC 的单元素与批量吞吐量，dev/bench/queue/bench_queue_latency.c 测量 MPSC、MPMC 的平均延迟、P50、P95、P99 与消费者公平性。两者直接编译当前 single/xrt.h，不依赖网络头或网络链接库。

Windows 与 Linux runner 位于 dev/bench/run_queue_*。历史 20260324、20260325 报告只作为旧版比较证据；XRT 2 的发布结论必须使用固定主机、编译器、矩阵和串行采样重新生成，不能把诊断用 CPU 绑定结果混入默认基线。