store.hpp

Go to the documentation of this file.

#pragma once
 
#include <algorithm>
#include <array>
#include <cstdint>
#include <functional>
#include <memory>
#include <mutex>
#include <optional>
#include <pulp/state/listener_token.hpp>
#include <pulp/state/parameter.hpp>
#include <pulp/state/state_migration.hpp>
#include <span>
#include <unordered_map>
#include <unordered_set>
#include <utility>
#include <vector>
 
namespace pulp::events { class EventLoop; }
 
namespace pulp::state {

struct ParamGroup {
    int id = 0;
    std::string name;
    int parent_id = 0; 
};

struct RtListenerQueueTelemetry {
    std::size_t size_approx = 0;
    std::size_t capacity = 0;
    std::uint64_t overflow_count = 0;
};

enum class ParameterGestureApplyStatus {
    Applied,
    GenerationConflict,
    InvalidParameter,
    ConcurrentMutation,
    CallbackFailureRolledBack,
    CallbackFailureUnknown,
};
 
struct ParameterGestureApplyResult {
    ParameterGestureApplyStatus status = ParameterGestureApplyStatus::InvalidParameter;
    std::uint64_t generation = 0;
};
 
class StateStore;
namespace test_support {
struct StateWriterProbe;
}

class ParameterFeedbackBaseline {
  public:
    ParameterFeedbackBaseline() = default;
 
    bool valid() const noexcept {
        return valid_;
    }
 
    ParamID id() const noexcept {
        return id_;
    }
    std::uint64_t packed_identity() const noexcept {
        return packed_identity_;
    }
 
  private:
    friend class StateStore;
    ParameterFeedbackBaseline(const StateStore* owner, ParamID id, std::uint64_t packed_identity)
        : owner_(owner), id_(id), packed_identity_(packed_identity), valid_(true) {}
 
    const StateStore* owner_ = nullptr;
    ParamID id_ = 0;
    std::uint64_t packed_identity_ = 0;
    bool valid_ = false;
};
 
enum class ConditionalParameterApplyStatus {
    Applied,
    Conflict,
    InvalidParameter,
};
 
struct ConditionalParameterApplyResult {
    ConditionalParameterApplyStatus status = ConditionalParameterApplyStatus::InvalidParameter;
    std::uint64_t current_identity = 0;
};

class ParamReader {
  public:
    ParamReader() = default;

    float get() const noexcept;

    bool valid() const noexcept {
        return store_ != nullptr;
    }
 
  private:
    friend class StateStore;
    ParamReader(const StateStore* store, std::size_t index) noexcept
        : store_(store), index_(index) {}
 
    const StateStore* store_ = nullptr;
    std::size_t index_ = 0;
};

class StateStore {
    // Tests drive a writer through its phases one at a time to reproduce
    // reader/writer interleavings deterministically.
    friend struct test_support::StateWriterProbe;
 
  public:
    StateStore();
    ~StateStore();
 
    StateStore(const StateStore&) = delete;
    StateStore& operator=(const StateStore&) = delete;

    void add_parameter(const ParamInfo& info);

    void add_group(const ParamGroup& group);

    [[gnu::always_inline]] float get_value(ParamID id) const {
        const std::size_t i = index_of(id);
        return i == kNoIndex ? 0.0f : values_[i].get();
    }

    ParamReader param_reader(ParamID id) const;

    float get_modulated(ParamID id) const;

    BaseOffsetValue get_base_offset(ParamID id) const;

    void set_value(ParamID id, float value);

    void set_value_rt(ParamID id, float value);

    struct ParamWrite {
        ParamID id = 0;
        float value = 0.0f;
    };

    void set_values_rt(std::span<const ParamWrite> writes);

    void set_normalized_rt(ParamID id, float normalized);

    std::optional<ParameterFeedbackBaseline> capture_feedback_baseline(ParamID id) const noexcept;

    ConditionalParameterApplyResult
    set_value_rt_if_baseline(const ParameterFeedbackBaseline& baseline, float value);

    void set_mod_offset(ParamID id, float offset);

    void add_mod_offset(ParamID id, float delta);

    void reset_all_mod();
 
