trace_session.hpp

Go to the documentation of this file.

// trace_session.hpp — process-global tracing session control (DEV ONLY).
//
// The lifecycle facade behind <pulp/runtime/trace.hpp>'s span macros. Perfetto's
// Tracing::Initialize() + TrackEvent::Register() are PROCESS singletons and a
// DAW loads N plugin instances into one process, so this is a single process
// wide controller with reference-counted attachment (plan §0b item 5), not a
// per-instance object. One active in-process session at a time.
//
// The API is identical in both build configs: with PULP_TRACING=OFF every call
// is a no-op returning "inactive", so callers need no #ifdef. No Perfetto type
// appears in this header, so OFF consumers pull in zero Perfetto headers.
//
// RT-safety (D1): tracing here rides UI/render/process + OFFLINE-audio threads
// only. Never call start()/the span macros from a live audio callback.
#pragma once
 
#include <atomic>
#include <cstdint>
#include <optional>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
 
namespace pulp::runtime {

bool tracing_reminder_first_time(std::atomic<bool>& already_emitted);

void log_tracing_reminder();
 
namespace detail {

inline constexpr std::uint32_t default_autostart_ring_kb = 80u * 1024u;
inline constexpr std::uint32_t min_autostart_ring_kb = 1024u;
inline constexpr std::uint32_t max_autostart_ring_kb = 4u * 1024u * 1024u;

inline std::optional<std::uint32_t> parse_autostart_ring_kb(const char* raw) {
    if (raw == nullptr || *raw == '\0') return std::nullopt;
    std::uint64_t value = 0;
    for (const char* c = raw; *c != '\0'; ++c) {
        if (*c < '0' || *c > '9') return std::nullopt;
        value = value * 10u + static_cast<std::uint64_t>(*c - '0');
        if (value > max_autostart_ring_kb) return std::nullopt;
    }
    if (value < min_autostart_ring_kb) return std::nullopt;
    return static_cast<std::uint32_t>(value);
}

struct TraceAutostartConfig {
    std::string path;
    std::string seconds;
    std::string ring_kb;
};

inline TraceAutostartConfig parse_trace_autostart(std::string_view text) {
    TraceAutostartConfig config;
    while (!text.empty()) {
        const auto end = text.find('\n');
        auto line = text.substr(0, end);
        text = end == std::string_view::npos ? std::string_view{} : text.substr(end + 1);
        while (!line.empty() && (line.back() == '\r' || line.back() == ' ' || line.back() == '\t'))
            line.remove_suffix(1);
        while (!line.empty() && (line.front() == ' ' || line.front() == '\t')) line.remove_prefix(1);
        if (line.empty() || line.front() == '#') continue;
        const auto eq = line.find('=');
        if (eq == std::string_view::npos) continue;
        const auto key = line.substr(0, eq);
        const auto value = std::string(line.substr(eq + 1));
        if (key == "PULP_TRACE_PATH") config.path = value;
        else if (key == "PULP_TRACE_SECONDS") config.seconds = value;
        else if (key == "PULP_TRACE_RING_KB") config.ring_kb = value;
    }
    return config;
}

inline std::string trace_autostart_expand(const std::string& path, const std::string& temp_dir) {
    constexpr std::string_view token = "$TMPDIR";
    if (path.compare(0, token.size(), token) != 0) return path;
    std::string base = temp_dir;
    if (!base.empty() && base.back() == '/') base.pop_back();
    return base + path.substr(token.size());
}

inline std::string trace_autostart_output_path(const std::string& path,
                                               std::string_view process_name, long pid) {
    if (path.empty() || path.back() != '/') return path;
    std::string name(process_name.empty() ? std::string_view{"pulp"} : process_name);
    for (auto& c : name)
        if (c == '/' || c == ' ') c = '_';
    return path + name + "-" + std::to_string(pid) + ".pftrace";
}
 
}  // namespace detail

struct TraceStopResult {
    bool ok = false;            
    std::string path;           
    std::uint64_t trace_bytes = 0;
};

enum class TraceStartStatus {
    Started,
    AlreadyActive,
    Unavailable,
};

class TraceOwnership {
public:
    TraceOwnership(TraceOwnership&& other) noexcept
        : generation_(std::exchange(other.generation_, 0)),
          token_(std::exchange(other.token_, 0)) {}
    TraceOwnership& operator=(TraceOwnership&& other) noexcept {
        if (this != &other) {
            generation_ = std::exchange(other.generation_, 0);
            token_ = std::exchange(other.token_, 0);
        }
        return *this;
    }
    TraceOwnership(const TraceOwnership&) = delete;
    TraceOwnership& operator=(const TraceOwnership&) = delete;
 
private:
    friend class Tracing;
    TraceOwnership(std::uint64_t generation,
                   std::uint64_t token) noexcept
        : generation_(generation), token_(token) {}
 
    std::uint64_t generation_ = 0;
    std::uint64_t token_ = 0;
};
 
struct TraceStartResult {
    TraceStartStatus status = TraceStartStatus::Unavailable;
    std::optional<TraceOwnership> ownership;
};

struct TraceOwnershipStatus {
    bool active = false;
    bool owned = false;
};

class Tracing {
public:
    static bool start(const std::vector<std::string>& categories = {},
                      const std::string& out_path = {},
                      std::uint32_t ring_kb = 80u * 1024u);

    static TraceStartResult start_exclusive(
        const std::vector<std::string>& categories = {},
        const std::string& out_path = {},
        std::uint32_t ring_kb = 80u * 1024u);

    static TraceStopResult stop();

    static TraceStopResult stop_owned(const TraceOwnership& ownership);

    static TraceOwnershipStatus ownership_status(
        const TraceOwnership* ownership);

    static bool active();

    static void attach();
    static void detach();

    static std::uint64_t session_generation();

    static int attachment_count();
};

class ScopedTracingAttachment {
public:
    ScopedTracingAttachment() : attached_(true) { Tracing::attach(); }
    ScopedTracingAttachment(const ScopedTracingAttachment&) = delete;
    ScopedTracingAttachment& operator=(const ScopedTracingAttachment&) = delete;
    ScopedTracingAttachment(ScopedTracingAttachment&& other) noexcept
        : attached_(other.attached_) {
        other.attached_ = false;
    }
    ScopedTracingAttachment& operator=(ScopedTracingAttachment&& other) noexcept {
        if (this != &other) {
            reset();
            attached_ = other.attached_;
            other.attached_ = false;
        }
        return *this;
    }
    ~ScopedTracingAttachment() { reset(); }

    void reset() noexcept {
        if (!attached_) return;
        attached_ = false;
        Tracing::detach();
    }
 
    bool attached() const noexcept { return attached_; }
 
private:
    bool attached_ = false;
};
 
}  // namespace pulp::runtime