control_gpu_health_provider.hpp

Go to the documentation of this file.

#pragma once
 
#include <chrono>
#include <cstdint>
#include <memory>
#include <optional>
#include <string>
#include <thread>
#include <vector>
 
namespace pulp::tooling::gpu_health {
struct HealthReadResult;
}
 
namespace pulp::inspect {

class ControlGpuHealthProvider final {
  public:
    enum class CacheState { cold, warm };
    enum class CacheProvenance {
        unknown,
        fresh_process,
        explicit_cache_reset,
        same_process_editor_reopen,
    };
    enum class MeasurementEndpoint { native_compositor_presentation, headless_capture_complete };
 
    struct ReferenceHost {
        std::string host_id;
        double refresh_rate_hz = 0.0;
    };
 
    struct Config {
        std::string pulp_build_id;
        std::string campaign_id{"editor-open"};
        MeasurementEndpoint measurement_endpoint =
            MeasurementEndpoint::native_compositor_presentation;
        std::optional<std::string> gpu_evidence_id;
        std::optional<std::string> trace_evidence_id;
        std::string budget_id{"pulp.editor-first-visible.v1"};
        std::uint32_t budget_version = 1;
        bool budget_ratified = false;
        std::optional<double> threshold_ms;
        std::optional<std::string> threshold_source;
        std::vector<ReferenceHost> reference_hosts;
        std::optional<std::string> vellum_revision;
        std::optional<std::string> source_signature_sha256;
        std::optional<std::string> shader_signature_sha256;
        std::optional<std::string> expected_target_signature_sha256;
        std::uint32_t event_capacity = 64;
        std::chrono::milliseconds timeout{5000};
        bool seed_blank_first_frame = false;
    };
 
    struct AdapterIdentity {
        enum class Type {
            unknown,
            integrated_gpu,
            discrete_gpu,
            cpu,
        };
 
        bool available = false;
        bool native_bridge = false;
        Type type = Type::unknown;
        bool null_backend = false;
        std::string backend;
        std::string name;
        std::string vendor;
        std::string architecture;
    };
 
    struct FrameObservation {
        std::string lifecycle_id;
        std::optional<CacheState> observed_cache_state;
        CacheProvenance cache_provenance = CacheProvenance::unknown;
        AdapterIdentity adapter;
        bool capture_valid = false;
        bool content_floor_passed = false;
        bool gpu_submission_observed = false;
        bool native_present_observed = false;
        std::optional<std::chrono::steady_clock::time_point> native_presented_at;
        std::optional<double> interaction_hitch_ms;
        std::optional<double> shader_compile_ms;
        std::optional<double> upload_ms;
        std::optional<double> hidden_frame_ms;
        std::optional<double> present_ms;
        std::optional<std::string> trace_evidence_id;
        std::vector<std::string> missing_trace_categories;
        std::uint64_t non_transparent_pixel_count = 0;
        std::uint64_t distinct_color_count = 0;
        std::string observed_signature_sha256;
        std::optional<std::string> observed_source_signature_sha256;
        std::optional<std::string> observed_shader_signature_sha256;
        std::chrono::steady_clock::time_point observed_at;
    };

    std::vector<std::string> derive_missing_trace_categories(const FrameObservation& frame) const;
 
    explicit ControlGpuHealthProvider(Config config);
    ~ControlGpuHealthProvider();
    ControlGpuHealthProvider(const ControlGpuHealthProvider&) = delete;
    ControlGpuHealthProvider& operator=(const ControlGpuHealthProvider&) = delete;

    bool begin_editor_open(CacheState cache_state,
                           std::chrono::steady_clock::time_point requested_at) noexcept;
    bool record_presented_frame(const FrameObservation& frame) noexcept;
    bool record_timeout(std::chrono::steady_clock::time_point observed_at) noexcept;
    bool record_instance_lost() noexcept;
    bool record_dropped_events(std::uint64_t count) noexcept;
    bool awaiting_frame() const noexcept;
 
    std::shared_ptr<const tooling::gpu_health::HealthReadResult> snapshot() const noexcept;
 
  private:
    struct Impl;
    std::unique_ptr<Impl> impl_;
};
 
} // namespace pulp::inspect