    // ── Modulated value for display ─────────────────────────────────────
    //
    // A control bound to a parameter shows two things: the BASE (what the
    // user set or host automation plays; what gestures edit and the host
    // records) and, when something modulates the parameter, the value
    // PLAYING. Two sources feed the second, and neither is ever a host
    // automation write:
    //
    //   * host modulation -- a CLAP host's parameter modulation, which the
    //     adapter writes as the mod offset (set_mod_offset). Shown by every
    //     bound control with no plugin code.
    //   * the plugin's own modulation (an internal LFO) -- opt-in: the
    //     plugin publishes the value its DSP plays with
    //     set_display_modulation(), from any thread, real-time safe.
    //
    // A published display value wins over the host offset; nothing published
    // and a zero offset means nothing is shown.

    void set_display_modulation(ParamID id, float plain_value) noexcept;
    void clear_display_modulation(ParamID id) noexcept;
    std::optional<float> displayed_modulation(ParamID id) const noexcept;
 
    class ModulationWatch;
    [[nodiscard]] ModulationWatch
    watch_modulation(ParamID id, std::function<void(std::optional<float>)> on_change);

    float get_normalized(ParamID id) const;

    void set_normalized(ParamID id, float normalized);

    std::uint64_t state_generation() const noexcept {
        return state_generation_.load(std::memory_order_acquire);
    }

    bool state_snapshot_is_current(std::uint64_t generation) const noexcept {
        return active_state_writers_.load(std::memory_order_acquire) == 0 &&
               state_generation() == generation;
    }

    ParameterGestureApplyResult apply_normalized_gesture_if_generation(
        std::uint64_t expected_generation, ParamID id, float normalized);

    float get_default(ParamID id) const;

    void reset_to_default(ParamID id);

    void reset_all_to_defaults();

    bool reset_triggers_rt();

    bool has_trigger_params() const { return !trigger_indices_.empty(); }

    const ParamInfo* info(ParamID id) const;

    bool set_parameter_display_name(ParamID id, std::string name);

    std::string parameter_display_name(ParamID id) const;

    std::uint64_t parameter_display_revision() const noexcept {
        return parameter_display_revision_.load(std::memory_order_acquire);
    }

    template <std::size_t N>
    [[nodiscard]] std::array<float, N> snapshot(
        const std::array<ParamID, N>& ids) const noexcept;

    template <std::size_t N>
    [[nodiscard]] std::array<float, N> snapshot_modulated(
        const std::array<ParamID, N>& ids) const noexcept;

    std::span<const ParamInfo> all_params() const { return params_; }

    std::span<const ParamGroup> all_groups() const { return groups_; }

    std::size_t param_count() const { return params_.size(); }

    void begin_gesture(ParamID id);

    void end_gesture(ParamID id);

    void acquire_gesture(ParamID id);
    void release_gesture(ParamID id);
    void defer_gesture_release(ParamID id);
    void flush_deferred_gesture_releases() noexcept;

    void release_open_gestures();

    std::size_t open_gesture_count() const noexcept { return open_gestures_.size(); }

    void run_gesture_on_main(std::function<void()> gesture);

    std::uint64_t gesture_thread_violation_count() const {
        return gesture_thread_violations_.load(std::memory_order_relaxed);
    }

    void set_main_loop(pulp::events::EventLoop* loop);

    [[nodiscard]]
    ListenerToken add_listener(ParamChangeCallback callback,
                               ListenerThread thread);

    [[nodiscard]]
    ListenerToken add_listener(ParamChangeCallback callback,
                               ListenerThread thread,
                               ListenerRestoreBehavior restore_behavior);

    [[nodiscard]]
    ListenerToken add_audio_listener(ParamChangeCallback callback);

    void remove_listener(ListenerToken& token);

    std::size_t pump_listeners();

    std::size_t reconcile_restore_listeners();

    RtListenerQueueTelemetry rt_listener_queue_telemetry() const;

    void reset_rt_listener_queue_overflow_count();

    void add_listener(ParamChangeCallback callback);

    std::vector<uint8_t> serialize() const;

    bool deserialize(std::span<const uint8_t> data);

