sequencer_state_channel.hpp

Go to the documentation of this file.

#pragma once
 
#include <array>
#include <atomic>
#include <cstdint>
#include <optional>
#include <type_traits>
 
#include <pulp/runtime/seqlock.hpp>
#include <pulp/runtime/spsc_queue.hpp>
#include <pulp/runtime/triple_buffer.hpp>

namespace pulp::state {
 
// ── Shared scalar types (dimension-independent) ──────────────────────────────
using Epoch = std::uint64_t;
using EngineSequence = std::uint64_t;
using ClientSequence = std::uint64_t;
using EditTransactionId = std::uint32_t;

struct StepCell {
    std::uint8_t flags = 0;
    std::uint8_t velocity = 100;      // 0..127
    std::uint8_t probability = 127;   // 0..127
    std::int8_t pitch_offset = 0;     // semitones
    std::uint16_t gate_ticks = 24;    // gate length in ticks
    std::uint8_t ratchet = 1;         // sub-hits per step
    std::uint8_t reserved = 0;
 
    static constexpr std::uint8_t kEnabledBit = 0x01;
    constexpr bool enabled() const { return (flags & kEnabledBit) != 0; }
};

struct PlayheadState {
    std::uint64_t sample_time = 0;
    double ppq_position = 0.0;
    std::uint32_t block_index = 0;
    std::uint8_t active_pattern = 0;
    std::uint8_t active_step = 0;
    std::uint8_t playing = 0;          // bool as byte for trivial-copy stability
    std::uint8_t reserved = 0;
};
static_assert(std::is_trivially_copyable_v<PlayheadState>,
              "PlayheadState must be trivially copyable for SeqLock");
 
// ── SequencerConfig — the compile-time dimension/type bundle ─────────────────
template <std::size_t Lanes, std::size_t Steps, std::size_t Patterns,
          class Cell = StepCell, class Playhead = PlayheadState,
          std::size_t CommandDepth = 1024, std::size_t AppliedDepth = 1024>
struct SequencerConfig {
    static constexpr std::size_t lanes = Lanes;
    static constexpr std::size_t steps = Steps;
    static constexpr std::size_t patterns = Patterns;
    static constexpr std::size_t command_depth = CommandDepth;
    static constexpr std::size_t applied_depth = AppliedDepth;
    using cell_type = Cell;
    using playhead_type = Playhead;
 
    static_assert(Lanes >= 1 && Steps >= 1 && Patterns >= 1,
                  "dimensions must be >= 1");
    static_assert(Lanes <= 255 && Steps <= 255 && Patterns <= 255,
                  "wire indices are uint8_t; dims are capped at 255");
    static_assert(CommandDepth > 0 && AppliedDepth > 0, "FIFO depths must be > 0");
    // NOTE: do NOT require trivially-default-constructible — the reference
    // StepCell has default member initializers, so it is trivially copyable but
    // not trivially default constructible. The operational contract is:
    // trivially copyable (memcpy/TripleBuffer/FIFO), copy-assignable
    // (TripleBuffer::write assigns), and cheaply default-constructible
    // (SpscQueue::try_pop default-constructs the element on the audio thread).
    static_assert(std::is_trivially_copyable_v<Cell> &&
                      std::is_copy_assignable_v<Cell> &&
                      std::is_default_constructible_v<Cell>,
                  "Cell must be trivially copyable, copy-assignable, and cheaply "
                  "default-constructible (its default ctor runs on audio-thread pop)");
    static_assert(std::is_trivially_copyable_v<Playhead> &&
                      std::is_copy_assignable_v<Playhead>,
                  "Playhead must be trivially copyable + copy-assignable (SeqLock)");
};
 
// ── Reference dimensions (sized to the reference sequencer shape) ────────────
inline constexpr std::uint8_t kPatternCount = 32;
inline constexpr std::uint8_t kLaneCount = 12;
inline constexpr std::uint8_t kStepCount = 32;
 
// FIFO depths. Commands and echoes are small and drained every UI/audio tick;
// these are generous relative to a realistic edit burst. Overflow is handled
// (command submit fails; echo overflow forces a snapshot resync), never UB.
inline constexpr std::size_t kCommandQueueCapacity = 1024;
inline constexpr std::size_t kAppliedQueueCapacity = 1024;
 
// ── Dirty-region descriptor (UI invalidation granularity) ────────────────────
enum class DirtyKind : std::uint8_t {
    None,
    FullSnapshot,
    Pattern,
    Lane,
    StepRange,
    Cell,
};
 
struct DirtyRegion {
    DirtyKind kind = DirtyKind::None;
    std::uint8_t pattern = 0;
    std::uint8_t lane = 0;
    std::uint8_t first_step = 0;
    std::uint8_t step_count = 0;
};
 
// ── UI -> audio: edit commands ───────────────────────────────────────────────
enum class StepEditKind : std::uint8_t {
    SetCell,
    Clear,
    RandomizeLane,
    SetPatternLength,
    SwitchPattern,
};
 
enum class ClearScope : std::uint8_t { Cell, Lane, Pattern, All };

enum class GesturePhase : std::uint8_t { None, Begin, Update, End, Cancel };

template <class Config>
struct SetCellEditT {
    std::uint8_t pattern = 0;
    std::uint8_t lane = 0;
    std::uint8_t step = 0;
    typename Config::cell_type cell{};
};
struct ClearEdit {
    ClearScope scope = ClearScope::Cell;
    std::uint8_t pattern = 0;
    std::uint8_t lane = 0;
    std::uint8_t step = 0;
};
struct RandomizeLaneEdit {
    std::uint8_t pattern = 0;
    std::uint8_t lane = 0;
    std::uint32_t seed = 0;
    std::uint8_t density = 64;         // 0..127 probability of a hit per step
    std::uint8_t min_velocity = 64;
    std::uint8_t max_velocity = 127;
};
struct SetPatternLengthEdit {
    std::uint8_t pattern = 0;
    std::uint8_t length = 0;           // active step count; 0 = full (Config::steps)
};
struct SwitchPatternEdit {
    std::uint8_t pattern = 0;
};
 
template <class Config>
struct StepEditCommandT {
    ClientSequence client_sequence = 0;
    EditTransactionId transaction_id = 0;
    GesturePhase gesture_phase = GesturePhase::None;
    StepEditKind kind = StepEditKind::SetCell;
 
