ds-ring-buffer-lockfree

Answer

Design – A lock-free SPSC (single producer, single consumer) ring buffer. The buffer is a fixed-size slice rounded up to a power of two. Head and tail are monotonically increasing uint64 counters manipulated only via atomic.LoadUint64/atomic.StoreUint64:

• Producer: reads head (to check fullness), writes the slot, then stores tail+1 (release).
• Consumer: reads tail (to check emptiness), reads the slot, then stores head+1 (release).

Because Go's atomic operations provide sequential consistency, the release store of tail guarantees the slot write is globally visible before the consumer sees the advanced tail. Similarly, the release store of head guarantees the slot read completes before the producer reuses that slot.

Key implementation (ringbuffer.go):

type RingBuffer struct {
    buffer   []interface{}
    capacity uint64
    mask     uint64 // capacity-1 (power of two)
    head     uint64 // written by consumer, read by producer
    tail     uint64 // written by producer, read by consumer
}

func (rb *RingBuffer) Enqueue(item interface{}) bool {
    tail := atomic.LoadUint64(&rb.tail)
    head := atomic.LoadUint64(&rb.head)
    if tail-head >= rb.capacity {
        return false // full
    }
    rb.buffer[tail&rb.mask] = item
    atomic.StoreUint64(&rb.tail, tail+1)
    return true
}

func (rb *RingBuffer) Dequeue() (interface{}, bool) {
    head := atomic.LoadUint64(&rb.head)
    tail := atomic.LoadUint64(&rb.tail)
    if head == tail {
        return nil, false // empty
    }
    idx := head & rb.mask
    item := rb.buffer[idx]
    rb.buffer[idx] = nil // help GC
    atomic.StoreUint64(&rb.head, head+1)
    return item, true
}

Wrap-around – uint64 counters naturally overflow (after 2⁶⁴ operations), and tail - head remains correct because unsigned subtraction wraps around too. The & mask trick indexes into the circular buffer regardless of the counter values.