    std::uint64_t state_restore_revision() const noexcept {
        return state_restore_revision_.load(std::memory_order_acquire);
    }

    void set_state_version(uint32_t version) { state_version_ = version; }

    uint32_t state_version() const { return state_version_; }

    bool register_state_migration(uint32_t from_version,
                                  uint32_t to_version,
                                  StateMigrationRegistry::MigrationFn migration);

    void copy_state_migrations_from(const StateStore& source);
 
  private:
    friend class ParamReader;

    float value_at_index_(std::size_t index) const noexcept {
        return values_[index].get();
    }
 
    // Member ORDER is load-bearing for the RT->main listener path. The
    // parameter storage (id_to_index_ + values_) MUST be declared before
    // registry_ so that, on destruction (reverse declaration order),
    // registry_ is torn down FIRST. registry_'s value_getter captures
    // `this` and reads id_to_index_/values_ during drain_main_listeners;
    // destroying registry_ before that storage guarantees the getter can
    // never run after the storage it reads is gone. Do not reorder.
    std::vector<ParamInfo> params_;
    std::vector<ParamGroup> groups_;
    std::unordered_map<ParamID, std::size_t> id_to_index_;
    std::vector<ParamValue> values_;
    // Direct ParamID -> index table for the audio-thread readers and writers.
    // Parameter IDs are almost always small integers, so a vector beats a hash
    // lookup. Every ID below kDenseIndexLimit is in the table; only IDs at or
    // above it (a four-char code, an adapter's synthesized Bypass) are looked
    // up in the map, so one such ID does not slow every other lookup.
    static constexpr ParamID kDenseIndexLimit = 1u << 14;
    static constexpr std::uint32_t kNoDenseIndex = 0xFFFF'FFFFu;
    std::vector<std::uint32_t> dense_index_;
    bool has_sparse_ids_ = false;
    static constexpr std::size_t kNoIndex = static_cast<std::size_t>(-1);
    // The dense-table hit is the whole inline path; the hash-map fallback is
    // out of line so get_value() stays small enough to inline into a
    // processor's per-block parameter reads.
    [[gnu::always_inline]] std::size_t index_of(ParamID id) const noexcept {
        if (id < dense_index_.size()) {
            const std::uint32_t i = dense_index_[id];
            return i == kNoDenseIndex ? kNoIndex : i;
        }
        return id >= kDenseIndexLimit && has_sparse_ids_ ? index_of_sparse(id) : kNoIndex;
    }
    [[gnu::noinline]] std::size_t index_of_sparse(ParamID id) const noexcept;
    using ParameterDisplayNames =
        std::unordered_map<ParamID, std::string>;
    mutable std::mutex parameter_display_mutex_;
    std::shared_ptr<const ParameterDisplayNames> parameter_display_names_;
    std::atomic<std::uint64_t> parameter_display_revision_{0};
    std::atomic<std::uint64_t> state_restore_revision_{0};
    std::atomic<std::uint64_t> reconciled_state_restore_revision_{0};
    std::atomic<std::uint64_t> state_generation_{0};
    std::atomic<std::uint32_t> active_state_writers_{0};
    // Indices (into values_/params_) of trigger / momentary parameters, cached
    // at registration so reset_triggers_rt() is allocation-free on the audio
    // thread. Empty for the overwhelmingly common no-trigger store.
    std::vector<std::size_t> trigger_indices_;
    std::shared_ptr<detail::ListenerRegistry> registry_;
 
  public:
    struct ModulationWatchers {
        struct Entry {
            std::uint64_t id = 0;
            ParamID param = 0;
            std::function<void(std::optional<float>)> on_change;
            std::optional<float> last;
        };
        std::vector<Entry> entries;
        std::uint64_t next_id = 1;
    };

