ring_buffer.hpp

Go to the documentation of this file.

#ifndef SBL_HW_UTIL_RING_BUFFER_HPP_
#define SBL_HW_UTIL_RING_BUFFER_HPP_
 
/**
 * @file ring_buffer.hpp
 * @brief Lock-free single-producer, single-consumer ring buffer
 * @ingroup primitives
 *
 * Carries data from one execution context to another without blocking
 * either: ISR → main on hardware, thread → thread on the workbench. Every
 * operation is bounded and allocation-free.
 *
 * ## Ordering
 *
 * The indices are relaxed `std::atomic<uint32_t>` — no torn or invented
 * accesses, and no data race in the C++ sense. Ordering between the slot
 * contents and the index that publishes them comes from a fence pair:
 *
 *   producer: write slot → release fence → store head
 *   consumer: load head → acquire fence → read slot → release fence → store tail
 *
 * The fence strength follows the target:
 *
 * - **Single-core bare metal** (Cortex-M): producer and consumer share one
 *   core — an ISR preempting a thread is like a signal handler — so the
 *   fences are `atomic_signal_fence`, compiler-only, zero instructions. A
 *   DMB would be the wrong strength, not a safer one (interrupt research
 *   doc §5.3).
 * - **Host** (workbench, unit tests): producer and consumer may run on
 *   different cores, so the fences are `atomic_thread_fence` (DMB on
 *   AArch64).
 *
 * One slot is reserved to tell full from empty: capacity is Size − 1.
 *
 * Usage:
 * @code
 * RingBuffer<uint8_t, 256> rx;
 *
 * // Producer (ISR)
 * if (!rx.push(byte)) { ++overflows; }
 *
 * // Consumer (main)
 * uint8_t b;
 * while (rx.pop(b)) { handle(b); }
 * @endcode
 *
 * @tparam T    Element type (copied in and out)
 * @tparam Size Slot count, a power of 2
 *
 * @note push() from the producer context only, pop() from the consumer
 *       context only. empty()/full()/size() are snapshots from either side.
 */
 
#include <atomic>
#include <cstdint>
 
namespace sbl {
namespace primitives {
namespace buffers {
 
namespace detail {
 
#if defined(__arm__) && !defined(__linux__)
inline void ring_acquire_fence() { std::atomic_signal_fence(std::memory_order_acquire); }
inline void ring_release_fence() { std::atomic_signal_fence(std::memory_order_release); }
#else
inline void ring_acquire_fence() { std::atomic_thread_fence(std::memory_order_acquire); }
inline void ring_release_fence() { std::atomic_thread_fence(std::memory_order_release); }
#endif
 
} // namespace detail
 
template<typename T, uint32_t Size>
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");
    static_assert(std::atomic<uint32_t>::is_always_lock_free,
                  "RingBuffer needs lock-free 32-bit atomics");
 
public:
    RingBuffer() = default;
 
    /**
     * @brief Push an element (producer side)
     * @return false if the buffer is full; the element is not stored
     * @note ISR-safe — bounded, non-blocking
     */
    bool push(const T& item) {
        const uint32_t head = head_.load(std::memory_order_relaxed);
        const uint32_t next = (head + 1) & kMask;
        if (next == tail_.load(std::memory_order_relaxed)) {
            return false;
        }
        detail::ring_acquire_fence();   // consumer finished with this slot
        buffer_[head] = item;
        detail::ring_release_fence();   // slot written before head publishes it
        head_.store(next, std::memory_order_relaxed);
        return true;
    }
 
    /**
     * @brief Pop the oldest element (consumer side)
     * @return false if the buffer is empty; `item` is unchanged
     * @note ISR-safe — bounded, non-blocking
     */
    bool pop(T& item) {
        const uint32_t tail = tail_.load(std::memory_order_relaxed);
        if (tail == head_.load(std::memory_order_relaxed)) {
            return false;
        }
        detail::ring_acquire_fence();   // head observed before the slot is read
        item = buffer_[tail];
        detail::ring_release_fence();   // slot read before tail frees it
        tail_.store((tail + 1) & kMask, std::memory_order_relaxed);
        return true;
    }
 
    bool empty() const {
        return head_.load(std::memory_order_relaxed) ==
               tail_.load(std::memory_order_relaxed);
    }
 
    bool full() const {
        return ((head_.load(std::memory_order_relaxed) + 1) & kMask) ==
               tail_.load(std::memory_order_relaxed);
    }
 
    /// Element count — a snapshot, may change immediately after the call.
    uint32_t size() const {
        return (head_.load(std::memory_order_relaxed) -
                tail_.load(std::memory_order_relaxed)) & kMask;
    }
 
    static constexpr uint32_t capacity() { return Size - 1; }
 
    /// Empty the buffer. Only while neither producer nor consumer runs.
    void clear() {
        head_.store(0, std::memory_order_relaxed);
        tail_.store(0, std::memory_order_relaxed);
    }
 
private:
    static constexpr uint32_t kMask = Size - 1;
 
    T buffer_[Size] = {};
    std::atomic<uint32_t> head_{0};  // producer writes, consumer reads
    std::atomic<uint32_t> tail_{0};  // consumer writes, producer reads
};
 
} // namespace buffers
} // namespace primitives
} // namespace sbl
 
#endif // SBL_HW_UTIL_RING_BUFFER_HPP_