font_flight_recorder.hpp

Go to the documentation of this file.

// font_flight_recorder.hpp
//
// FontFlightRecorder is the process-global sink for FallbackTraceRecord
// events produced by FontResolver every time a typeface resolves. It's a
// bounded ring buffer; callers (the --font-trace CLI flag, the
// import-missing-font-advisor, a developer's debug overlay) can drain it to
// see exactly which font cascade step produced each glyph.
//
// The recorder runs always-on with a reasonable default capacity
// (1024 records) — there's no measurable overhead at typical UI
// rates and the diagnostic value of "what fonts did the last
// frame use" is high. Callers that need a different cap can call
// set_capacity(); 0 disables recording entirely.
 
#pragma once
 
#include <cstddef>
#include <cstdint>
#include <memory>
#include <string>
#include <vector>
 
namespace pulp::canvas {

struct FallbackTraceRecord {
    std::string  requested_family;
    std::string  selected_family;
    std::uint8_t origin;        
    std::uint64_t generation;   
    std::uint64_t sequence;     
};
 
class FontFlightRecorder {
public:
    static FontFlightRecorder& instance();

    void record_fallback(const FallbackTraceRecord& record);

    std::vector<FallbackTraceRecord> drain();

    std::vector<FallbackTraceRecord> snapshot() const;

    void clear();

    void set_capacity(std::size_t capacity);
    std::size_t capacity() const noexcept;

    std::size_t size() const noexcept;
 
private:
    FontFlightRecorder();
    ~FontFlightRecorder();
    FontFlightRecorder(const FontFlightRecorder&)            = delete;
    FontFlightRecorder& operator=(const FontFlightRecorder&) = delete;
 
    struct Impl;
    std::unique_ptr<Impl> impl_;
};

std::string flight_recorder_drain_json();
 
} // namespace pulp::canvas