前言

传统的链表实现虽然是 wait‑free，但其指针追逐和缓存未命中的问题让性能大打折扣。若业务允许使用有界队列，环形数组则能提供更优的内存连续性、零分配和更高的 cache hit 率。

• 内存连续CPU prefetch 友好，cache 命中率远高于链表。
• 零分配预先分配缓冲区，无运行时堆对象。老实说，
• Try 系列是 wait‑free*：入队/出队在固定步数内完成。无自旋、无重试，
• 阻塞版用有界自旋替代 runtime 调度适合高频场景，不会触发 goroutine 阻塞。

一、方案选型：环形数组 vs 链表

二、数据结构

队列主体

type SPSCQueue struct {
// --- 生产者独占字段 ---
head atomic.Uint64
_padding0 byte
tailCache uint64
_padding1 byte
// --- 使用者独占字段 ---
tail atomic.Uint64
_padding2 byte
headCache uint64
_padding3 byte
// --- 共享状态字段 ---
closed atomic.Bool
_padding4 byte
// --- 只读常量字段 ---
mask uint64
buffer T
}

五个 cache line padding 把生产者的 使用者的 与共享的 /全局状态隔开。SPSC 场景下每侧只有一个线程，它们访问不同字段即可避免伪共享。

tailCache / headCache 调整

# 本地缓存对端游标，避免每次都做原子读 #

• 生产者维护 tailCache：上次读到的 tail 值。判满时先比缓存值，如果不足再做原子读。
• 使用者维护 headCache：上次读到的 head 值。其实，判空时先比缓存值，如果不足再做原子读。

效果是高频入队大部分判满操作只需比较本地 tailCache。无需跨核同步，从而将原子操作降到最低限度。

三、初始化：容量向上取整为 2 的幂

func NewSPSCQueue *SPSCQueue {
if capacity  maxCapacity {
capacity = maxCapacity
}
if!isPowerOfTwo {
capacity = nextPowerOfTwo
}
return &SPSCQueue{
buffer这方面，make,mask: uint64。}
}

mask = capacity - 1 → pos & mask 替代 %capacity；位运算速度提高十倍以上，

head 和 tail 是单调递增 unsigned int，不会回绕。老实说，判空用 head == tail；判满用 head - tail>= capacity；两者永不混淆，

四、入队 – 阻塞版本 单个入队

func Enqueue bool {
if q.closed.Load { return false }
head := q.head.Load
capacity := q.mask + 1
tailLimit := q.tailCache + capacity
if head>= tailLimit {
// 缓存不够，需要读取真实尾部位置
realTail := q.tail.Load
if head>= realTail+capacity {
// 空间不足，自旋等待并退避以防 CPU 空转浪费
spinCount := uint32
for {
if q.closed.Load { return false }
realTail = q.tail.Load
if head < realTail+capacity { break }
                zbackoff.Backoff(spinCount,
                    zbackoff.BackoffMax,
                    zbackoff.BackoffMin,
                    *time.Microsecond)
                spinCount++
            }
        }
        q.tailCache = realTail   // 更新本地缓存后继续执行写入逻辑
    }
    q.buffer = item        // 写数据至缓冲区
    q.head.Store            // Release 屏障保证写完成后发布索引
    return true
}

• The only write to 。thus reading it once is sufficient.
• The local ,being a plain variable accessed only by producer thread,requires no atomics.
• If space is insufficient a bounded spin+backoff loop ensures that CPU is not wasted while waiting for consumer progress.
• The final Store includes a Release barrier guaranteeing that data write happens before publishing index.

批量入队

func EnqueueBatch bool {
// 一样先执行判满逻辑…offset := head & q.mask // 当前写位置偏移量
toEnd := capacity - offset // 可写直至剩余空间
if count <= toEnd { 
    copy          // 一次性拷贝 
} else { 
    copy             // 回绕第一段拷贝 
    copy                   // 回绕第二段拷贝 
} 
q.head.Store                           // Release barrier 发布新头部位置 
return true 
}


用 Go 内置 copy 而不是手动循环赋值，可被编译器调整为快速块复制；

