Lock-free Single-Producer / Single-Consumer ring buffer. More...

#include <array>
#include <atomic>
#include <cstddef>
#include <optional>
#include <type_traits>

Classes
class	srfm::stream::SPSCRing< T, SIZE >
	Lock-free single-producer / single-consumer ring buffer. More...

Namespaces
namespace	srfm

namespace	srfm::stream

Detailed Description

Lock-free Single-Producer / Single-Consumer ring buffer.

Module: include/srfm/stream/ Owner: AGT-10 (Builder) — 2026-03-01

Responsibility

Provide a zero-heap-allocation, lock-free SPSC queue with sub-microsecond throughput. This is the sole inter-thread communication primitive in the streaming pipeline.

Guarantees

• Deterministic: push()/pop() never allocate heap memory. • Lock-free: no mutexes, no condition variables, no spin-locks. • Cache-friendly: producer and consumer indices live on separate cache lines (alignas(64)) to eliminate false sharing. • Correct: all cross-thread visibility relies on C++11 acquire/release atomic ordering — no relaxed cross-thread loads. • Non-blocking: push() returns false when full; pop() returns nullopt when empty. Neither ever blocks the calling thread. • noexcept: both push() and pop() are unconditionally noexcept, provided T's move-constructor and move-assignment are noexcept.

Template Parameters

T — Element type. Must be noexcept move-constructible and noexcept move-assignable. SIZE — Capacity in elements. Must be an exact power of two. Valid range: [2, 2^30].

Usage

SPSCRing<OHLCVTick, 65536> ring;
 
// Producer thread:
OHLCVTick tick = ...;
if (!ring.push(std::move(tick))) { ++drop_count; }
 
// Consumer thread:
while (auto t = ring.pop()) { process(*t); }

NOT Responsible For

• Multi-producer or multi-consumer safety — use one producer, one consumer. • Blocking wait — callers must implement their own spin or yield logic. • Persistence — in-memory only.

Memory Layout

The buffer is stored inline (std::array<T, SIZE>), so the total object size is approximately SIZE * sizeof(T) + 128 bytes (two padded indices). For SIZE=65536 and OHLCVTick (48 bytes): ~3 MiB per ring.

Definition in file spsc_ring.hpp.

Classes