signal_graph_prepared_topology_edit.hpp

Go to the documentation of this file.

#pragma once
 
#include <pulp/host/sample_region_parameters.hpp>
#include <pulp/host/signal_graph_execution_snapshot.hpp>
 
#include <optional>
 
namespace pulp::host {
 
namespace detail {
struct QuiescedPluginLifecycle;
struct QuiescedCustomLifecycle;
struct QuiescedProcessorLifecycle;
} // namespace detail

class ExactParameterNodeClaimPasskey {
    ExactParameterNodeClaimPasskey() = default;
    friend class TimelineGraphPlaybackBinding;
};
 
// Isolated, fail-closed authoring transaction for topology-producing clients.
// This exposes only nodes that SignalGraph owns and can prepare off-side.
class SignalGraph::PreparedTopologyEdit {
  public:
    enum class Result : std::uint8_t {
        Prepared,
        Committed,
        InvalidMutation,
        StaleBase,
        PreflightFailed,
        MidiOutputSnapshotLocalRequired,
        ExternalPluginReprepareRequired,
        BaselinePluginRemovalRequiresRelease,
        ExistingCustomReprepareRequired,
        BaselineCustomRemovalRequiresRelease,
        CustomRegistryConflict,
        CustomInstanceCreateFailed,
        CustomStateRestoreFailed,
        CompileFailed,
        RuntimeAdoptionFailed,
        ParallelWorkerStartFailed,
        QuiescedRollbackFailed,
        NotPrepared,
        AlreadyCommitted,
        RegionRuntimeUnavailable,
        ParameterContractMismatch,
        Staged,
    };
 
    ~PreparedTopologyEdit();
    PreparedTopologyEdit(const PreparedTopologyEdit&) = delete;
    PreparedTopologyEdit& operator=(const PreparedTopologyEdit&) = delete;
 
    bool register_custom_node_type(CustomNodeType type);
    bool register_custom_node_type(CustomNodeType type, SampleKernelDescriptor sample_kernel);
    bool unregister_custom_node_type(std::string_view type_id, int version);
    std::size_t prune_unused_custom_node_types();
    std::size_t custom_node_type_count() const;
 
    NodeId add_input_node(int channels, const std::string& name = "Input");
    SpectralResult<SpectralAnalysisPorts> add_spectral_analysis(SpectralIdentity identity,
                                                                const std::string& name) {
        if (prepare_attempted_ || committed_)
            return {std::nullopt, SpectralError::Busy};
        return candidate_->add_spectral_analysis(identity, name);
    }
    SpectralResult<SpectralStagePorts> add_spectral_stage(SpectralIdentity identity,
                                                          QualifiedSpectralStage stage,
                                                          const std::string& name) {
        if (prepare_attempted_ || committed_)
            return {std::nullopt, SpectralError::Busy};
        return candidate_->add_spectral_stage(identity, std::move(stage), name);
    }
    SpectralResult<SpectralSynthesisPorts> add_spectral_synthesis(SpectralIdentity identity,
                                                                  const std::string& name) {
        if (prepare_attempted_ || committed_)
            return {std::nullopt, SpectralError::Busy};
        return candidate_->add_spectral_synthesis(identity, name);
    }
    GraphResult connect(SpectralOutputPort source, SpectralInputPort destination) {
        if (prepare_attempted_ || committed_)
            return {GraphResult::Code::UnknownPort, 0, 0, "edit is immutable", {}};
        return candidate_->connect(source, destination);
    }
    GraphResult connect(const PortHandle& source, const PortHandle& destination) {
        if (prepare_attempted_ || committed_)
            return {GraphResult::Code::UnknownPort, 0, 0, "edit is immutable", {}};
        return candidate_->connect(source, destination);
    }
    NodeId add_output_node(int channels, const std::string& name = "Output");
    NodeId add_gain_node(const std::string& name = "Gain");
    NodeId add_midi_input_node(const std::string& name = "MIDI In");
    NodeId add_midi_output_node(const std::string& name = "MIDI Out");
    NodeId add_owned_builtin_plugin_node(std::unique_ptr<PluginSlot> slot, int num_inputs,
                                         int num_outputs, const std::string& name);
    NodeId add_processor_node(std::shared_ptr<format::ProcessorNodeInstance> processor,
                              const std::string& name = {});
    NodeId add_processor_node(std::unique_ptr<format::Processor> processor,
                              const std::string& name = {});
    NodeId add_custom_node(std::string_view type_id, const std::string& name = {});
    NodeId add_custom_node(std::string_view type_id, int version,
                           const std::string& name = {});
    NodeId add_unresolved_custom_node(std::string_view type_id, int version,
                                      int num_inputs, int num_outputs,
                                      const std::string& name);
    bool remove_node(NodeId id);
    bool connect(NodeId source, PortIndex source_port, NodeId dest, PortIndex dest_port);
    bool connect_automation(NodeId source, PortIndex source_port, NodeId dest,
                            uint32_t dest_param_id, float range_lo, float range_hi,
                            float smoothing_ms = 0.0f, AutomationMix mix = AutomationMix::Replace);
    bool connect_audio_rate_modulation(NodeId source, PortIndex source_port, NodeId dest,
                                       uint32_t dest_param_id, float range_lo, float range_hi,
                                       float smoothing_ms = 0.0f,
                                       AutomationMix mix = AutomationMix::Replace);
    bool connect_feedback(NodeId source, PortIndex source_port, NodeId dest,
                          PortIndex dest_port);
    bool connect_midi(NodeId source, NodeId dest);
    bool disconnect(NodeId source, PortIndex source_port, NodeId dest, PortIndex dest_port);
    bool disconnect_modulation(NodeId source, PortIndex source_port, NodeId dest,
                               uint32_t dest_param_id, bool audio_rate);
    bool set_node_gain(NodeId id, float linear_gain);
 
