Profiling Ranges (ROCTX)

Profiling Ranges (ROCTX)#

2026-03-13

3 min read time

Applies to Linux

#include <raft/core/nvtx.hpp>

namespace raft::common::nvtx

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.

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.