Profiling Ranges (ROCTX)#

2026-08-27

2 min read time

Applies to Linux

#include <raft/core/nvtx.hpp>

namespace raft::common::nvtx

inline auto raft::common::nvtx::thread_local_current_range(
) -> std::shared_ptr<const current_range>#

Get a read-only handle to this thread’s current NVTX range name. Pass the returned shared_ptr to another thread to read this thread’s current NVTX range name at any time.

template<typename Domain = domain::app, typename ...Args>
inline void raft::common::nvtx::push_range(
const char *format,
Args... args
)#

Push a named NVTX range.

Template Parameters:

Domain – optional struct that defines the NVTX domain message; You can create a new domain with a custom message as follows:

struct custom_domain { static constexpr char const* name{"custom message"}; }
NB: make sure to use the same domain for push_range and pop_range.

Parameters:
  • format – range name format (accepts printf-style arguments)

  • args – the arguments for the printf-style formatting

template<typename Domain = domain::app>
inline void raft::common::nvtx::pop_range(
)#

Pop the latest range.

Template Parameters:

Domain – optional struct that defines the NVTX domain message; You can create a new domain with a custom message as follows:

struct custom_domain { static constexpr char const* name{"custom message"}; }
NB: make sure to use the same domain for push_range and pop_range.

class current_range#
#include <nvtx_range_stack.hpp>

Shared, read-only handle to the current NVTX range name of a specific thread (set internally by one thread, read publicly by zero or more threads).

Public Functions

inline auto get(
) const -> std::pair<std::string, std::size_t>#

Read the current range name and stack depth (safe to call from any thread).

template<typename Domain = domain::app>
class range#
#include <nvtx.hpp>

Push a named NVTX range that would be popped at the end of the object lifetime.

Refer to Usage for the usage examples.

Template Parameters:

Domain – optional struct that defines the NVTX domain message; You can create a new domain with a custom message as follows:

struct custom_domain { static constexpr char const* name{"custom message"}; }

Public Functions

template<typename ...Args>
inline explicit range(
const char *format,
Args... args
)#

Push a named NVTX range. At the end of the object lifetime, pop the range back.

Parameters:
  • format – range name format (accepts printf-style arguments)

  • args – the arguments for the printf-style formatting

Note

The profiling range support in this header is backed by ROCTX (roctx64) rather than NVIDIA’s NVTX library. The API and header name are kept identical for source compatibility.

To enable profiling ranges, build hipRAFT with -DRAFT_NVTX=ON. This links against roctx64 and defines the NVTX_ENABLED compile-time macro. Profiling annotations can then be visualized with ROCm profiling tools such as ROCm Systems Profiler or rocprofv3.

Without -DRAFT_NVTX=ON, all nvtx::range objects compile to no-ops with zero overhead.