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_channels channels of at least capacity samples 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_samples of every channel (channels[c]: channel c; channels beyond channels.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_samples of the oldest arrived samples into channels (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_samples of the oldest arrived samples.

Returns the samples dropped.

inline size_t read_latest(std::span<T*const> channels, size_t num_samples)#

Reader: the newest num_samples (or fewer, if fewer have arrived) into channels, consuming everything up to them: what an analyser that only shows the latest window wants.

Returns the samples read.

inline size_t dropped() const#

The samples write() could not fit since prepare().