    class ModulationWatch {
      public:
        ModulationWatch() = default;
        ModulationWatch(std::weak_ptr<ModulationWatchers> owner, std::uint64_t id) noexcept
            : owner_(std::move(owner)), id_(id) {}
        ModulationWatch(ModulationWatch&& other) noexcept
            : owner_(std::move(other.owner_)), id_(std::exchange(other.id_, 0)) {}
        ModulationWatch& operator=(ModulationWatch&& other) noexcept {
            if (this != &other) {
                reset();
                owner_ = std::move(other.owner_);
                id_ = std::exchange(other.id_, 0);
            }
            return *this;
        }
        ModulationWatch(const ModulationWatch&) = delete;
        ModulationWatch& operator=(const ModulationWatch&) = delete;
        ~ModulationWatch() {
            reset();
        }
        void reset() noexcept {
            if (id_ == 0)
                return;
            if (auto owner = owner_.lock()) {
                auto& e = owner->entries;
                e.erase(std::remove_if(e.begin(), e.end(),
                                       [this](const auto& x) { return x.id == id_; }),
                        e.end());
            }
            id_ = 0;
        }
        explicit operator bool() const noexcept {
            return id_ != 0;
        }
 
      private:
        std::weak_ptr<ModulationWatchers> owner_;
        std::uint64_t id_ = 0;
    };
 
  private:
    std::shared_ptr<ModulationWatchers> modulation_watchers_ =
        std::make_shared<ModulationWatchers>();
    void service_modulation_watchers();
    std::vector<ListenerToken> permanent_listener_tokens_;
    StateMigrationRegistry migrations_;
    uint32_t state_version_ = 1;
 
    std::function<void(ParamID)> on_begin_gesture_;
    std::function<void(ParamID)> on_end_gesture_;
 
    // Parameters with an open gesture (begin without a matching end). Keeps
    // begin/end balanced 1:1 toward the host and lets release_open_gestures()
    // close everything still held on editor teardown. Main-thread-only, like
    // the gesture entry points that mutate it.
    std::unordered_set<ParamID> open_gestures_;
    // Direct begin/end callers retain the historical duplicate-suppression
    // contract independently of shared editor leases. open_gestures_ is the
    // union that is actually open toward the host.
    std::unordered_set<ParamID> direct_gestures_;
    std::unordered_map<ParamID, std::size_t> gesture_leases_;
    std::vector<ParamID> deferred_gesture_releases_;
 
    // Close a retired owner's pending host bracket before a replacement owner
    // is allowed to begin the same parameter again.
    void flush_deferred_gesture_release(ParamID id) noexcept;
    std::uint64_t advance_state_generation() noexcept;
 
    // Off-main-thread gesture-misuse counter. Bumped (relaxed) by
    // begin_gesture/end_gesture when a MainThreadDispatcher backend is live but
    // the caller is not on the main thread. Observability only — never blocks
    // the audio path (gestures are main-thread UI events, not audio).
    std::atomic<std::uint64_t> gesture_thread_violations_{0};
 
public:
    void set_gesture_callbacks(
        std::function<void(ParamID)> begin_fn,
        std::function<void(ParamID)> end_fn)
    {
        on_begin_gesture_ = std::move(begin_fn);
        on_end_gesture_ = std::move(end_fn);
        // A new callback set is a new host/editor session: any gesture tracked
        // against the previous callbacks is stale. Reset so a re-opened editor
        // (e.g. AU clears callbacks on teardown, then re-installs on reopen)
        // does not have a lingering entry suppress a fresh begin_gesture.
        open_gestures_.clear();
        direct_gestures_.clear();
        gesture_leases_.clear();
        deferred_gesture_releases_.clear();
    }
};
 
inline float ParamReader::get() const noexcept {
    return store_ != nullptr ? store_->value_at_index_(index_) : 0.0f;
}
 
// ─── Template definitions ──────────────────────────────────────────────────
 
template <std::size_t N>
std::array<float, N> StateStore::snapshot(
    const std::array<ParamID, N>& ids) const noexcept
{
    std::array<float, N> out{};
    for (std::size_t i = 0; i < N; ++i) {
        out[i] = get_value(ids[i]);
    }
    return out;
}
 
template <std::size_t N>
std::array<float, N> StateStore::snapshot_modulated(
    const std::array<ParamID, N>& ids) const noexcept
{
    std::array<float, N> out{};
    for (std::size_t i = 0; i < N; ++i) {
        out[i] = get_modulated(ids[i]);
    }
    return out;
}
 
} // namespace pulp::state