Cache the send effect snapshot in the audio callback

Author: juzzlin

CHANGELOG

@@ -40,6 +40,11 @@ New features:
 
 Bug fixes:
 
+* Avoid copying the send effect list on every audio callback
+  - AudioEngine caches a snapshot of the send effect rack and refreshes it only
+    when the rack changes (tracked by a version counter), instead of copying the
+    effect vector under a lock every buffer
+
 * Fix per-buffer heap allocation in the Sampler audio path
   - processAudio() now reuses member scratch buffers (main mix and per-pad
     sub-mixes) instead of allocating on every audio callback

src/domain/effects/effect_rack.cpp

@@ -40,6 +40,7 @@ void EffectRack::setEffect(size_t index, EffectS effect)
     std::lock_guard<std::recursive_mutex> lock { m_mutex };
     if (index < m_effects.size()) {
         m_effects[index] = std::move(effect);
+        markChanged();
     }
 }
 
@@ -48,6 +49,7 @@ void EffectRack::swapEffects(size_t indexA, size_t indexB)
     std::lock_guard<std::recursive_mutex> lock { m_mutex };
     if (indexA < m_effects.size() && indexB < m_effects.size()) {
         std::swap(m_effects[indexA], m_effects[indexB]);
+        markChanged();
     }
 }
 
@@ -56,9 +58,20 @@ void EffectRack::removeEffect(size_t index)
     std::lock_guard<std::recursive_mutex> lock { m_mutex };
     if (index < m_effects.size()) {
         m_effects.erase(m_effects.begin() + index);
+        markChanged();
     }
 }
 
