Class thl::core::SpscRingBuffer#
-
template<typename T>
class SpscRingBuffer# A multi-channel lock-free single-producer / single-consumer ring of samples: one thread writes blocks (the audio thread), one other thread reads them (a UI or analysis thread).
Semantics:
write() copies as much of a block as fits and drops the rest, counted in dropped(): the writer never waits and never touches what the reader may be copying. A reader that keeps up never sees a drop; one that wants only the latest samples skips the rest (skip(), read_latest()).
read() copies what has arrived, oldest first, up to the destination’s length.
Every channel moves together: one write position, one read position.
Threads: prepare() allocates and must not run concurrently with anything else. write() and free_space() belong to the writer, read(), read_latest(), skip() and available() to the reader; all are real-time safe (no allocation, no locks: two atomic indices). dropped() may be called from any thread.
Memory ordering: the writer copies samples, then publishes its position with a release store; the reader acquires it before copying, and publishes its own position with a release store after copying, which the writer acquires before reusing that space. The positions only grow (modulo 2^N), so full and empty are told apart without a spare slot.
T must be trivially copyable; the capacity is rounded up to a power of two.
Why not moodycamel (readerwriterqueue, concurrentqueue), already fetched for the modulation component:
ReaderWriterQueue (SPSC) moves one element per call: a call per sample per channel, or a fixed-size block struct per entry that wastes shorter blocks and splits longer ones. It has no bulk enqueue.
ConcurrentQueue has try_enqueue_bulk(), but it is multi-producer / multi-consumer (more than one writer and one reader need), and only its try_ variants with preallocated capacity never allocate.
Both queue elements, not channels: planar blocks would be interleaved on the way in, or need a queue per channel that can drift apart.
CMakeLists.txt keeps moodycamel inside the modulation component; core would make it a public dependency of the library. This ring moves whole multi-channel blocks with two copies per channel, drops and counts what does not fit, and needs no dependency.
Public Functions
-
SpscRingBuffer() = default#
-
SpscRingBuffer(const SpscRingBuffer&) = delete#
-
SpscRingBuffer &operator=(const SpscRingBuffer&) = delete#
-
inline void prepare(size_t num_channels, size_t capacity)#
Allocates
num_channelschannels of at leastcapacitysamples each and empties the ring.Not concurrent with any other call.
-
inline size_t num_channels() const#
-
inline size_t capacity() const#
-
inline size_t free_space() const#
Writer: the samples that fit now.
-
inline size_t write(std::span<const T*const> channels, size_t num_samples)#
Writer: appends
num_samplesof every channel (channels[c]: channel c; channels beyondchannels.size()get T{}, extra ones are ignored).Returns the samples written; the rest are dropped and counted.
-
inline size_t available() const#
Reader: the samples that have arrived and not been read.
-
inline size_t read(std::span<T*const> channels, size_t num_samples)#
Reader: copies up to
num_samplesof the oldest arrived samples intochannels(channels[c]: channel c; a null or missing destination skips that channel) and consumes them.Returns the samples read.
-
inline size_t skip(size_t num_samples)#
Reader: drops up to
num_samplesof the oldest arrived samples.Returns the samples dropped.