scheduler.hpp

Go to the documentation of this file.

// sbl/control/scheduler.hpp — The control context: one base tick, divider slots,
// fixed intra-tick order (FDP-073)
//
// The app drives run() from a single base tick — the 1 kHz timer ISR on
// hardware, the timer thread on the workbench — and passes the audio sample
// clock. Each slot runs every Nth base tick. Subscribers are told how many
// samples elapsed since their slot last ran, derived from the clock, so an
// irregular base tick never skews time-constant math (the rate invariant:
// components are told elapsed time, never assume a call rate).
//
// Every base tick runs in stage order, so the signal-transport update order
// is enforced by construction:
//
//   Drain    event queues → converters (MIDI parsed elsewhere arrives here)
//   Update   sources and components: tick(elapsed_samples)
//   Merge    per-parameter merge policies resolve (FDP-074)
//   Publish  bridge writes — the only state the audio context reads
//
// Within a stage, due subscribers run in subscription order. Apps subscribe;
// components never self-register. Static storage, no allocation.
//
// Usage:
//   enum : uint8_t { k1kHz, k200Hz, k60Hz };
//   sbl::control::Scheduler<3> sched{{1, 5, 17}};
//   sched.subscribe<MyWidget, &MyWidget::tick>(Stage::Update, k200Hz, widget);
//   sched.subscribe(Stage::Drain, k1kHz, drain_midi, nullptr);
//
//   // base tick (1 kHz timer ISR / timer thread)
//   sched.run(sbl::hal::audio::SampleClock::now());
//
// Contexts: run() from exactly one context. subscribe() at init, before the
// first run().
 
#ifndef SBL_CONTROL_SCHEDULER_HPP_
#define SBL_CONTROL_SCHEDULER_HPP_
 
#include <cstdint>
 
namespace sbl::control {
 
/// Intra-tick order. Every due subscriber of a stage runs before any of the next.
enum class Stage : uint8_t {
    Drain,
    Update,
    Merge,
    Publish,
};
 
inline constexpr uint8_t kStageCount = 4;
 
/// Subscriber callback: context pointer and samples elapsed since its slot last ran.
using TickFn = void (*)(void* context, uint32_t elapsed_samples);
 
template<uint8_t Slots, uint8_t Capacity = 16>
class Scheduler {
    static_assert(Slots > 0, "Scheduler needs at least one slot");
    static_assert(Capacity > 0, "Scheduler needs subscriber capacity");
 
public:
    /// @param dividers Base ticks per run, per slot (0 is treated as 1).
    explicit Scheduler(const uint16_t (&dividers)[Slots]) {
        for (uint8_t s = 0; s < Slots; ++s) {
            divider_[s] = dividers[s] ? dividers[s] : 1;
        }
    }
 
    /// Add a subscriber. Returns false if full, the slot is out of range, or fn is null.
    bool subscribe(Stage stage, uint8_t slot, TickFn fn, void* context) {
        if (count_ >= Capacity || slot >= Slots || fn == nullptr) return false;
        subs_[count_++] = {fn, context, stage, slot};
        return true;
    }
 
    /// Subscribe a member `void T::method(uint32_t elapsed_samples)`.
    template<typename T, void (T::*Method)(uint32_t)>
    bool subscribe(Stage stage, uint8_t slot, T& object) {
        return subscribe(stage, slot,
            [](void* c, uint32_t elapsed) { (static_cast<T*>(c)->*Method)(elapsed); },
            &object);
    }
 
    /// One base tick. `sample_clock` is the audio frame count (wrapping).
    /// The first call establishes the baseline: every slot runs, told 0.
    void run(uint32_t sample_clock) {
        if (!started_) {
            for (uint8_t s = 0; s < Slots; ++s) last_[s] = sample_clock;
            started_ = true;
        }
 
        bool due[Slots];
        uint32_t elapsed[Slots];
        for (uint8_t s = 0; s < Slots; ++s) {
            due[s] = (phase_[s] == 0);
            elapsed[s] = 0;
            if (due[s]) {
                elapsed[s] = sample_clock - last_[s];
                last_[s] = sample_clock;
            }
            if (++phase_[s] >= divider_[s]) phase_[s] = 0;
        }
 
        for (uint8_t st = 0; st < kStageCount; ++st) {
            const Stage stage = static_cast<Stage>(st);
            for (uint8_t i = 0; i < count_; ++i) {
                const Subscriber& sub = subs_[i];
                if (sub.stage == stage && due[sub.slot]) {
                    sub.fn(sub.context, elapsed[sub.slot]);
                }
            }
        }
    }
 
    uint8_t subscriber_count() const { return count_; }
    uint16_t divider(uint8_t slot) const { return slot < Slots ? divider_[slot] : 0; }
    static constexpr uint8_t slots() { return Slots; }
    static constexpr uint8_t capacity() { return Capacity; }
 
private:
    struct Subscriber {
        TickFn fn = nullptr;
        void* context = nullptr;
        Stage stage = Stage::Update;
        uint8_t slot = 0;
    };
 
    Subscriber subs_[Capacity]{};
    uint16_t divider_[Slots]{};
    uint16_t phase_[Slots]{};
    uint32_t last_[Slots]{};
    uint8_t count_ = 0;
    bool started_ = false;
};
 
} // namespace sbl::control
 
#endif // SBL_CONTROL_SCHEDULER_HPP_