nvtx3::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. More...

Static Public Member Functions
template<typename DomainName >
static domain const &	get ()
	Returns reference to an instance of a function local static domain object. More...

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 DomainName 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 DomainName that contains a member DomainName::name which resolves to either a char const* or wchar_t const*. The value of DomainName::name is used to name and uniquely identify the custom domain.

Upon the first use of an NVTX construct associated with the type DomainName, the "construct on first use" pattern is used to construct a function local static domain object. All future NVTX constructs associated with DomainType 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::domain_thread_range<my_domain> r{};

// An alias can be created for a `domain_thread_range` in the custom domain
using my_thread_range = nvtx3::domain_thread_range<my_domain>;
my_thread_range my_range{};

// `domain::global` indicates that the global NVTX domain is used
nvtx3::domain_thread_range<domain::global> r2{};

// For convenience, `nvtx3::thread_range` is an alias for a range in the
// global domain
nvtx3::thread_range r3{};

Member Function Documentation

template<typename DomainName >

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

inlinestatic

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<DomainName>(). 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 domain_thread_range 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 threadsafe as of C++11. If two or more threads call domain::get<DomainName> 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 DomainName pass as an explicit template parameter. DomainName is required to contain a member DomainName::name that resolves to either a char const* or wchar_t const*. The value of DomainName::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 D = domain::get<my_domain>(); // First invocation constructs a
                                   // `domain` with the name "my domain"

auto D1 = domain::get<my_domain>(); // Simply returns reference to
                                    // previously constructed `domain`.

Template Parameters

DomainName

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

Returns

Reference to the domain corresponding to the type DomainName.

nvtx3::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.

---

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

• nvtx3.hpp