live_dsp_telemetry.hpp

Go to the documentation of this file.

#pragma once

 
#include <atomic>
#include <chrono>
#include <cstdint>
#include <span>
#include <string_view>
#include <vector>
 
namespace pulp::audio {

enum class LiveDspNodeKind : std::uint8_t {
    Unknown = 0,
    AudioInput,
    AudioOutput,
    Plugin,
    Gain,
    MidiInput,
    MidiOutput,
    Custom,
    Utility,
};
 
const char* to_string(LiveDspNodeKind kind) noexcept;

struct LiveDspNodeInfo {
    std::uint64_t node_id = 0;
    LiveDspNodeKind kind = LiveDspNodeKind::Unknown;
    std::uint32_t input_ports = 0;
    std::uint32_t output_ports = 0;
    char name[64] = {};
 
    void set_name(std::string_view value) noexcept;
};
 
struct LiveDspTelemetryConfig {
    std::uint32_t ring_blocks = 256;
    std::uint32_t percentile_window_blocks = 256;
    float graph_overload_load = 1.0f;
    bool spectral_diagnostics = false;
};
 
struct LiveDspSpectralDiagnostic {
    std::uint64_t node = 0, root = 0, epoch = 0, expected_sequence = 0;
    std::uint64_t errors = 0;
    std::int64_t first_error_position = 0, latest_origin = 0;
    std::uint8_t first_error = 0;
};

struct LiveDspNodeSummary {
    std::uint64_t node_id = 0;
    LiveDspNodeKind kind = LiveDspNodeKind::Unknown;
    char name[64] = {};
 
    std::uint64_t sample_count = 0;   
    std::int64_t last_elapsed_ns = 0;
    std::int64_t min_elapsed_ns = 0;
    std::int64_t max_elapsed_ns = 0;
    std::int64_t mean_elapsed_ns = 0;
    std::int64_t p50_elapsed_ns = 0;
    std::int64_t p95_elapsed_ns = 0;
    std::int64_t p99_elapsed_ns = 0;
    std::int64_t jitter_ns = 0;       
    float last_budget_fraction = 0.0f;
    std::uint64_t over_budget_attributions = 0;
};

struct LiveDspTelemetrySnapshot {
    bool available = false;
    bool enabled = false;
    std::uint64_t sequence_number = 0;
 
    std::uint32_t node_count = 0;
    std::uint64_t blocks_written = 0;
    std::uint64_t blocks_drained = 0;
    std::uint64_t blocks_dropped = 0;
    std::uint64_t graph_over_budget_blocks = 0;
 
    double sample_rate = 0.0;
    std::uint32_t last_frame_count = 0;
    std::int64_t last_available_ns = 0;
    std::int64_t last_graph_elapsed_ns = 0;
    float last_graph_load = 0.0f;
 
    std::vector<LiveDspNodeSummary> nodes;  
    std::vector<LiveDspSpectralDiagnostic> spectral;
    std::uint64_t observed_block = 0;
    std::uint64_t observed_drops = 0;
    std::uint64_t age_blocks = 0; 
};
 
class LiveDspTelemetryStore;

class LiveDspTelemetryNodeScope {
public:
    LiveDspTelemetryNodeScope() noexcept = default;
    LiveDspTelemetryNodeScope(LiveDspTelemetryStore* store, std::uint32_t ring_slot,
                              std::uint32_t node_slot) noexcept;
    ~LiveDspTelemetryNodeScope() noexcept;
 
    LiveDspTelemetryNodeScope(const LiveDspTelemetryNodeScope&) = delete;
    LiveDspTelemetryNodeScope& operator=(const LiveDspTelemetryNodeScope&) = delete;
    LiveDspTelemetryNodeScope(LiveDspTelemetryNodeScope&& other) noexcept;
    LiveDspTelemetryNodeScope& operator=(LiveDspTelemetryNodeScope&&) = delete;
 
private:
    LiveDspTelemetryStore* store_ = nullptr;
    std::uint32_t ring_slot_ = 0;
    std::uint32_t node_slot_ = 0;
    std::chrono::steady_clock::time_point start_{};
};

class LiveDspTelemetryBlockWriter {
public:
    LiveDspTelemetryBlockWriter() noexcept = default;
    LiveDspTelemetryBlockWriter(LiveDspTelemetryStore* store, std::uint32_t ring_slot,
                                std::uint32_t frame_count, double sample_rate) noexcept;
 