+void EffectRack::markChanged()
+{
+    m_version.fetch_add(1, std::memory_order_release);
+}
+
+uint64_t EffectRack::version() const
+{
+    return m_version.load(std::memory_order_acquire);
+}
+
 EffectRack::EffectS EffectRack::effect(size_t index) const
 {
     std::lock_guard<std::recursive_mutex> lock { m_mutex };
@@ -172,6 +185,7 @@ void EffectRack::clear()
 {
     std::lock_guard<std::recursive_mutex> lock { m_mutex };
     std::fill(m_effects.begin(), m_effects.end(), nullptr);
+    markChanged();
 }
 
 void EffectRack::serializeEffectsToXml(ProjectWriter & writer) const
@@ -195,6 +209,7 @@ void EffectRack::deserializeEffectsFromXml(ProjectReader & reader)
 {
     std::lock_guard<std::recursive_mutex> lock { m_mutex };
     std::fill(m_effects.begin(), m_effects.end(), nullptr);
+    markChanged();
 
     while (reader.readNextStartElement()) {
         if (reader.name() == Constants::NahdXml::xmlKeyEffect()) {
@@ -224,6 +239,7 @@ void EffectRack::deserializeEffect(ProjectReader & reader)
             m_effects.resize(targetIndex + 1, nullptr);
         }
         m_effects[targetIndex] = std::move(effect);
+        markChanged();
     } else {
         reader.skipCurrentElement();
     }
@@ -280,6 +296,7 @@ bool EffectRack::importEffectSettings(size_t index, ProjectReader & reader)
                             effect->deserializeParametersFromXml(reader);
                             effect->sync();
                             m_effects[index] = std::move(effect);
+                            markChanged();
                             return true;
                         } else {
                             reader.skipCurrentElement();
@@ -297,6 +314,7 @@ bool EffectRack::importEffectSettings(size_t index, ProjectReader & reader)
                                     effect->deserializeParametersFromXml(reader);
                                     effect->sync();
                                     m_effects[index] = std::move(effect);
+                                    markChanged();
                                     return true;
                                 } else {
                                     reader.skipCurrentElement();

src/domain/effects/effect_rack.hpp

@@ -18,6 +18,8 @@
 
 #include "../dsp/audio_context.hpp"
 #include "effect.hpp"
+#include <atomic>
+#include <cstdint>
 #include <memory>
 #include <mutex>
 #include <vector>
@@ -43,6 +45,11 @@ class EffectRack
     size_t effectCount() const;
     bool hasEffects() const;
 
+    //! Monotonically increasing counter bumped whenever the effect list changes (effects added,
+    //! removed, swapped, cleared or deserialized). Lets callers cache a snapshot of effects() and
+    //! only refresh it when this changes, avoiding a per-audio-callback copy. Cheap atomic read.
+    uint64_t version() const;
+
     void process(AudioContext & outputContext, const double * sendBus, size_t effectIndex);
     void processInPlace(AudioContext & context);
     std::vector<size_t> sidechainDependencies() const;
@@ -61,7 +68,10 @@ class EffectRack
     bool importEffectSettings(size_t index, ProjectReader & reader);
 
 private:
+    void markChanged();
+
     std::vector<EffectS> m_effects;
+    std::atomic<uint64_t> m_version { 0 };
     mutable std::recursive_mutex m_mutex;
 };
 

src/infra/audio/audio_engine.cpp

@@ -350,7 +350,13 @@ void AudioEngine::process(AudioContext & context)
     if (!bufferSize) {
         return;
     }
-    auto effects = m_sendEffectRack->effects();
+    // Refresh the cached send-effects snapshot only when the rack actually changed, so the common
+    // case avoids copying the vector (and bumping shared_ptr refcounts) under a lock every callback.
+    if (const auto version = m_sendEffectRack->version(); version != m_sendEffectsVersion) {
+        m_sendEffectsSnapshot = m_sendEffectRack->effects();
+        m_sendEffectsVersion = version;
+    }
+    auto & effects = m_sendEffectsSnapshot;
     const size_t sendCount = effects.size();
     const size_t laneCount = m_workerPool->laneCount();
 

src/infra/audio/audio_engine.hpp

@@ -18,6 +18,8 @@
 
 #include "../../domain/devices/device.hpp"
 
+#include <cstdint>
+#include <limits>
 #include <map>
 #include <memory>
 #include <mutex>
@@ -81,6 +83,11 @@ class AudioEngine
     std::map<size_t, DeviceS> m_devices;
     std::unique_ptr<EffectRack> m_sendEffectRack;
     std::unique_ptr<EffectRack> m_insertEffectRack;
+
+    // Cached snapshot of the send effect rack, refreshed only when the rack changes so that process()
+    // does not copy the effect vector (and bump shared_ptr refcounts) on every audio callback.
+    std::vector<std::shared_ptr<Effect>> m_sendEffectsSnapshot;
+    uint64_t m_sendEffectsVersion = std::numeric_limits<uint64_t>::max();
     std::unique_ptr<RealTimeWorkerPool> m_workerPool;
     std::vector<AudioEngineWorkBuffer> m_workBuffers;
     std::vector<DeviceS> m_deviceSnapshot;

src/unit_tests/effect_rack_test/effect_rack_test.cpp

@@ -50,6 +50,40 @@ void EffectRackTest::test_addRemove_shouldAddAndRemoveEffects()
     QCOMPARE(rack.effect(0), nullptr);
 }
 