    union Payload {
        SetCellEditT<Config> set_cell;
        ClearEdit clear;
        RandomizeLaneEdit randomize_lane;
        SetPatternLengthEdit set_pattern_length;
        SwitchPatternEdit switch_pattern;
        constexpr Payload() : set_cell{} {}
    } payload{};
};
 
// ── Authoritative state model ────────────────────────────────────────────────
template <class Config>
struct PatternStateT {
    std::uint8_t length = static_cast<std::uint8_t>(Config::steps);  // active steps (<= Steps)
    std::array<std::array<typename Config::cell_type, Config::steps>, Config::lanes> lanes{};
};

template <class Config>
struct SnapshotT {
    std::uint32_t schema_version = 1;
    Epoch epoch = 0;                     // engine-controlled; monotonic per publish
    EngineSequence engine_sequence = 0;  // last applied edit folded into this snapshot
    std::uint8_t active_pattern = 0;
    std::uint8_t active_lane_count = static_cast<std::uint8_t>(Config::lanes);
    std::uint8_t active_pattern_count = static_cast<std::uint8_t>(Config::patterns);
    std::array<PatternStateT<Config>, Config::patterns> patterns{};
};
 
// ── audio -> UI: applied echoes ──────────────────────────────────────────────

template <class Config>
struct StepRangeAppliedT {
    std::uint8_t pattern = 0;
    std::uint8_t lane = 0;
    std::uint8_t first_step = 0;
    std::uint8_t step_count = 0;
    std::array<typename Config::cell_type, Config::steps> cells{};
};
 
enum class AppliedEditKind : std::uint8_t {
    StepRangeChanged,
    PatternLengthChanged,
    ActivePatternChanged,
    CommandRejected,
};
 
template <class Config>
struct AppliedEditT {
    EngineSequence engine_sequence = 0;  // monotonic; UI filters stale echoes by this
    Epoch snapshot_epoch = 0;            // snapshot this echo is relative to
    ClientSequence client_sequence = 0;  // echoes the originating command's id
    EditTransactionId transaction_id = 0;
    AppliedEditKind kind = AppliedEditKind::StepRangeChanged;
    DirtyRegion dirty{};
 
    union Payload {
        StepRangeAppliedT<Config> step_range;
        SetPatternLengthEdit pattern_length;
        SwitchPatternEdit active_pattern;
        std::uint32_t reject_reason;
        constexpr Payload() : step_range{} {}
    } payload{};
};
 
// ── The channel ──────────────────────────────────────────────────────────────
template <class Config>
class SequencerStateChannelT {
public:
    using ConfigType = Config;
    using Snapshot = SnapshotT<Config>;
    using PatternState = PatternStateT<Config>;
    using Command = StepEditCommandT<Config>;
    using AppliedEdit = AppliedEditT<Config>;
    using StepRangeApplied = StepRangeAppliedT<Config>;
    using SetCellEdit = SetCellEditT<Config>;
    using Playhead = typename Config::playhead_type;
 
    SequencerStateChannelT() = default;
 
    // ── UI / message thread ──────────────────────────────────────────────────

