event_queue.hpp

Go to the documentation of this file.

// sbl/control/event_queue.hpp — Events from another context into the control tick (FDP-073)
//
// One producing context pushes (the main loop, which parses USB MIDI); the
// control tick drains in Stage::Drain. Events reach the control context and
// only the control context touches control state, so the cross-context
// writes RPT-026 §3d found cannot happen.
//
// Lock-free SPSC over RingBuffer. A full queue drops the newest event: the
// push is rejected and counted. Only the consumer may move the tail, so
// dropping the oldest would need a lock (FDP-073 addendum 2026-09-11). Size
// the queue so overflow means a stalled tick — 64 events drained every 1 ms
// is about 60x full-rate DIN MIDI.
//
// drain() pops at most capacity() events per call, so a producer that keeps
// pushing cannot stretch the tick.
//
// Usage:
//   sbl::control::EventQueue<sbl::midi::MidiEvent, 64> s_midi_q;
//
//   // main loop (producer)
//   s_midi_q.push(event);
//
//   // Stage::Drain subscriber (consumer)
//   s_midi_q.drain([](const sbl::midi::MidiEvent& e) { handle(e); });
 
#ifndef SBL_CONTROL_EVENT_QUEUE_HPP_
#define SBL_CONTROL_EVENT_QUEUE_HPP_
 
#include <atomic>
#include <cstdint>
 
#include <sbl/hw/util/ring_buffer.hpp>
 
namespace sbl::control {
 
template<typename T, uint32_t Size>
class EventQueue {
public:
    /// Producer side. Returns false (and counts a drop) if the queue is full.
    bool push(const T& event) {
        if (ring_.push(event)) return true;
        dropped_.store(dropped_.load(std::memory_order_relaxed) + 1,
                       std::memory_order_relaxed);
        return false;
    }
 
    /// Consumer side. Calls fn(event) for up to capacity() queued events,
    /// oldest first. Returns the number handled.
    template<typename Fn>
    uint32_t drain(Fn&& fn) {
        T event{};
        uint32_t handled = 0;
        while (handled < capacity() && ring_.pop(event)) {
            fn(static_cast<const T&>(event));
            ++handled;
        }
        return handled;
    }
 
    /// Consumer side. Pop one event; false if empty.
    bool pop(T& event) { return ring_.pop(event); }
 
    bool empty() const { return ring_.empty(); }
 
    /// Pushes rejected because the queue was full, since boot. Any context.
    uint32_t dropped() const { return dropped_.load(std::memory_order_relaxed); }
 
    static constexpr uint32_t capacity() { return Size - 1; }
 
private:
    sbl::primitives::buffers::RingBuffer<T, Size> ring_;
    std::atomic<uint32_t> dropped_{0};  // producer writes, anyone reads
};
 
} // namespace sbl::control
 
#endif // SBL_CONTROL_EVENT_QUEUE_HPP_