    LiveDspTelemetryBlockWriter(const LiveDspTelemetryBlockWriter&) = delete;
    LiveDspTelemetryBlockWriter& operator=(const LiveDspTelemetryBlockWriter&) = delete;
    LiveDspTelemetryBlockWriter(LiveDspTelemetryBlockWriter&& other) noexcept;
    LiveDspTelemetryBlockWriter& operator=(LiveDspTelemetryBlockWriter&&) = delete;
    ~LiveDspTelemetryBlockWriter() noexcept { finish(); }
 
    bool active() const noexcept { return store_ != nullptr; }

    LiveDspTelemetryNodeScope node(std::uint32_t node_slot) noexcept;

    void finish() noexcept;
 
private:
    LiveDspTelemetryStore* store_ = nullptr;
    std::uint32_t ring_slot_ = 0;
    std::chrono::steady_clock::time_point start_{};
};

class LiveDspTelemetryStore {
public:
    LiveDspTelemetryStore() = default;

    bool prepare(const LiveDspTelemetryConfig& config, std::span<const LiveDspNodeInfo> nodes);
 
    void set_enabled(bool enabled) noexcept { enabled_.store(enabled, std::memory_order_relaxed); }
    bool enabled() const noexcept { return enabled_.load(std::memory_order_relaxed); }
 
    std::uint32_t node_count() const noexcept { return node_count_; }
    bool prepared() const noexcept { return node_count_ != 0; }

    LiveDspTelemetryBlockWriter begin_block(std::uint32_t frame_count, double sample_rate) noexcept;

    void inject_block(std::span<const std::int64_t> node_ns, std::int64_t graph_elapsed_ns,
                      std::uint32_t frame_count, double sample_rate,
                      std::span<const LiveDspSpectralDiagnostic> spectral = {}) noexcept;
    std::span<LiveDspSpectralDiagnostic> spectral_scratch() noexcept {
        return spectral_scratch_;
    }

    std::int64_t* external_record_scratch() noexcept {
        return record_scratch_.empty() ? nullptr : record_scratch_.data();
    }

    void drain() noexcept;

    const LiveDspTelemetrySnapshot& latest() const noexcept { return snapshot_; }
 
    std::uint64_t blocks_written() const noexcept { return write_index_.load(std::memory_order_acquire); }
    std::uint64_t blocks_dropped() const noexcept { return dropped_.load(std::memory_order_relaxed); }
 
private:
    friend class LiveDspTelemetryBlockWriter;
    friend class LiveDspTelemetryNodeScope;
 
    // Audio-thread write helpers (called by the writer/scope friends).
    void write_node_elapsed(std::uint32_t ring_slot, std::uint32_t node_slot,
                            std::int64_t elapsed_ns) noexcept;
    void publish_block(std::uint32_t ring_slot, std::int64_t graph_elapsed_ns) noexcept;
 
    struct BlockHeader {
        std::uint64_t observed_block = 0, observed_drops = 0;
        std::uint32_t frame_count = 0;
        double sample_rate = 0.0;
        std::int64_t available_ns = 0;
        std::int64_t graph_elapsed_ns = 0;
    };
 
    std::uint32_t node_count_ = 0;
    std::uint32_t ring_blocks_ = 0;
    std::uint32_t window_blocks_ = 0;
    float graph_overload_load_ = 1.0f;
 
    std::atomic<bool> enabled_{false};
 
    // SPSC ring: producer = audio thread, consumer = drain(). write_/read_index_
    // are monotonic; slot = index % ring_blocks_.
    std::atomic<std::uint64_t> write_index_{0};
    std::atomic<std::uint64_t> read_index_{0};
    std::atomic<std::uint64_t> dropped_{0};
    std::atomic<std::uint64_t> observed_blocks_{0};
 
    std::vector<BlockHeader> ring_headers_;   // [ring_blocks_]
    std::vector<std::int64_t> ring_node_ns_;  // [ring_blocks_ * node_count_]
    std::vector<LiveDspSpectralDiagnostic> ring_spectral_, spectral_scratch_;
 
    // Drain-side rolling windows (one ring of the last window_blocks_ samples per node).
    std::vector<std::int64_t> window_ns_;     // [node_count_ * window_blocks_]
    std::vector<std::uint32_t> window_pos_;   // [node_count_] next write pos
    std::vector<std::uint32_t> window_len_;   // [node_count_] filled length
    std::vector<std::int64_t> scratch_;       // [window_blocks_] percentile scratch
    std::vector<std::int64_t> record_scratch_;  // [node_count_] external-record staging
 
    std::vector<LiveDspNodeInfo> info_;       // [node_count_]
    std::uint64_t drained_ = 0;
    std::uint64_t over_budget_blocks_ = 0;
    LiveDspTelemetrySnapshot snapshot_;
};
 
}  // namespace pulp::audio