当 head 接近缓冲区末尾时需要拆成两段拷贝以处理回绕。怎么说呢，

func Dequeue {
tail的观点是。=q.tail.Load
var zero T
if tail>= q.headCache{ /* 看是否需要更新头部缓存 */
realHead:=q.head.Load /* 原子读取真实头部位置 */
if tail <> realHead{ /* 队列为空 */
spinCount:=uint32
for{
realHead=q.head.Load
if tail <>realHead{break} /* 使用者检测到新的数据后退出 */
if q.closed.Load{
if q.head.Load <>tail{return zero,false} /* 已关闭且空 */
}
zbackoff.Backoff;
怎么说呢，spinCount++
}
}
q.headCache=realHead /* 更新本地缓存后继续消费 */
}
说到index，=tail&q.mask /* 实际缓冲区索引 */
说到val，=q.buffer
q.buffer=zero /* 清零释放引用帮助 GC */
q.tail.Store /* Release barrier 确保清零之后才发布索引 */
return val。true /* 成功读取一条消息 */


}



清零 buffer 对于包含指针类型非常关键，否则旧引用可能被 GC 错过。

最终的 Store 包含 Release 障碍。即使使用者是唯一读方，也能保证正确的内存序。


批量出队 + GC 清理 
func consumeBatch int{
offset := tail&q.mask
capacity := q.mask+1
toEnd := capacity-offset
var zero T
if batchSize<=toEnd{                      /* 一段拷贝 */  
   copy
   for i:=uint64;i


}else{ /* 回绕两段拷贝 + 两段清零 */
copy
remaining:=batchSize-toEnd
copy
for i:=uint64;其实，i
}
for i:=uint64;老实说，i
}
}

q.tail.Store
return int
}


回绕场景必须彻底清零。否则旧数据残留会导致 GC 泄漏。

六、非阻塞 API：TryEnqueue / TryDequeue 

阻塞版适合“必须写/读”的场景，而某些实时或尾部丢弃策略要求不能等候返回立即失败/成功才能决定后续动作！''，提供了 Try 系列：

func TryEnqueue bool{
if!isFull{ return false } /* 判满直接返回 false */
copy
q.head.Store
return true
}


func TryDequeueBatch{
if!isEmpty{return ...} /* 判空直接返回对应语义 */
readItems
return n。true
}


TryDequeueBatch 的返回语义遵循 channel 的 ,ok 模式：


成功读取 n 条记录；

当前空但未关闭，可以重试；

已关闭且空，不应再尝试读取。怎么说呢，

这使调用方可以轻松判断“已结束”与“暂时为空”的区别。

七、Close 语义 
func Close{
q.closed.Store
}`
*Close*仅设置一个标志——不主动通知生产者，只需由调用方统一协调。不过，与 UnboundedSPSC 的 Close 不同的是后者还需把本地回收池归还。而 SPSCQueue 的 buffer 已经预分配，无需额外清理。关闭后的观点是，


writes的观点是。Enqueue/EnqueueBatch immediately fail.

`reads`: existing data remains readable until queue becomes empty . After empty Dequeue returns `` signaling end.


八、性能特点 



TryEnqueue/TryDequeue 全程仅使用 atomic.Uint64.Load/Store无 CAS，无自旋，即真正 wait‑free 固定步数完成。• 阻塞版在满/空时自旋等待。但自旋是有界且带退避，以避免 CPU 空转；其实，仍然远比更好 channel 的 runtime 调度开销。• 环形数组具备极佳 cache 局部性，在批量操作下可利用硬件预取接近直接 slice 操作。• tailCache/headCache 缓存进一步减少了跨核原子访问，仅在需要更新时才进行一次 atomic read。• 这些调整共同提高吞吐率同时保持低延迟。




我会继续改进文章内容，让它更加贴近使用者痛点还有实际开发经验。如果你还有其它需求或者想了解更细节，请随时告诉我！说起来，


The above markdown has some placeholders like ...;y are not actual code but illustrate concept. If needed actual code should replace placeholders accordingly.

仓库github.com/aiyang-zh/z…源码spsc.go
交流群QQ 群
公众号Zhenyi‑io