ring_buffer.hpp

Go to the documentation of this file.

#ifndef SBL_PRIMITIVES_BUFFERS_RING_BUFFER_HPP_
#define SBL_PRIMITIVES_BUFFERS_RING_BUFFER_HPP_
 
/**
 * @file ring_buffer.hpp
 * @brief Lock-free ring buffer for ISR-safe communication
 * @ingroup primitives
 *
 * Provides single-producer-single-consumer (SPSC) ring buffer for safe
 * communication between interrupt service routines and main thread without
 * blocking or corruption.
 *
 * Essential for audio applications where data must flow between interrupts
 * and processing threads without blocking the interrupt handler.
 */
 
#include <cstdint>
 
namespace sbl {
namespace primitives {
namespace buffers {
 
/**
 * @brief Lock-free single-producer-single-consumer ring buffer
 *
 * Thread-safe ring buffer designed for communication between ISR and main
 * contexts. Uses volatile indices and memory barriers to ensure data
 * coherency without locks or blocking operations.
 *
 * On single-core Cortex-M, volatile guarantees that reads/writes are not
 * optimized away or reordered by the compiler. The memory barrier (provided
 * via template parameter) ensures data is committed before the index update
 * becomes visible.
 *
 * Key features:
 * - Lock-free operation - never blocks ISR
 * - Power-of-2 sizing for fast modulo operations
 * - Memory barriers for correct ordering
 * - Bounded execution time in ISR context
 * - No dynamic allocation - all storage static
 *
 * Usage:
 * @code
 * // Create ring buffer for audio samples
 * RingBuffer<int16_t, 256, MemoryBarrier> audio_buffer;
 *
 * // In ISR (producer)
 * ISR(ADC_COMPLETE) {
 *     int16_t sample = ADC_read();
 *     if (!audio_buffer.push(sample)) {
 *         // Buffer full - handle overflow
 *     }
 * }
 *
 * // In main loop (consumer)
 * void process_audio() {
 *     int16_t sample;
 *     while (audio_buffer.pop(sample)) {
 *         // Process sample
 *         apply_filter(sample);
 *     }
 * }
 * @endcode
 *
 * @tparam T Element type to store in buffer
 * @tparam Size Buffer size (must be power of 2)
 * @tparam MemoryBarrierImpl Platform-specific memory barrier implementation
 *
 * @note All public methods are ISR-safe — lock-free SPSC, bounded computation, no blocking.
 */
template<typename T, uint32_t Size, typename MemoryBarrierImpl>
class RingBuffer {
    static_assert((Size & (Size - 1)) == 0, "Size must be power of 2");
    static_assert(Size > 1, "Size must be greater than 1");
    static_assert(Size <= 65536, "Size must fit in practical memory constraints");
 
public:
    /**
     * @brief Construct empty ring buffer
     */
    RingBuffer() : head_(0), tail_(0) {}
 
    /**
     * @brief Push element to buffer (producer side)
     *
     * Adds element to the buffer if space is available. This method is
     * ISR-safe and designed to be called from the producer context
     * (typically an interrupt handler).
     *
     * @param item Element to add to buffer
     * @return true if element was added, false if buffer is full
     *
     * @note This method has bounded execution time suitable for ISR use
     */
    bool push(const T& item) {
        const uint32_t current_head = head_;
        const uint32_t next_head = (current_head + 1) & (Size - 1);
 
        // Check if buffer is full
        if (next_head == tail_) {
            return false;
        }
 
        // Store data
        buffer_[current_head] = item;
 
        // Memory barrier to ensure data is written before updating head
        MemoryBarrierImpl::full_barrier();
 
        // Update head pointer
        head_ = next_head;
 
        return true;
    }
 
    /**
     * @brief Pop element from buffer (consumer side)
     *
     * Removes and returns the oldest element from the buffer if available.
     * This method is designed to be called from the consumer context
     * (typically the main thread).
     *
     * @param item Reference to store popped element
     * @return true if element was popped, false if buffer is empty
     */
    bool pop(T& item) {
        const uint32_t current_tail = tail_;
 
        // Check if buffer is empty
        if (current_tail == head_) {
            return false;
        }
 
        // Load data
        item = buffer_[current_tail];
 
        // Memory barrier to ensure data is read before updating tail
        MemoryBarrierImpl::full_barrier();
 
        // Update tail pointer
        tail_ = (current_tail + 1) & (Size - 1);
 
        return true;
    }
 
    /**
     * @brief Check if buffer is empty
     *
     * @return true if buffer contains no elements
     */
    bool empty() const {
        return head_ == tail_;
    }
 
    /**
     * @brief Check if buffer is full
     *
     * @return true if buffer cannot accept more elements
     */
    bool full() const {
        return ((head_ + 1) & (Size - 1)) == tail_;
    }
 
    /**
     * @brief Get number of elements in buffer
     *
     * @return Current number of elements
     *
     * @note This is a snapshot - value may change immediately after call
     */
    uint32_t size() const {
        return (head_ - tail_) & (Size - 1);
    }
 
    /**
     * @brief Get maximum buffer capacity
     *
     * @return Maximum number of elements buffer can hold
     */
    constexpr uint32_t capacity() const {
        return Size - 1;  // One slot reserved to distinguish full from empty
    }
 
    /**
     * @brief Clear all elements from buffer
     *
     * Resets buffer to empty state. Should only be called when both
     * producer and consumer are stopped to avoid data races.
     */
    void clear() {
        head_ = 0;
        tail_ = 0;
    }
 
private:
    // Buffer storage
    T buffer_[Size];
 
    // Volatile indices for ISR/main thread visibility.
    // On single-core Cortex-M, volatile ensures the compiler doesn't
    // cache these in registers across barrier boundaries.
    volatile uint32_t head_;  // Producer writes, consumer reads
    volatile uint32_t tail_;  // Consumer writes, producer reads
};
 
/**
 * @brief Type alias for common audio sample buffer
 * @note Requires platform to provide MemoryBarrierImpl type
 */
template<typename MemoryBarrierImpl>
using AudioSampleBuffer = RingBuffer<int16_t, 512, MemoryBarrierImpl>;
 
/**
 * @brief Type alias for MIDI event buffer
 * @note Requires platform to provide MemoryBarrierImpl type
 */
template<typename MemoryBarrierImpl>
using MidiEventBuffer = RingBuffer<uint8_t, 128, MemoryBarrierImpl>;
 
/**
 * @brief Type alias for general event buffer
 * @note Requires platform to provide MemoryBarrierImpl type
 */
template<typename EventType, typename MemoryBarrierImpl>
using EventBuffer = RingBuffer<EventType, 64, MemoryBarrierImpl>;
 
} // namespace buffers
} // namespace primitives
} // namespace sbl
 
#endif // SBL_PRIMITIVES_BUFFERS_RING_BUFFER_HPP_