+void EffectRackTest::test_version_shouldChangeOnlyWhenEffectsChange()
+{
+    EffectRack rack;
+
+    // Adding, removing, swapping and clearing effects must bump the version so cached snapshots of
+    // effects() (e.g. in AudioEngine::process) get refreshed. Read-only access must not.
+    const auto v0 = rack.version();
+
+    rack.setEffect(0, std::make_shared<Volume>());
+    const auto v1 = rack.version();
+    QVERIFY(v1 != v0);
+
+    // Read-only queries leave the version unchanged.
+    (void)rack.effects();
+    (void)rack.effect(0);
+    (void)rack.effectCount();
+    QCOMPARE(rack.version(), v1);
+
+    rack.setEffect(1, std::make_shared<Volume>());
+    const auto v2 = rack.version();
+    QVERIFY(v2 != v1);
+
+    rack.swapEffects(0, 1);
+    const auto v3 = rack.version();
+    QVERIFY(v3 != v2);
+
+    rack.removeEffect(0);
+    const auto v4 = rack.version();
+    QVERIFY(v4 != v3);
+
+    rack.clear();
+    QVERIFY(rack.version() != v4);
+}
+
 void EffectRackTest::test_process_shouldProcessAudio()
 {
     EffectRack rack;

src/unit_tests/effect_rack_test/effect_rack_test.hpp

@@ -28,6 +28,7 @@ private slots:
     void initTestCase();
     void cleanupTestCase();
     void test_addRemove_shouldAddAndRemoveEffects();
+    void test_version_shouldChangeOnlyWhenEffectsChange();
     void test_process_shouldProcessAudio();
     void test_processInPlace_shouldApplyEffectToBuffer();
     void test_serialization_shouldSerializeAndDeserializeEffects();

src/unit_tests/side_chain_audio_test/side_chain_audio_test.cpp

@@ -17,6 +17,7 @@
 
 #include "../../common/constants.hpp"
 #include "../../domain/devices/device.hpp"
+#include "../../domain/dsp/volume.hpp"
 #include "../../domain/effects/compressor.hpp"
 #include "../../infra/audio/audio_engine.hpp"
 #include "../../infra/xml/nahd_xml_reader.hpp"
@@ -426,6 +427,35 @@ void SideChainAudioTest::test_audioEngine_serialAndExclusive_shouldProduceIdenti
     QVERIFY(std::abs(serialOut[0] - 5.0) < 1e-9);
 }
 
+void SideChainAudioTest::test_audioEngine_sendEffectAddedAfterProcess_shouldBeApplied()
+{
+    // AudioEngine caches a snapshot of the send effect rack and only refreshes it when the rack's
+    // version changes. A send effect added *after* the first process() must still be applied.
+    AudioEngine engine;
+    const auto device = std::make_shared<MockDevice>("Source");
+    device->setGenerateSignal(true); // Emits 1.0
+    device->setReverbSend(0, 1.0f); // Route fully to send bus 0
+    engine.setDevice(0, device);
+
+    std::vector<double> buffer(128, 0.0);
+    AudioContext context { std::span(buffer.data(), 128), 64, 44100 };
+
+    // No send effect yet: output is just the device's dry signal.
+    engine.process(context);
+    QVERIFY(std::abs(buffer[0] - 1.0) < 1e-9);
+
+    // Add a send effect after the first process(); the cached snapshot must refresh.
+    const auto volume = std::make_shared<Volume>();
+    volume->setVolume(0.5f);
+    engine.sendEffectRack().setEffect(0, volume);
+
+    std::fill(buffer.begin(), buffer.end(), 0.0);
+    engine.process(context);
+
+    // Output = dry device (1.0) + wet send (0.5 * 1.0 - 1.0 = -0.5) = 0.5.
+    QVERIFY(std::abs(buffer[0] - 0.5) < 1e-6);
+}
+
 } // namespace noteahead
 
 QTEST_GUILESS_MAIN(noteahead::SideChainAudioTest)

src/unit_tests/side_chain_audio_test/side_chain_audio_test.hpp

@@ -30,6 +30,7 @@ private slots:
     void test_audioEngine_process_runtimeSidechainChange_shouldRebuildGraph();
     void test_audioEngine_rebuildProcessingGraph_shouldHandleCircularDependencyGracefully();
     void test_audioEngine_serialAndExclusive_shouldProduceIdenticalOutput();
+    void test_audioEngine_sendEffectAddedAfterProcess_shouldBeApplied();
     void test_compressorEffect_process_shouldApplySidechainGainReduction();
     void test_compressorEffect_sideChainLpf_bypass_shouldPreserveGainReduction();
     void test_compressorEffect_sideChainLpf_lowCutoff_shouldAttenuateAcDetectorSignal();