processor_hotswap_slot.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/audio/buffer.hpp>
#include <pulp/format/processor.hpp>
#include <pulp/format/state_restore_gate.hpp>
#include <pulp/midi/buffer.hpp>
 
#include <algorithm>
#include <pulp/signal/transition_mixer.hpp>
 
#include <atomic>
#include <cstddef>
#include <cstdint>
#include <memory>
#include <mutex>
#include <shared_mutex>
#include <vector>
 
namespace pulp::format::reload {

using CrossfadeCurve = signal::TransitionCurve;
 
class ProcessorHotSwapSlot {
public:
    ProcessorHotSwapSlot() = default;
    explicit ProcessorHotSwapSlot(std::unique_ptr<Processor> initial)
        : active_(std::move(initial)) {}

    void process(audio::BufferView<float>& out,
                 const audio::BufferView<const float>& in,
                 midi::MidiBuffer& midi_in,
                 midi::MidiBuffer& midi_out,
                 const ProcessContext& ctx) {
        std::shared_lock<std::shared_mutex> lock(mutex_, std::try_to_lock);
        if (!lock.owns_lock() || !active_) {
            passthrough(out, in);
            contention_blocks_.fetch_add(1, std::memory_order_relaxed);
            return;
        }
        active_->process(out, in, midi_in, midi_out, ctx);
        mix_fade_out(out, in, ctx);
    }

    [[nodiscard]] std::unique_ptr<Processor> swap(std::unique_ptr<Processor> next) {
        std::unique_ptr<Processor> displaced;   // returned to caller (instant path)
        std::unique_ptr<Processor> superseded;  // a collapsed prior fade-out
        {
            std::unique_lock<std::shared_mutex> lock(mutex_);
            // DSP-state carry: holding the writer lock proves no audio
            // reader is inside the old processor, so it is safe to serialize its
            // DSP state (delay tails / filter history / phase) and restore it into
            // the incoming one — off the audio thread. Opt-in + cold-start-safe:
            // an empty blob or a false restore leaves `next` freshly prepared and
            // never fails the swap. Skipped on the first install (no old to carry
            // from). The blob is copied while the lock is held, so a plugin that
            // opts in should keep it bounded (a longer copy → a few more audio
            // passthrough blocks during the swap, which the crossfade masks).
            if (active_ && next) {
                // Best-effort: a THROW (not just a false return) must also degrade
                // to cold-start, per the contract — otherwise a serialize/restore
                // bug would reject the whole reload (and a throwing serialize on
                // the already-live OLD processor would block every future reload).
                try {
                    const std::vector<std::byte> blob = active_->serialize_dsp_state();
                    if (!blob.empty()) next->restore_dsp_state(blob);
                } catch (...) {
                    // Swallow: state-carry failed → `next` stays freshly prepared.
                }
            }
            if (!crossfade_ready()) {
                displaced = std::move(active_);
                active_ = std::move(next);
            } else {
                // Collapse any still-pending fade-out: it is fully superseded.
                // We hold the writer lock so no audio reader is inside it; hand
                // it out to be freed AFTER unlock (not under the lock — a slow
                // ~Processor() would lengthen the audio thread's passthrough
                // contention window, as the instant path already avoids).
                // MID-FADE RE-SWAP CONTRACT: with a SINGLE fade slot,
                // a re-swap arriving WITHIN the ~12ms window can only keep one
                // fade-out — the just-displaced processor — and must drop the
                // older fade-out's residual contribution, so the output can STEP
                // at the re-swap instant (bounded, not click-free). This is
                // deliberate: click-free chaining of overlapping fades needs a
                // SECOND fade-out slot + buffer (double the RT cost + memory) to
                // handle an event that is human-file-save paced (far wider than
                // the window) — not worth it. What IS guaranteed and tested
                // (test_hotswap_slot "swap during a fade …"): RT-safe (no
                // alloc/free/leak — the superseded fade-out is reclaimed on the
                // control thread), output stays finite + bounded across the
                // re-swap, and the fade always settles to the NEWEST processor.
                // Restarting the new fade at g=0 (below) is the right single-slot
                // choice: keeping the ramp position or seeding a partial gain both
                // measured WORSE late in the fade (the common case). See 1.7b.
                superseded = std::move(fading_out_);
                fading_out_ = std::move(active_);   // keep the just-displaced DSP for the fade
                active_ = std::move(next);
                fade_mixer_.configure(fade_samples_, fade_mixer_.curve());
                // Nothing to fade from on the first install → mark done immediately.
                fade_done_.store(fading_out_ == nullptr, std::memory_order_release);
            }
        }
        return displaced;  // nullptr on the crossfade path (slot retains the fade-out)
    }

    void reclaim() {
        std::unique_lock<std::shared_mutex> lock(mutex_);
        if (fading_out_ && fade_done_.load(std::memory_order_acquire)) {
            auto old = std::move(fading_out_);
            lock.unlock();
            old.reset();                      // ~Processor() here — control thread
        }
    }

    void reprepare_active(const PrepareContext& ctx) {
        std::unique_lock<std::shared_mutex> lock(mutex_);
        if (active_) active_->prepare(ctx);
    }