    SampleRegionResult declare_sample_region(SampleRegionDefinition definition);
    SampleRegionResult remove_sample_region(SampleRegionId id);
    SampleRegionResult add_sample_region_member(SampleRegionId id, NodeId member,
                                                SampleKernelConfig config);
    SampleRegionResult remove_sample_region_member(SampleRegionId id, NodeId member);
    SampleRegionResult set_sample_kernel_config(SampleRegionId id, NodeId member,
                                                SampleKernelConfig config);
    SampleRegionResult connect_in_sample_region(SampleRegionId id, NodeId source,
                                                PortIndex source_port, NodeId destination,
                                                PortIndex destination_port);
    SampleRegionProof prove_sample_region(SampleRegionId id) const;
    std::optional<SampleRegionDescriptor> sample_region(SampleRegionId id) const;
    std::vector<SampleRegionDescriptor> sample_regions() const;
    SampleRegionParameterContract sample_region_parameter_contract() const;
    SampleRegionResult bind_sample_region_parameters(const SampleRegionParameterBinding& binding);
    const SampleRegionParameterBinding* sample_region_parameter_binding() const noexcept {
        return sample_region_parameter_binding_;
    }
 
    void set_canonical_executor_routing_enabled(bool enabled) noexcept;
    void set_parallel_routing_enabled(bool enabled) noexcept;
    void set_anticipation_enabled(bool enabled) noexcept;
 
    const GraphNode* node(NodeId id) const;
    const std::vector<GraphNode>& nodes() const;
    const std::vector<Connection>& connections() const;
    bool routed_execution_ready(int block_size) const noexcept;
 
    Result prepare(double sample_rate, int max_block_size);
    Result prepare_quiesced(double sample_rate, int max_block_size);
    Result commit();
    ExecutionSnapshot committed_execution_snapshot() const noexcept {
        if (owner_->spectral_mode_.load(std::memory_order_acquire)) {
            owner_->spectral_error_.store(SpectralError::SpectralPinnedExecutionUnsupported,
                                          std::memory_order_relaxed);
            return {};
        }
        return ExecutionSnapshot(*owner_, committed_snapshot_);
    }
    Result last_result() const noexcept { return last_result_; }
 
    // Claims a set of plugin nodes as exact-generation parameter-event sinks
    // owned by `owner`. Gated by a passkey only the timeline binding can mint.
    bool set_exact_parameter_event_nodes(
        const std::shared_ptr<detail::ExactParameterIngressOwner>& owner,
        std::span<const NodeId> nodes, ExactParameterNodeClaimPasskey);
 
  private:
    friend class SignalGraph;
    friend bool register_builtin_sample_region_types(PreparedTopologyEdit& edit);
    explicit PreparedTopologyEdit(SignalGraph& owner);
    bool base_is_current_locked_() const;
    bool is_new_node_(NodeId id) const;
    std::optional<Result> baseline_removal_rejection_locked_() const;
    bool rollback_quiesced_lifecycles_locked_() noexcept;
    void release_new_custom_instances_() noexcept;
    SampleRegionResult replace_sample_region_(SampleRegionDefinition definition, bool declaration);
    SampleRegionResult reject_sample_region_(SampleRegionId id, SampleRegionRefusalReason reason,
                                             std::string message, NodeId node = 0);
    std::optional<Result> sample_region_preparation_result_(double sample_rate, int max_block_size);
 
    template <typename Fn> NodeId add_node_(Fn&& fn) {
        if (mutation_failed_ || committed_ || prepare_attempted_) {
            mutation_failed_ = true;
            return 0;
        }
        const NodeId id = fn();
        if (id == 0)
            mutation_failed_ = true;
        return id;
    }
    template <typename Fn> bool mutate_(Fn&& fn) {
        if (mutation_failed_ || committed_ || prepare_attempted_) {
            mutation_failed_ = true;
            return false;
        }
        const bool ok = fn();
        if (!ok)
            mutation_failed_ = true;
        return ok;
    }
 
    SignalGraph* owner_ = nullptr;
    std::unique_ptr<SignalGraph> candidate_;
    std::shared_ptr<SignalGraph::CompiledGraph> prepared_snapshot_;
    std::shared_ptr<SignalGraph::CompiledGraph> committed_snapshot_;
    std::unordered_set<NodeId> baseline_node_ids_;
    std::unordered_set<std::string> baseline_registry_keys_;
    std::unordered_set<std::string> replaced_registry_keys_;
    std::vector<NodeId> prepared_new_custom_ids_;
    std::vector<detail::QuiescedPluginLifecycle> quiesced_plugins_;
    std::vector<detail::QuiescedCustomLifecycle> quiesced_customs_;
    std::vector<detail::QuiescedProcessorLifecycle> quiesced_processors_;
    std::uint64_t base_authoring_generation_ = 0;
    std::shared_ptr<SignalGraph::CompiledGraph> base_live_;
    bool base_canonical_routing_ = false;
    bool base_parallel_routing_ = false;
    bool base_anticipation_ = false;
    bool mutation_failed_ = false;
    bool prepare_attempted_ = false;
    bool quiesced_lifecycles_dirty_ = false;
    bool committed_ = false;
    const SampleRegionParameterBinding* sample_region_parameter_binding_ = nullptr;
    Result last_result_ = Result::NotPrepared;
};
 
} // namespace pulp::host