    bool ui_try_submit(const Command& command) noexcept {
        return commands_.try_push(command);
    }

    std::optional<AppliedEdit> ui_try_pop_applied() noexcept {
        return applied_.try_pop();
    }

    Playhead ui_read_playhead() const noexcept { return playhead_.read(); }

    const Snapshot& ui_read_latest_snapshot() noexcept { return snapshot_.read(); }

    Epoch ui_resync_required_epoch() const noexcept {
        return resync_epoch_.load(std::memory_order_acquire);
    }
 
    runtime::SpscQueueTelemetry ui_applied_telemetry() const noexcept {
        return applied_.telemetry();
    }
    runtime::SpscQueueTelemetry ui_command_telemetry() const noexcept {
        return commands_.telemetry();
    }

    bool debug_claim_ui_consumer() noexcept {
#ifndef NDEBUG
        bool expected = false;
        return ui_consumer_claimed_.compare_exchange_strong(expected, true,
                                                            std::memory_order_acq_rel);
#else
        return true;
#endif
    }
    void debug_release_ui_consumer() noexcept {
#ifndef NDEBUG
        ui_consumer_claimed_.store(false, std::memory_order_release);
#endif
    }
 
    // ── Engine (audio) thread ─────────────────────────────────────────────────

    std::optional<Command> audio_try_pop_command() noexcept {
        return commands_.try_pop();
    }

    bool audio_try_publish_applied(const AppliedEdit& edit) noexcept {
        return applied_.try_push(edit);
    }

    void audio_publish_snapshot(const Snapshot& snapshot) noexcept {
        snapshot_.write(snapshot);
    }

    void audio_publish_playhead(const Playhead& playhead) noexcept {
        playhead_.write(playhead);
    }

    void audio_mark_resync_required(Epoch epoch) noexcept {
        Epoch prev = resync_epoch_.load(std::memory_order_relaxed);
        while (epoch > prev &&
               !resync_epoch_.compare_exchange_weak(prev, epoch,
                                                    std::memory_order_release,
                                                    std::memory_order_relaxed)) {
            // prev reloaded by compare_exchange_weak; retry until we win or
            // another (larger) value already satisfies the bar.
        }
    }
 
private:
    runtime::SpscQueue<Command, Config::command_depth> commands_{};
    runtime::SpscQueue<AppliedEdit, Config::applied_depth> applied_{};
    runtime::TripleBuffer<Snapshot> snapshot_{};
    runtime::SeqLock<Playhead> playhead_{};
    std::atomic<Epoch> resync_epoch_{0};
#ifndef NDEBUG
    std::atomic<bool> ui_consumer_claimed_{false};
#endif
};
 
// ── Reference config + aliases ───────────────────────────────────────────────
using ReferenceSequencerConfig =
    SequencerConfig<kLaneCount, kStepCount, kPatternCount, StepCell>;
 
using SequencerStateChannel = SequencerStateChannelT<ReferenceSequencerConfig>;
using Snapshot = SnapshotT<ReferenceSequencerConfig>;
using PatternState = PatternStateT<ReferenceSequencerConfig>;
using StepEditCommand = StepEditCommandT<ReferenceSequencerConfig>;
using AppliedEdit = AppliedEditT<ReferenceSequencerConfig>;
using StepRangeApplied = StepRangeAppliedT<ReferenceSequencerConfig>;
using SetCellEdit = SetCellEditT<ReferenceSequencerConfig>;
 
// ── Frozen layout tripwires (source/API compat only — NOT byte persistence) ──
// These flag accidental layout drift of the reference transport types. They are
// NOT a promise that a Snapshot may be memcpy'd to disk/IPC; persist via a codec.
static_assert(std::is_trivially_copyable_v<StepCell>);
static_assert(std::is_trivially_copyable_v<DirtyRegion>);
static_assert(std::is_trivially_copyable_v<StepEditCommand> &&
                  std::is_copy_assignable_v<StepEditCommand> &&
                  std::is_default_constructible_v<StepEditCommand>,
              "Command must be trivially copyable + copy-assignable + default-constructible "
              "for the SPSC FIFO");
static_assert(std::is_trivially_copyable_v<AppliedEdit> &&
                  std::is_copy_assignable_v<AppliedEdit> &&
                  std::is_default_constructible_v<AppliedEdit>,
              "AppliedEdit must be trivially copyable + copy-assignable + default-constructible "
              "for the SPSC FIFO");
static_assert(std::is_trivially_copyable_v<Snapshot> &&
                  std::is_copy_assignable_v<Snapshot> &&
                  std::is_default_constructible_v<Snapshot>,
              "Snapshot must be trivially copyable + copy-assignable for TripleBuffer");
 
} // namespace pulp::state