reload_transaction.hpp File Reference

The verify-before-commit reload transaction — ties the Phase-0 primitives into one operation: load a candidate logic library, gate it on reload-ABI version, build-fingerprint, and parameter-contract compatibility, and only then construct + swap it into the live ProcessorHotSwapSlot. More...

#include <pulp/format/processor.hpp>
#include <pulp/format/reload/build_fingerprint.hpp>
#include <pulp/format/reload/param_contract.hpp>
#include <pulp/format/reload/processor_hotswap_slot.hpp>
#include <pulp/format/reload/reload_abi.hpp>
#include <pulp/format/reload/reload_library.hpp>
#include <pulp/format/reload/swap_pack.hpp>
#include <pulp/format/reload/revocation.hpp>
#include <pulp/state/store.hpp>
#include <chrono>
#include <cmath>
#include <cstddef>
#include <cstdint>
#include <exception>
#include <filesystem>
#include <memory>
#include <optional>
#include <string>
#include <system_error>
#include <variant>
#include <vector>

Go to the source code of this file.

Classes
struct	pulp::format::reload::ReloadMetrics
	DSP-axis reload timings (control-thread, off the audio path). More...
struct	pulp::format::reload::ReloadOutcome
struct	pulp::format::reload::GatedImage
	A logic image that passed the pre-construction gates (reload-ABI version + build fingerprint) with its factory resolved. More...
struct	pulp::format::reload::SwapPackTrust
	Trust material for verifying a swap-pack-delivered logic image BEFORE it is loaded. More...
class	pulp::format::reload::ReloadSession
	Owns the session-stable state for a series of hot reloads of one plugin instance — the slot, the live store, the host fingerprint, the prepare context, and the retained images — so callers (a standalone shell, a file-watch controller) issue reload(path) without re-threading five coupled arguments, and the lifetime contract is enforced by construction. More...

Namespaces
namespace	pulp
namespace	pulp::format
	What the product grants a device: the quota table indexed by capability tier and live thermal state.
namespace	pulp::format::reload

Functions
std::optional< ReloadOutcome >	pulp::format::reload::verify_pack_before_load (const SwapPackTrust &trust, const std::string &library_path)
	Verify trust on the RAW bytes on disk and confirm library_path is a member of the verified pack — the strict pre-dlopen trust phase.
std::variant< GatedImage, ReloadOutcome >	pulp::format::reload::gate_logic_image (const std::string &library_path, const BuildFingerprint &host_fingerprint, const SwapPackTrust *trust=nullptr)
	Load library_path and run the pre-construction gates — reload-ABI version, then build fingerprint — and resolve the create symbol.
ReloadOutcome	pulp::format::reload::reload_processor_from_library (ProcessorHotSwapSlot &slot, const std::string &library_path, const BuildFingerprint &host_fingerprint, state::StateStore &live_store, const PrepareContext &prepare_ctx, std::vector< ReloadLibrary > &retained_images, const SwapPackTrust *trust=nullptr)
	Attempt to hot-reload slot from the logic library at library_path.

Detailed Description

The verify-before-commit reload transaction — ties the Phase-0 primitives into one operation: load a candidate logic library, gate it on reload-ABI version, build-fingerprint, and parameter-contract compatibility, and only then construct + swap it into the live ProcessorHotSwapSlot.

Ordering is deliberately fail-closed: every gate that can reject does so BEFORE the audio-visible swap, so a bad candidate never reaches the audio thread. The displaced processor is returned by the slot and destroyed on the CALLER's (control) thread.

State continuity (one canonical answer): the new processor binds to the caller's LIVE StateStore, which already holds the current parameter values and — by the contract gate — the same parameter set, so the swap preserves the sound with no value copying. param_contract.hpp::carry_state() is the ALTERNATE model (copy live values into a processor that owns its own store); it is NOT used on this shell path and exists for hosts that give each processor an independent store. The transaction is the canonical path.

Most callers should use ReloadSession (below), which owns the session-stable state; reload_processor_from_library() is the stateless core it delegates to.