profile.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 XCENA Inc.
//
// pxl::Profile — libpxl-side entry points into the xpti Profile API.
//
// v1 design (see tools/xprofiler/docs/design/profiling-api-redesign-plan.md):
//
//   pxl::enableProfiling(cfg);       // starts the current v1 default device session
//   pxl::disableProfiling();
//   pxl::isProfilingEnabled();
//   pxl::Profile = xpti::Profile;    // alias for Profile::open(path)
//   pxl::ScopedProfile p(cfg);       // RAII helper
//
// Live in-process attach (pxl::profile() / Map::profile() / Job::profile()) is NOT part
// of v1: it requires the xpti live-session manager, deferred to a Phase 3 follow-up (see
// design doc). v1 provides collection (enableProfiling / ScopedProfile / XPTI_ENABLE) plus
// offline analysis via Profile::open(path). The current facade delegates to xpti for
// session state and keeps ownership only so ScopedProfile does not stop sessions it did
// not start.
 
#pragma once
 
#include "xpti/profile.hpp"
 
// Forward decl for xpti::ProfileConfig — already provided by xpti.hpp / xpti_types.hpp.
namespace xpti
{
struct ProfileConfig;
}
 
namespace pxl
{
 
// Type alias so users can write pxl::Profile::open(path).
using Profile = xpti::Profile;
 
// Session control -----------------------------------------------------------------
// enableProfiling returns true iff this call actually started a session; false if a
// session was already active (the caller's cfg is not re-applied in that case).
bool enableProfiling(const xpti::ProfileConfig& cfg);
void disableProfiling();
bool isProfilingEnabled();
 
// RAII helper. Idempotent w.r.t. already-enabled sessions: if profiling is already
// on when the ctor runs, the dtor does NOT disable.
class ScopedProfile
{
public:
    explicit ScopedProfile(const xpti::ProfileConfig& cfg);
    ~ScopedProfile();
 
    ScopedProfile(const ScopedProfile&) = delete;
    ScopedProfile& operator=(const ScopedProfile&) = delete;
    ScopedProfile(ScopedProfile&&) = delete;
    ScopedProfile& operator=(ScopedProfile&&) = delete;
 
private:
    bool enabledByMe_;
};
 
namespace detail
{
// Returns true iff this call actually enabled profiling. Internal — users must
// not call this directly; it exists for callers that need to serialize the
// check-then-act race.
bool tryEnableProfiling(const xpti::ProfileConfig& cfg);
}  // namespace detail
 
}  // namespace pxl