ring_buffer.hpp

Go to the documentation of this file.

#ifndef SBL_CORE_PRIMITIVES_BUFFERS_RING_BUFFER_HPP_
#define SBL_CORE_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>
 
// ARM-native types for optimal performance
namespace sbl::common::types {
    using BufferIndex = uint32_t;
    using BufferSize = uint32_t;
}
 
namespace sbl {
namespace core {
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 atomic operations and memory barriers to ensure data
 * coherency without locks or blocking operations.
 * 
 * Key features:
 * - Lock-free operation - never blocks ISR
 * - Power-of-2 sizing for fast modulo operations
 * - Proper memory barriers for multi-core safety
 * - Bounded execution time in ISR context
 * - No dynamic allocation - all storage static
 * 
 * Typical use cases:
 * - Audio sample transfer between ISR and processing
 * - Event capture (triggers, gates, clock edges)
 * - Parameter changes from UI to audio engine
 * - CV recording and analysis
 * 
 * Usage:
 * @code
 * // Create ring buffer for audio samples
 * // (assumes platform provides MemoryBarrier type)
 * 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
 */
template<typename T, common::types::BufferSize 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 common::types::BufferIndex current_head = head_.load();
        const common::types::BufferIndex next_head = (current_head + 1) & (Size - 1);
        
        // Check if buffer is full
        if (next_head == tail_.load()) {
            return false;
        }
        
        // Store data
        buffer_[current_head] = item;
        
        // Memory barrier to ensure data is written before updating head
        memory_barrier();
        
        // Update head pointer
        head_.store(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 common::types::BufferIndex current_tail = tail_.load();
        
        // Check if buffer is empty
        if (current_tail == head_.load()) {
            return false;
        }
        
        // Load data
        item = buffer_[current_tail];
        
        // Memory barrier to ensure data is read before updating tail
        memory_barrier();
        
        // Update tail pointer
        const common::types::BufferIndex next_tail = (current_tail + 1) & (Size - 1);
        tail_.store(next_tail);
        
        return true;
    }
    
    /**
     * @brief Check if buffer is empty
     * 
     * @return true if buffer contains no elements
     */
    bool empty() const {
        return head_.load() == tail_.load();
    }
    
    /**
     * @brief Check if buffer is full
     * 
     * @return true if buffer cannot accept more elements
     */
    bool full() const {
        const common::types::BufferIndex next_head = (head_.load() + 1) & (Size - 1);
        return next_head == tail_.load();
    }
    
    /**
     * @brief Get number of elements in buffer
     * 
     * @return Current number of elements
     * 
     * @note This is a snapshot - value may change immediately after call
     */
    common::types::BufferIndex size() const {
        const common::types::BufferIndex h = head_.load();
        const common::types::BufferIndex t = tail_.load();
        return (h - t) & (Size - 1);
    }
    
    /**
     * @brief Get maximum buffer capacity
     * 
     * @return Maximum number of elements buffer can hold
     */
    constexpr common::types::BufferIndex 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_.store(0);
        tail_.store(0);
    }
    
private:
    // Atomic types for lock-free operation - ARM-native 32-bit for optimal performance
    using AtomicIndex = volatile common::types::BufferIndex;
    
    /**
     * @brief Platform-specific memory barrier
     * 
     * Ensures memory operations complete in order. Uses platform-specific
     * implementation provided via template parameter.
     */
    static void memory_barrier() {
        MemoryBarrierImpl::full_barrier();
    }
    
    // Buffer storage
    T buffer_[Size];
    
    // Lock-free atomic indices
    // Separate cache lines to avoid false sharing on multi-core systems
    alignas(64) AtomicIndex head_;  // Producer writes, consumer reads
    alignas(64) AtomicIndex tail_;  // Consumer writes, producer reads
};
 
/**
 * @brief Type alias for common audio sample buffer - ARM-optimized sizing
 * @note Requires platform to provide MemoryBarrierImpl type
 */
template<typename MemoryBarrierImpl>
using AudioSampleBuffer = RingBuffer<int16_t, 512, MemoryBarrierImpl>;
 
/**
 * @brief Type alias for MIDI event buffer - ARM-optimized sizing
 * @note Requires platform to provide MemoryBarrierImpl type
 */
template<typename MemoryBarrierImpl>
using MidiEventBuffer = RingBuffer<uint8_t, 128, MemoryBarrierImpl>;
 
/**
 * @brief Type alias for general event buffer - ARM-optimized sizing
 * @note Requires platform to provide MemoryBarrierImpl type
 */
template<typename EventType, typename MemoryBarrierImpl>
using EventBuffer = RingBuffer<EventType, 64, MemoryBarrierImpl>;
 
} // namespace buffers
} // namespace primitives
} // namespace core
} // namespace sbl
 
#endif // SBL_CORE_PRIMITIVES_BUFFERS_RING_BUFFER_HPP_