nvtx3::v1::domain Class Reference

domains allow for grouping NVTX events into a single scope to differentiate them from events in other domains. More...

#include <nvtx3.hpp>

Classes
struct	global
	Tag type for the "global" NVTX domain. More...

Public Member Functions
	domain (domain const &)=delete
domain &	operator= (domain const &)=delete
	domain (domain &&)=delete
domain &	operator= (domain &&)=delete
	operator nvtxDomainHandle_t () const noexcept
	Conversion operator to nvtxDomainHandle_t.

Static Public Member Functions
template<typename D = global, typename std::enable_if< detail::is_c_string< decltype(D::name)>::value, int >::type = 0>
static domain const &	get () noexcept
	Returns reference to an instance of a function local static domain object.
template<typename D = global, typename std::enable_if< !detail::is_c_string< decltype(D::name)>::value, int >::type = 0>
static domain const &	get () noexcept
	Overload of domain::get to provide a clear compile error when D has a name member that is not directly convertible to either char const* or wchar_t const*.
template<typename D = global, typename std::enable_if< !detail::has_name< D >::value, int >::type = 0>
static domain const &	get () noexcept
	Overload of domain::get to provide a clear compile error when D does not have a name member.

Detailed Description

domains allow for grouping NVTX events into a single scope to differentiate them from events in other domains.

By default, all NVTX constructs are placed in the "global" NVTX domain.

A custom domain may be used in order to differentiate a library's or application's NVTX events from other events.

domains are expected to be long-lived and unique to a library or application. As such, it is assumed a domain's name is known at compile time. Therefore, all NVTX constructs that can be associated with a domain require the domain to be specified via a type D passed as an explicit template parameter.

The type domain::global may be used to indicate that the global NVTX domain should be used.

None of the C++ NVTX constructs require the user to manually construct a domain object. Instead, if a custom domain is desired, the user is expected to define a type D that contains a member D::name which resolves to either a char const* or wchar_t const*. The value of D::name is used to name and uniquely identify the custom domain.

Upon the first use of an NVTX construct associated with the type D, the "construct on first use" pattern is used to construct a function local static domain object. All future NVTX constructs associated with D will use a reference to the previously constructed domain object. See domain::get.

Example:

// The type `my_domain` defines a `name` member used to name and identify
// the `domain` object identified by `my_domain`.
struct my_domain{ static constexpr char const* name{"my_domain"}; };
 
// The NVTX range `r` will be grouped with all other NVTX constructs
// associated with  `my_domain`.
nvtx3::scoped_range_in<my_domain> r{};
 
// An alias can be created for a `scoped_range_in` in the custom domain
using my_scoped_range = nvtx3::scoped_range_in<my_domain>;
my_scoped_range my_range{};
 
// `domain::global` indicates that the global NVTX domain is used
nvtx3::scoped_range_in<domain::global> r2{};
 
// For convenience, `nvtx3::scoped_range` is an alias for a range in the
// global domain
nvtx3::scoped_range r3{};

Definition at line 756 of file nvtx3.hpp.

Member Function Documentation

get() [1/3]

template<typename D = global, typename std::enable_if< detail::is_c_string< decltype(D::name)>::value, int >::type = 0>

static domain const & nvtx3::v1::domain::get ( )

inlinestaticnoexcept

Returns reference to an instance of a function local static domain object.

Uses the "construct on first use" idiom to safely ensure the domain object is initialized exactly once upon first invocation of domain::get<D>(). All following invocations will return a reference to the previously constructed domain object. See https://isocpp.org/wiki/faq/ctors#static-init-order-on-first-use

None of the constructs in this header require the user to directly invoke domain::get. It is automatically invoked when constructing objects like a scoped_range_in or category. Advanced users may wish to use domain::get for the convenience of the "construct on first use" idiom when using domains with their own use of the NVTX C API.

This function is thread-safe as of C++11. If two or more threads call domain::get<D> concurrently, exactly one of them is guaranteed to construct the domain object and the other(s) will receive a reference to the object after it is fully constructed.

The domain's name is specified via the type D pass as an explicit template parameter. D is required to contain a member D::name that resolves to either a char const* or wchar_t const*. The value of D::name is used to name and uniquely identify the domain.

Example:

// The type `my_domain` defines a `name` member used to name and identify
// the `domain` object identified by `my_domain`.
struct my_domain{ static constexpr char const* name{"my domain"}; };
 
auto& D1 = domain::get<my_domain>(); // First invocation constructs a
                                     // `domain` with the name "my domain"
 
auto& D2 = domain::get<my_domain>(); // Quickly returns reference to
                                     // previously constructed `domain`.

Template Parameters

D	Type that contains a D::name member used to name the domain object.

Returns

Reference to the domain corresponding to the type D.

Definition at line 826 of file nvtx3.hpp.

get() [2/3]

template<typename D = global, typename std::enable_if< !detail::is_c_string< decltype(D::name)>::value, int >::type = 0>

static domain const & nvtx3::v1::domain::get ( )

inlinestaticnoexcept

Overload of domain::get to provide a clear compile error when D has a name member that is not directly convertible to either char const* or wchar_t const*.

Definition at line 841 of file nvtx3.hpp.

get() [3/3]

template<typename D = global, typename std::enable_if< !detail::has_name< D >::value, int >::type = 0>

static domain const & nvtx3::v1::domain::get ( )

inlinestaticnoexcept

Overload of domain::get to provide a clear compile error when D does not have a name member.

Definition at line 859 of file nvtx3.hpp.

operator nvtxDomainHandle_t()

nvtx3::v1::domain::operator nvtxDomainHandle_t ( ) const

inlinenoexcept

Conversion operator to nvtxDomainHandle_t.

Allows transparently passing a domain object into an API expecting a native nvtxDomainHandle_t object.

Definition at line 882 of file nvtx3.hpp.

---

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

• nvtx3.hpp