daniel/reasampler
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Cut shell/instrument comment bloat ~34% (comments only, zero code change)

Browse Source
This commit is contained in:
Daniel Harvey
2026-07-29 20:48:43 -04:00
parent 1f24c4b095
commit d4d29146c7
19 changed files with 1131 additions and 1769 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/shell/instrument/processor_reload.cpp
+122 -187
View File
@@ -1,11 +1,9 @@
// processor_reload.cpp — the ReaSamplerProcessor's OFF-AUDIO-THREAD instrument
// lifecycle: reloadInstrument (self-contained refs resolve + WAV decode + keymap
// build), the safety-critical publishBuiltLocked drain-slot swap, the voice-param
// light rebuild, idle-drain retirement, the pre-v10 legacy-lift gate, the S9/S8
// bank-sync poll, and the pS-usage publish. Split out of reasampler_processor.cpp
// (Q-W2v, T4-12). NOTHING here runs on the audio thread — process() (the lifecycle
// TU) only touches the atomics this family publishes; the atomic-pointer-swap
// pattern deliberately gains NO virtual seam (T4-29).
// processor_reload.cpp — ReaSamplerProcessor's off-audio-thread instrument lifecycle:
// reloadInstrument (self-contained refs resolve + WAV decode + keymap build), the
// safety-critical publishBuiltLocked drain-slot swap, the voice-param light rebuild,
// idle-drain retirement, the pre-v10 legacy-lift gate, the bank-sync poll, and the
// usage publish. Nothing here runs on the audio thread — process() only touches the
// atomics this family publishes; the atomic-pointer-swap pattern gains no virtual seam.
#include "shell/instrument/reasampler_processor.h"
@@ -18,20 +16,19 @@
#include <utility>
#include <vector>
#include "core/capture/capture_paths.h" // resolveBankFile (shared M4 path resolution)
#include "core/capture/capture_paths.h" // resolveBankFile (shared path resolution)
#include "core/capture/wav_codec.h" // parseWavLayout, extractFloatFrames (shared WAV parse)
#include "core/instrument/map/bank_sync.h" // S9/S8 pure decisions: parseBankGeneration, consumeDecision
#include "core/instrument/map/sample_map.h" // refs resolve, buildZonedKeymap (pS self-contained)
#include "core/util/file_bytes.h" // shared whole-file loader (Q-W1, T2-03)
#include "core/wire/assignment_request.h" // decodeAssignmentRequest (S8 request wire parse)
#include "core/wire/sample_usage.h" // pS-usage publish plan + wire (prune-protection seam)
#include "core/instrument/map/bank_sync.h" // pure decisions: parseBankGeneration, consumeDecision
#include "core/instrument/map/sample_map.h" // refs resolve, buildZonedKeymap (self-contained)
#include "core/util/file_bytes.h" // shared whole-file loader
#include "core/wire/assignment_request.h" // decodeAssignmentRequest (request wire parse)
#include "core/wire/sample_usage.h" // usage publish plan + wire (prune-protection seam)
#include "ext_keys.h" // kProjExtBanksKey / kProjExtBankGenKey / kProjExtAssignKey
namespace reasampler::vst {
using namespace instrument::map; // resolution + bank-sync vocabulary this TU drives
using namespace reasampler::wire; // assignment_request + sample_usage wire records
// Q-W6 (shim retired): the shared WAV parse + file loader by their real homes.
using capture::extractFloatFrames;
using capture::parseWavLayout;
using capture::resolveBankFile;
@@ -40,20 +37,15 @@ using util::readFileBytes;
namespace {
// S16 Preserve-mode voice cap: a Preserve voice runs a per-voice OLA pitch shifter and is
// materially heavier than a Varispeed voice. A Preserve note-on past the cap is dropped rather
// than glitching (Varispeed notes are unaffected). Set from the measured/estimated per-voice
// cost — see the handoff CPU note. 8 is conservative pending DAW profiling. Phase S: the
// polyphony bound itself is now the USER-SET voiceCount (1..32, persisted) — this cap stays
// FIXED so raising the voice count never multiplies shifter CPU past the profiled budget.
// Preserve-mode voice cap: a Preserve voice runs a per-voice OLA pitch shifter and is
// materially heavier than a Varispeed voice, so a note-on past the cap is dropped rather
// than glitching. 8 is conservative pending DAW profiling; fixed regardless of the
// user-set voiceCount (1..32) so raising polyphony never multiplies shifter CPU past budget.
constexpr std::size_t kPreserveVoiceCap = 8;
// pS-usage: mint a fresh publish identity — 32 lowercase hex chars from the OS entropy
// source. Used for BOTH the persisted per-instance key guid (instanceGuid_) and the
// in-memory per-LIFETIME owner nonce (usageNonce_). Uniqueness (not cryptographic
// strength) is the requirement: two instances sharing a key is the copy-collision
// planUsagePublish resolves fail-safe anyway; the mint just makes accidental collision
// vanishingly unlikely. Off-thread only.
// Mints a fresh publish identity (32 lowercase hex chars) for either the persisted
// instanceGuid_ or the in-memory usageNonce_. Uniqueness, not cryptographic strength, is
// the requirement — planUsagePublish resolves a collision fail-safe anyway.
std::string mintUsageInstanceGuid() {
std::random_device rd;
std::mt19937_64 gen((static_cast<std::uint64_t>(rd()) << 32) ^ rd());
@@ -65,17 +57,11 @@ std::string mintUsageInstanceGuid() {
return std::string(buf);
}
// Whole-file reads go through the shared core/util readFileBytes (Q-W1, T2-03).
// Off-thread only (blocking file I/O). Empty on any failure — the caller treats
// an unreadable WAV as "nothing to play".
// Resolve a project-relative WAV path (the M4 way persist does), read + decode it (file
// I/O — off-thread only), and apply the S7 cross-mode channel policy for `mode`: mono mode
// downmixes to one channel (existing policy); stereo mode yields two channels (dual-mono for
// a mono source, L/R for a stereo source) — see decodeChannels. Returns nullopt when the path
// fails to resolve, the file is unreadable, the WAV is malformed, or the decode yields no
// frames — the caller drops the zone (zoned map) or plays silence (single capture). Shared by
// the zoned build and the single-capture path so both decode identically for the active mode.
// Resolves a project-relative WAV path, reads + decodes it (file I/O, off-thread only),
// and applies the cross-mode channel policy for `mode` (mono downmix; stereo -> dual-mono
// for a mono source, L/R for a stereo source — see decodeChannels). Returns nullopt on any
// resolve/read/decode failure — the caller drops the zone or plays silence. Shared by the
// zoned build and the single-capture path.
std::optional<DecodedZonePcm> decodeRelative(const std::string& projectDir,
const std::string& relativePath,
ChannelMode mode) {
@@ -95,22 +81,19 @@ std::optional<DecodedZonePcm> decodeRelative(const std::string& projectDir,
} // namespace
std::string ReaSamplerProcessor::reloadInstrument() {
// OFF THE AUDIO THREAD. Serialize concurrent reloads (editor click + setState) so
// the retired-slot free is single-writer. This mutex is NEVER taken on the audio
// thread — process() only touches the atomic.
// OFF THE AUDIO THREAD. Serializes concurrent reloads (editor click + setState) so the
// retired-slot free is single-writer; never taken on the audio thread.
std::lock_guard<std::mutex> lock(reloadMutex_);
// Mint this reload's generation number first so we can stamp the built instrument
// with it before publishing. Under reloadMutex_ no other reload races here.
// Mint this reload's generation number first so the built instrument is stamped
// before publishing.
const std::uint64_t gen = reloadGeneration_.fetch_add(1, std::memory_order_relaxed) + 1;
// 1. SELF-CONTAINED RESOLUTION (pS). The instance-OWNED refs table is the source of
// truth for what to decode. The live bank blob, WHEN readable, is folded into the
// table first (refreshRefsFromBank) — that is the browser's copy-the-ref-in
// mechanism and the S9 recapture sync in one — but its absence changes NOTHING
// below: a project restored before the extension's PROJEXTSTATE parses (or with
// the extension absent entirely) resolves + plays from the persisted refs. The
// project dir comes from REAPER itself (EnumProjects), not from the extension.
// 1. Self-contained resolution: the instance-owned refs table is the source of truth.
// The live bank blob, when readable, is folded in first (refreshRefsFromBank — the
// browser's copy-the-ref-in + recapture-sync mechanism), but its absence changes
// nothing below — a project restored before PROJEXTSTATE parses (or with the
// extension absent) resolves + plays from the persisted refs.
const std::string selId = selectedSampleId();
const PerformanceMap map = performanceMap();
const std::vector<std::string> ids = referencedSampleIds(selId, map);
@@ -120,20 +103,18 @@ std::string ReaSamplerProcessor::reloadInstrument() {
bridge_.readReasamplerExtState(kProjExtBanksKey);
std::lock_guard<std::mutex> rl(refsMutex_);
if (banksJson) refreshRefsFromBank(sampleRefs_, *banksJson, ids);
// The LOAD path never prunes the owned table: dropping entries here on a transient
// bank miss could destroy the owned intrinsics of the previous selection — the ONE
// copy that survives with the extension absent. Entries for de-referenced ids stay
// in memory (bounded by in-session browsing); hygiene lives at the PERSIST boundary,
// where getState filters its snapshot via retainRefs to what the instance plays.
// The LOAD path never prunes the owned table: dropping entries on a transient bank
// miss could destroy the owned intrinsics of the previous selection — the ONE copy
// that survives with the extension absent. Hygiene lives at the PERSIST boundary
// (getState filters via retainRefs to what the instance plays).
refs = sampleRefs_; // snapshot for the decode below (outside the refs lock)
}
const std::string projectDir = bridge_.activeProjectDir();
// The active channel mode (S7) governs how each WAV decodes (mono downmix vs 2-channel).
// Read once under its mutex, off the audio thread, before the decode loop. The single-
// capture branch below may auto-default it (GA) before its decode.
// Governs how each WAV decodes (mono downmix vs 2-channel); the single-capture branch
// below may auto-default it before its decode.
ChannelMode mode = channelMode();
// Phase S: snapshot the voice-system parameters once — they are baked into the built
// engine's construction (the engine's config is immutable; a later change rebuilds).
// Snapshot the voice-system parameters once — baked into the built engine's
// construction (immutable config; a later change rebuilds).
int builtVoiceCount = kDefaultVoiceCount;
VoiceMode builtVoiceMode = VoiceMode::Poly;
MonoTrigger builtMonoTrigger = MonoTrigger::Retrigger;
@@ -149,12 +130,10 @@ std::string ReaSamplerProcessor::reloadInstrument() {
Keymap km;
bool haveKeymap = false;
// 2. Tier 1 first: if the instrument's performance map is non-empty, resolve its
// zones against the OWNED refs (an id with no ref drops cleanly), decode each
// zone's WAV off-thread, and build the ZONED keymap. Each surviving zone plays
// its sample repitched from its effective root note (override > ref intrinsic >
// C4). A zone whose WAV fails to decode — a MISSING FILE included — is dropped
// (not the whole map): the defined no-play, no crash, no retry loop.
// 2. Zoned build: if the performance map is non-empty, resolve its zones against the
// owned refs (an id with no ref drops cleanly), decode each zone's WAV off-thread,
// and build the keymap. A zone whose WAV fails to decode is dropped, not the whole
// map — the defined no-play, no crash, no retry loop.
if (!map.empty()) {
const ResolvedPerformance resolved = resolvePerformanceFromRefs(refs, map);
if (!resolved.zones.empty()) {
@@ -174,19 +153,15 @@ std::string ReaSamplerProcessor::reloadInstrument() {
}
}
// 3. Single-capture fast path (S10): an empty performance map plays the ONE
// deliberately-selected capture chromatically across the whole keyboard, resolved
// against the OWNED refs. NO first-sample fallback: an EMPTY selection (or a
// selection with no ref) resolves to nothing, so an un-picked instrument stays
// SILENT (the editor shows its "pick a capture" empty state) rather than
// auto-playing sample #1 (S10 policy reversal of the S4 convenience default).
// 3. Single-capture fast path: an empty performance map plays the one selected capture
// chromatically across the whole keyboard. No first-sample fallback: an empty
// selection (or one with no ref) resolves to nothing, so an un-picked instrument
// stays silent rather than auto-playing sample #1.
if (!haveKeymap) {
if (const SelectedSample* sel = findRef(refs, selId)) {
// GA auto-default: channelModeFor computes the mode from the loaded capture's
// REQUESTED channel count (always 2 for extension captures; mono only for
// ingest-imported mono files). An unknown count (0) or explicit user choice
// returns the current mode unchanged. Decode-only: the output bus is fixed
// stereo, so no bus work follows a flip.
// Auto-default: channelModeFor computes the mode from the loaded capture's
// channel count (always 2 for extension captures; mono only for ingest-imported
// mono files). An unknown count (0) or explicit user choice keeps the mode.
{
std::lock_guard<std::mutex> cm(channelModeMutex_);
channelMode_ = channelModeFor(sel->channelCount, channelMode_,
@@ -206,10 +181,9 @@ std::string ReaSamplerProcessor::reloadInstrument() {
}
if (haveKeymap) {
// Preserve OLA window in OUTPUT frames from the host sample rate (kPreserveWindowMs).
// Every voice's shifter is pre-sized to this off-thread here, so process()-time
// note-on never allocates. Floored at 2 so a valid window is always a real ring
// (which also covers a pathological host rate <= 0 — no rate literal needed).
// Preserve OLA window in output frames from the host rate (kPreserveWindowMs),
// pre-sized here so process()-time note-on never allocates. Floored at 2 so a
// valid window is always a real ring, covering a pathological host rate <= 0 too.
std::int64_t preserveWindow = static_cast<std::int64_t>(
kPreserveWindowMs * sampleRate_ / 1000.0 + 0.5);
if (preserveWindow < 2) preserveWindow = 2;
@@ -218,21 +192,14 @@ std::string ReaSamplerProcessor::reloadInstrument() {
kPreserveVoiceCap, preserveWindow, builtVoiceMode, builtMonoTrigger);
}
// 4. Publish. Atomically install the new instrument; the DISPLACED one moves into the
// DRAIN slot (FA1, bug 3b) where process() keeps rendering its ringing voices —
// a reload never cuts a sounding note; the next note-on plays the new state. The
// instrument evicted FROM the drain slot (two reloads old) goes to the graveyard
// (process may still be mid-block reading it). A null `built` (no ref / unreadable
// WAV) installs silence while the displaced tails still ring out via the drain.
// `built` is heap-owned; release() hands ownership to the atomic; the drain-evicted
// pointer is re-owned by the graveyard.
// 4. Publish: atomically install the new instrument via the drain-slot swap (see the
// header). A null `built` (no ref / unreadable WAV) installs silence while any
// displaced tails still ring out via the drain.
publishBuiltLocked(std::move(built));
// 5. pS-usage: publish this instance's held captures so the extension's prune can
// never reclaim them (see publishUsage). AFTER the instrument swap, still off the
// audio thread and under reloadMutex_. Publishes regardless of decode success:
// the holds are the refs the instance RETAINS (its play-set), not what decoded —
// a transiently unreadable WAV must stay protected.
// 5. Publish this instance's held captures so the extension's prune can never reclaim
// them. Regardless of decode success: the holds are the refs the instance retains
// (its play-set), not what decoded — a transiently unreadable WAV stays protected.
publishUsage(refs, ids);
return resolvedId;
}
@@ -252,15 +219,13 @@ void ReaSamplerProcessor::publishUsage(const SampleRefs& refs,
}
std::lock_guard<std::mutex> lock(usageMutex_);
// A never-published instance with nothing held writes nothing — no key litter for
// fresh/empty instances. Once an identity exists, empties DO publish (they release
// holds the prune would otherwise keep protecting).
// A never-published instance with nothing held writes nothing (no key litter); once an
// identity exists, empties do publish (releasing protected holds).
if (instanceGuid_.empty() && mine.holds.empty()) return;
if (instanceGuid_.empty()) instanceGuid_ = mintUsageInstanceGuid();
// The per-LIFETIME owner nonce rides INSIDE the wire (UsageRecord.ownerNonce) so
// planUsagePublish can prove "exactly this incarnation wrote the key" — a same-track
// sibling's byte-identical hold set can never pass as ours (its nonce differs), so
// siblings always union and never clean-replace over each other's held paths.
// The per-lifetime owner nonce (UsageRecord.ownerNonce) lets planUsagePublish prove
// "exactly this incarnation wrote the key" — a same-track sibling's byte-identical hold
// set can never pass as ours, so siblings always union rather than clean-replace.
if (usageNonce_.empty()) usageNonce_ = mintUsageInstanceGuid();
mine.ownerNonce = usageNonce_;
@@ -268,10 +233,9 @@ void ReaSamplerProcessor::publishUsage(const SampleRefs& refs,
bridge_.readReasamplerExtState(usageKeyFor(instanceGuid_));
const UsagePublishPlan plan = planUsagePublish(existing, mine);
if (plan.remint) {
// This state was cloned onto another track (FX copy / track duplication): take a
// fresh identity and leave the original's record untouched. The abandoned old
// identity's record dies by the extension's liveness rule when its track no
// longer hosts an instance. getState persists the new guid on the next save.
// Cloned onto another track (FX copy / track duplication): take a fresh identity;
// the abandoned old record dies by the extension's liveness rule once its track no
// longer hosts an instance.
instanceGuid_ = mintUsageInstanceGuid();
} else if (plan.skipWrite) {
return; // idle tick, or a union that adds nothing — no ext-state churn
@@ -280,15 +244,8 @@ void ReaSamplerProcessor::publishUsage(const SampleRefs& refs,
}
void ReaSamplerProcessor::publishBuiltLocked(std::unique_ptr<LoadedInstrument> built) {
// REQUIRES reloadMutex_ held (single-writer over both slots + the graveyard). Shared by
// reloadInstrument and rebuildVoiceEngine — the one safety-critical swap dance.
//
// Bounded reclaim: free graveyard entries whose installedAt < seen, where seen is
// the minimum installedAt process() published over the pointers it holds. Both
// slots are monotone in installedAt, so seen is monotone and any future process()
// load yields installedAt >= seen — an entry below seen is provably unreachable
// (see the header proof). Remaining entries drain at setActive(false) / terminate()
// when process is guaranteed stopped.
// REQUIRES reloadMutex_ held. Shared by reloadInstrument and rebuildVoiceEngine — the
// one safety-critical swap dance (see the header's drain-slot proof).
const std::uint64_t seen = processGeneration_.load(std::memory_order_acquire);
graveyard_.erase(
std::remove_if(graveyard_.begin(), graveyard_.end(),
@@ -302,10 +259,9 @@ void ReaSamplerProcessor::publishBuiltLocked(std::unique_ptr<LoadedInstrument> b
}
void ReaSamplerProcessor::rebuildVoiceEngine() {
// OFF THE AUDIO THREAD (the editor's voice-deck click handlers). See the header contract:
// a voice-param change touches NO audio data, so this rebuilds the engine
// around a COPY of the live instrument's already-decoded keymap — no bridge, no disk —
// and publishes through the same drain-slot swap, so ringing tails survive.
// Off the audio thread. A voice-param change touches no audio data, so this rebuilds
// the engine around a copy of the live instrument's already-decoded keymap — no
// bridge, no disk — and publishes through the same drain-slot swap.
std::lock_guard<std::mutex> lock(reloadMutex_);
LoadedInstrument* cur = live_.load(std::memory_order_acquire);
if (!cur) return; // nothing loaded: the new params bake into the next real reload.
@@ -321,13 +277,14 @@ void ReaSamplerProcessor::rebuildVoiceEngine() {
}
const std::uint64_t gen = reloadGeneration_.fetch_add(1, std::memory_order_relaxed) + 1;
// Same Preserve-window derivation as reloadInstrument (kPreserveWindowMs at the host rate).
// Same Preserve-window derivation as reloadInstrument.
std::int64_t preserveWindow = static_cast<std::int64_t>(
kPreserveWindowMs * sampleRate_ / 1000.0 + 0.5);
if (preserveWindow < 2) preserveWindow = 2;
// Deep-copy the decoded PCM + zones. Safe to read concurrently with process(): the keymap
// is immutable after construction, and under reloadMutex_ nobody can free `cur`.
// Deep-copy the decoded PCM + zones: safe to read concurrently with process() because
// the keymap is immutable after construction and reloadMutex_ prevents `cur` from
// being freed.
Keymap km = cur->keymap;
auto built = std::make_unique<LoadedInstrument>(
std::move(km), static_cast<std::size_t>(builtVoiceCount), gen,
@@ -336,23 +293,19 @@ void ReaSamplerProcessor::rebuildVoiceEngine() {
}
void ReaSamplerProcessor::retireIdleDrain() {
// Phase S (FA1-review Major #2). Cheap early-out BEFORE the lock: 0 means "no drain, or
// it still sounds" — the common case costs one relaxed load and no mutex.
// Cheap early-out before the lock: 0 means "no drain, or it still sounds".
const std::uint64_t idleGen = drainIdleGeneration_.load(std::memory_order_acquire);
if (idleGen == 0) return;
std::lock_guard<std::mutex> lock(reloadMutex_);
LoadedInstrument* drain = draining_.load(std::memory_order_acquire);
// Retire ONLY if the publication names the drain currently in the slot. A stale value
// (about an already-evicted, older drain) can never match the newer occupant's
// installedAt — the slot is monotone in generation — so a mid-swap race is closed by
// this identity check, not by timing.
// Retire only if the publication names the drain currently in the slot — a stale value
// (an already-evicted, older drain) can never match the newer occupant's installedAt
// (monotone in generation), closing a mid-swap race by identity rather than timing.
if (!drain || drain->installedAt != idleGen) return;
draining_.store(nullptr, std::memory_order_release);
graveyard_.push_back(std::unique_ptr<LoadedInstrument>(drain));
// Prune what is now provably unreachable — the same monotone-generation proof as the
// reload path's reclaim (see reloadInstrument): an entry with installedAt < seen cannot be
// held by process() now or ever again. The just-parked drain frees here immediately when
// process() has already published past it; otherwise on the next reload/retire/deactivate.
// Prune what is now provably unreachable (same monotone-generation proof as
// reloadInstrument's reclaim).
const std::uint64_t seen = processGeneration_.load(std::memory_order_acquire);
graveyard_.erase(
std::remove_if(graveyard_.begin(), graveyard_.end(),
@@ -363,18 +316,16 @@ void ReaSamplerProcessor::retireIdleDrain() {
}
bool ReaSamplerProcessor::legacyLiftShouldRun() {
// #A terminating guard for the pre-v10 legacy lift. The caller has already established
// refs-empty + intent; this decides whether a lift attempt can MAKE PROGRESS before
// paying for a full reload. Once concluded, the steady state is this one relaxed load —
// no bank read, no parse, no reload churn.
// Terminating guard for the pre-v10 legacy lift (caller has already established
// refs-empty + intent). Once concluded, the steady state is one relaxed load — no bank
// read, no parse, no reload churn.
if (legacyLiftConcluded_.load(std::memory_order_relaxed)) return false;
const LegacyLiftDecision decision = legacyLiftDecision(
bridge_.readReasamplerExtState(kProjExtBanksKey),
referencedSampleIds(selectedSampleId(), performanceMap()));
if (decision == LegacyLiftDecision::Stale) {
// Provably stale (the bank parses and knows none of the referenced ids): give up
// PERMANENTLY. A later bank change that re-introduces an id bumps the generation,
// and the genChanged reload refreshes the refs without consulting this latch.
// Provably stale: give up permanently. A later bank change that re-introduces an
// id bumps the generation, and genChanged refreshes the refs without this latch.
legacyLiftConcluded_.store(true, std::memory_order_relaxed);
return false;
}
@@ -383,21 +334,18 @@ bool ReaSamplerProcessor::legacyLiftShouldRun() {
ReaSamplerProcessor::BankSyncResult
ReaSamplerProcessor::pollBankSync(bool isFocusedTarget) {
// OFF THE AUDIO THREAD (the editor's UI timer calls this). Both reads allocate and call
// REAPER via the bridge — never invoked from process(). A disconnected bridge (non-REAPER
// host, or before connect) yields nullopt for both reads, so this no-ops cleanly.
// Off the audio thread (editor's UI timer only). A disconnected bridge yields nullopt
// for both reads, so this no-ops cleanly.
BankSyncResult result;
// Phase S: park an idle drain snapshot in the graveyard (and prune) on the same UI-timer
// cadence that drives reloads — an edited-away instrument stops costing memory as soon
// as its tails die instead of squatting in the drain slot until the next reload.
// Park an idle drain snapshot in the graveyard on the same cadence that drives
// reloads, so an edited-away instrument stops costing memory as soon as tails die.
retireIdleDrain();
// --- S8: assignment-request consume FIRST -------------------------------------
// Decode the pending assignment request (nullopt when absent/malformed). Resolve its
// (bankId, sampleId) against the live bank blob: selectSample returns non-nullopt only when
// the sampleId names an existing sample (the reader requirement — an unresolvable pair is
// dropped). Then run the pure consume decision against this instance's persisted marker.
// --- Assignment-request consume first -------------------------------------------
// Decodes the pending assignment request (nullopt if absent/malformed), resolves its
// sampleId against the live bank blob (an unresolvable pair is dropped), then runs the
// pure consume decision against this instance's persisted marker.
std::optional<AssignmentRequest> request;
if (auto raw = bridge_.readReasamplerExtState(kProjExtAssignKey)) {
request = decodeAssignmentRequest(*raw);
@@ -405,26 +353,24 @@ ReaSamplerProcessor::pollBankSync(bool isFocusedTarget) {
bool resolves = false;
if (request) {
// Resolve the assigned sample against the CURRENT bank blob (a fresh read, so a request
// whose sample was rolled back by an extension undo resolves to nullopt -> dropped).
// Resolve against the CURRENT bank blob (a fresh read, so a request whose sample
// was rolled back by an extension undo resolves to nullopt -> dropped).
if (auto banksJson = bridge_.readReasamplerExtState(kProjExtBanksKey)) {
resolves = selectSample(*banksJson, request->sampleId).has_value();
}
}
// Read lastConsumed and conditionally write it back under a single lock scope so there
// is no interleave window between the read and the write (a concurrent getState could
// otherwise observe a stale marker between the two separate lock acquisitions).
// Read + conditionally write lastConsumed under one lock scope so a concurrent
// getState cannot observe a stale marker between two separate acquisitions.
std::int64_t lastConsumed = 0;
const AssignConsumeDecision decision = [&] {
std::lock_guard<std::mutex> lock(assignMarkerMutex_);
lastConsumed = lastConsumedAssignGeneration_;
const AssignConsumeDecision d =
consumeDecision(request, lastConsumed, resolves, isFocusedTarget);
// Advance the persisted consumed marker whenever the decision consumed the request
// (applied OR dropped-as-seen). getState will persist it on the next project save so
// a re-open does not re-apply. A non-target instance leaves the marker (decision
// returns it unchanged) so it stays eligible if focus later lands here.
// Advance the persisted marker whenever the decision consumed the request
// (applied or dropped-as-seen); a non-target instance leaves it unchanged so it
// stays eligible if focus later lands here.
if (d.consumedGeneration != lastConsumed) {
lastConsumedAssignGeneration_ = d.consumedGeneration;
}
@@ -432,13 +378,12 @@ ReaSamplerProcessor::pollBankSync(bool isFocusedTarget) {
}();
if (decision.apply) {
// Apply the assignment as this instance's own selection (the same path a user card-pick
// takes) — the instrument updates its OWN state, never the bank. reloadInstrument below
// rebuilds against the new selection, so skip a redundant reload here.
// Apply as this instance's own selection (the instrument updates its own state,
// never the bank); reloadInstrument below rebuilds against it.
setSelectedSampleId(decision.sampleId);
// Zone-bleed fix (3a), peer of the editor's Browse Load: a stale full-range zone
// materialized for the previously loaded sample would shadow the assigned pick under
// first-match resolve. Authored maps (any narrow key range) are untouched.
// Peer of the editor's Browse Load: a stale full-range zone from the previous
// sample would shadow the assigned pick under first-match resolve. Authored maps
// (narrow key ranges) are untouched.
PerformanceMap reconciled = performanceMap();
if (reconcileSingleCaptureZones(reconciled, decision.sampleId)) {
setPerformanceMap(reconciled);
@@ -446,13 +391,10 @@ ReaSamplerProcessor::pollBankSync(bool isFocusedTarget) {
result.applied = true;
}
// --- S9: bank-generation change-detection -------------------------------------
// Read the generation stamp; parse (absent/malformed -> 0, the pre-S9 default). FIRST poll
// (lastSeenBankGeneration_ == -1 sentinel): BASELINE the seen value without a reload —
// setState already loaded the instrument from its OWNED refs (pS), so a redundant reload
// on open would only churn. A later
// generation CHANGE (a recapture/ingest/remove, or an undo that lowers it) then drives the
// reload. An assignment we just applied also needs a reload; fold both into ONE (coalesced).
// --- Bank-generation change-detection -------------------------------------------
// First poll (lastSeenBankGeneration_ == -1 sentinel) baselines without a reload —
// setState already loaded from owned refs, so a redundant reload on open would only
// churn. A later generation change (recapture/ingest/remove/undo) drives the reload.
std::int64_t currentGen = kBankGenerationAbsent;
if (auto rawGen = bridge_.readReasamplerExtState(kProjExtBankGenKey)) {
currentGen = parseBankGeneration(*rawGen);
@@ -462,18 +404,12 @@ ReaSamplerProcessor::pollBankSync(bool isFocusedTarget) {
!firstPoll && bankGenerationChanged(lastSeenBankGeneration_, currentGen);
lastSeenBankGeneration_ = currentGen;
// LEGACY LIFT (pre-v10 blob): the restored state carries intent (a selection or zones)
// but NO owned refs — a pre-pS blob had no path table, so the setState-time reload had
// nothing to decode unless the bank happened to be readable already. Reload on this
// editor tick until the lift lands: reloadInstrument folds the bank blob into the refs
// when readable, after which the table is non-empty and this never fires again (the
// next save is then self-contained). A deliberately-empty instance has no intent and
// never churns; a bank that is not readable YET retries a cheap null publish on the
// editor cadence only. TERMINATING GUARD (#A, legacyLiftShouldRun): once the bank blob
// PARSES and no referenced id resolves in it, the ids are provably stale — there is
// nothing to lift, so the lift concludes permanently instead of churning a full bank
// read + reload every tick forever. This is a MIGRATION convenience for old projects,
// NOT a playback dependency — a v10 blob plays from its refs with no poll at all (pS).
// Legacy lift (pre-v10 blob): restored state carries intent but no owned refs (old
// blobs had no path table). Reload on this tick until reloadInstrument folds the bank
// blob into the refs (after which this never fires again — the next save is
// self-contained). legacyLiftShouldRun concludes permanently once the bank parses and
// no referenced id resolves — a migration convenience only, never a playback
// dependency (a v10 blob plays from its refs with no poll at all).
bool legacyLift = false;
if (!genChanged && !result.applied && sampleRefs().empty()) {
const bool hasIntent = !selectedSampleId().empty() || !performanceMap().empty();
@@ -481,10 +417,9 @@ ReaSamplerProcessor::pollBankSync(bool isFocusedTarget) {
}
if (genChanged || result.applied || legacyLift) {
reloadInstrument(); // atomic pointer-swap handoff — glitch-free mid-play (S4 graveyard)
// Report the reload distinctly from an S8 apply so the editor re-snapshots its bank
// view. A legacy lift counts only when it actually landed an instrument (otherwise
// every retry tick would churn the editor's caches for nothing).
reloadInstrument(); // atomic pointer-swap handoff — glitch-free mid-play
// Reported distinctly from an applied assignment so the editor re-snapshots its
// bank view; a legacy lift counts only when it actually landed an instrument.
result.reloaded =
genChanged ||
(legacyLift && live_.load(std::memory_order_acquire) != nullptr);