pulp::runtime::Tracing Class Reference

Process-global tracing controller. More...

#include <trace_session.hpp>

Static Public Member Functions
static bool	start (const std::vector< std::string > &categories={}, const std::string &out_path={}, std::uint32_t ring_kb=80u *1024u)
	Start the single process session if none is active.
static TraceStartResult	start_exclusive (const std::vector< std::string > &categories={}, const std::string &out_path={}, std::uint32_t ring_kb=80u *1024u)
	Start only when no process session exists, reporting whether this call actually applied the requested configuration.
static TraceStopResult	stop ()
	Stop the active session, flush, and write the .pftrace. No-op → ok=false.
static TraceStopResult	stop_owned (const TraceOwnership &ownership)
	Stop only when both opaque ownership fields match the active session.
static TraceOwnershipStatus	ownership_status (const TraceOwnership *ownership)
	Read active and ownership state under one runtime lock.
static bool	active ()
	Whether a process session is currently active.
static void	attach ()
	Reference-counted attachment for multi-instance hosts.
static void	detach ()
static std::uint64_t	session_generation ()
	Generation of the session currently active, or 0 when none is.
static int	attachment_count ()
	Current attachment count.

Detailed Description

Process-global tracing controller.

All methods are thread-safe and safe to call when PULP_TRACING=OFF (they no-op).

── Lifetime contract (WAH-4) ────────────────────────────────────────────

The session, its refcount, and its auto-flush timer are PROCESS-global and live in whichever module first links this TU. In a DAW that means the plug-in binary, which can be unloaded (FreeLibrary / dlclose) while the host keeps running. Every thread this class owns must therefore be joined before the last detach() returns — a detached worker that wakes after unload executes freed code, and on Windows that is a hard crash inside the loader lock rather than a diagnosable fault.

So: detach() is not merely a refcount decrement. The final one cancels and JOINS the auto-flush timer before flushing the session. attach()/detach() must be balanced and called off the audio thread (adapters call them from their construct/destroy paths); ScopedTracingAttachment below makes that balance structural rather than conventional.

Timeouts are tagged with a session generation. Without it, a timer armed for session N could stop session N+1 — a real sequence when a user closes and reopens an editor inside the PULP_TRACE_SECONDS window, which silently truncated the second capture.

Member Function Documentation

active()

bool pulp::runtime::Tracing::active ( )

static

Whether a process session is currently active.

attach()

void pulp::runtime::Tracing::attach ( )

static

Reference-counted attachment for multi-instance hosts.

The last detach after all instances are gone cancels and JOINS the auto-flush timer, then tears the session down. Balanced calls; prefer ScopedTracingAttachment.

attachment_count()

int pulp::runtime::Tracing::attachment_count ( )

static

Current attachment count.

Exposed for tests and for a host that wants to assert its attach/detach balance.

detach()

void pulp::runtime::Tracing::detach ( )

static

ownership_status()

TraceOwnershipStatus pulp::runtime::Tracing::ownership_status ( const TraceOwnership * ownership )

static

Read active and ownership state under one runtime lock.

session_generation()

std::uint64_t pulp::runtime::Tracing::session_generation ( )

static

Generation of the session currently active, or 0 when none is.

Bumped by every successful start(). A timeout captured for generation N is a no-op once this has moved on, so a stale timer cannot truncate a later capture. Exposed for tests.

start()

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

static

Start the single process session if none is active.

categories selects the enabled track-event categories (empty = all). out_path overrides the default temp path (also overridable via $PULP_TRACE_PATH). ring_kb sizes the in-process ring (default 80 MB). Returns true when a session is active on return, including after an idempotent duplicate.

start_exclusive()

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

static

Start only when no process session exists, reporting whether this call actually applied the requested configuration.

stop()

TraceStopResult pulp::runtime::Tracing::stop ( )

static

Stop the active session, flush, and write the .pftrace. No-op → ok=false.

stop_owned()

TraceStopResult pulp::runtime::Tracing::stop_owned ( const TraceOwnership & ownership )

static

Stop only when both opaque ownership fields match the active session.

---

The documentation for this class was generated from the following file:

• /home/runner/work/pulp/pulp/core/runtime/include/pulp/runtime/trace_session.hpp