    void set_crossfade_samples(std::size_t samples) {
        std::unique_lock<std::shared_mutex> lock(mutex_);
        fade_samples_ = samples;
    }

    void set_crossfade_curve(CrossfadeCurve curve) {
        std::unique_lock<std::shared_mutex> lock(mutex_);
        fade_mixer_.set_curve(curve);   // live: a mid-fade change re-maps gains
    }

    void prepare_crossfade(std::size_t max_frames, std::size_t max_channels) {
        std::unique_lock<std::shared_mutex> lock(mutex_);
        scratch_frames_ = max_frames;
        scratch_channels_ = max_channels;
        scratch_storage_.assign(max_frames * max_channels, 0.0f);
        scratch_ptrs_.resize(max_channels);
        for (std::size_t c = 0; c < max_channels; ++c)
            scratch_ptrs_[c] = scratch_storage_.data() + c * max_frames;
        // Bound the fade-out's MIDI buffers to their reserved capacity so a
        // MIDI-emitting DSP (arp/MIDI-fx) rendered during the fade drops-and-
        // counts on overflow instead of ALLOCATING on the audio thread. reserve()
        // alone does not bound growth; the realtime-capacity-limit flag does.
        fade_midi_in_.reserve(64, 0);
        fade_midi_out_.reserve(64, 0);
        fade_midi_in_.set_realtime_capacity_limit(true);
        fade_midi_out_.set_realtime_capacity_limit(true);
    }

    bool has_active() const {
        std::shared_lock<std::shared_mutex> lock(mutex_);
        return active_ != nullptr;
    }

    template <class Fn>
    auto with_active(Fn&& fn) const -> decltype(fn(std::declval<Processor&>())) {
        std::shared_lock<std::shared_mutex> lock(mutex_);
        if (active_) return fn(*active_);
        return decltype(fn(std::declval<Processor&>())){};
    }

    bool crossfade_active() const {
        std::shared_lock<std::shared_mutex> lock(mutex_);
        return fading_out_ != nullptr && !fade_done_.load(std::memory_order_acquire);
    }

    std::uint64_t contention_blocks() const {
        return contention_blocks_.load(std::memory_order_relaxed);
    }
 
private:
    bool crossfade_ready() const {  // caller holds the lock
        return fade_samples_ > 0 && scratch_frames_ > 0 && scratch_channels_ > 0;
    }
 
    // Render the fading-out processor into scratch and mix it under a smoothstep
    // ramp (old→new). Audio thread, under the shared lock. RT-safe: no alloc
    // (scratch + midi reserved at prepare), no destroy (control thread reclaims).
    void mix_fade_out(audio::BufferView<float>& out,
                      const audio::BufferView<const float>& in,
                      const ProcessContext& ctx) {
        if (!fading_out_ || fade_done_.load(std::memory_order_relaxed)) return;
        const std::size_t frames = out.num_samples();
        if (fade_mixer_.length() == 0 || frames > scratch_frames_) {
            // Safety floor: a block larger than the scratch (the host exceeded
            // its declared max_buffer_size) can't be faded — finish now. This
            // snaps to full-new mid-ramp (a click), but it only triggers on a
            // misdeclared block size; prepare_crossfade() is sized to the host's
            // worst case so the normal path never hits this.
            fade_done_.store(true, std::memory_order_release);
            return;
        }
        const std::size_t ch =
            std::min({out.num_channels(), in.num_channels(), scratch_channels_});
        audio::BufferView<float> sv(scratch_ptrs_.data(), ch, frames);
        fade_midi_in_.clear();
        fade_midi_out_.clear();
        fading_out_->process(sv, in, fade_midi_in_, fade_midi_out_, ctx);
 
        // Blend the fading-out (old) render into the live output over the shared
        // TransitionMixer's curve — click-free at both ends. The same primitive
        // drives the SignalGraph live plugin swap so both share one crossfade law.
        if (signal::blend_fade_out(fade_mixer_, out, sv))
            fade_done_.store(true, std::memory_order_release);
    }
 
    static void passthrough(audio::BufferView<float>& out,
                            const audio::BufferView<const float>& in) {
        // Shared with the format adapters' state-restore gate so every
        // "Processor unavailable this block" path degrades identically.
        passthrough_block(out, in);
    }
 
    mutable std::shared_mutex mutex_;
    std::unique_ptr<Processor> active_;
    std::atomic<std::uint64_t> contention_blocks_{0};
 
    // ── Crossfade state ──────────────────────────────────────────────────────
    std::unique_ptr<Processor> fading_out_;       // retained old DSP during a fade
    std::size_t fade_samples_ = 0;                // configured fade length (0 = instant)
    signal::TransitionMixer fade_mixer_;          // active fade: length + position + curve
    std::atomic<bool> fade_done_{true};           // audio thread sets; reclaim() reads
    std::vector<float> scratch_storage_;          // [channels * frames], allocated off-RT
    std::vector<float*> scratch_ptrs_;
    std::size_t scratch_frames_ = 0;
    std::size_t scratch_channels_ = 0;
    midi::MidiBuffer fade_midi_in_;               // empty MIDI for the fading-out tail
    midi::MidiBuffer fade_midi_out_;              // discarded
};
 
} // namespace pulp::format::reload