nvtx3::v1::named_category_in< D > Class Template Reference

A category with an associated name string. More...

#include <nvtx3.hpp>

Inheritance diagram for nvtx3::v1::named_category_in< D >:

Collaboration diagram for nvtx3::v1::named_category_in< D >:

Public Member Functions
	named_category_in (id_type id, char const *name) noexcept
	Construct a named_category_in with the specified id and name.
	named_category_in (id_type id, wchar_t const *name) noexcept
	Construct a named_category_in with the specified id and name.
Public Member Functions inherited from nvtx3::v1::category
constexpr	category (id_type id) noexcept
	Construct a category with the specified id.
constexpr id_type	get_id () const noexcept
	Returns the id of the category.
	category (category const &)=default
category &	operator= (category const &)=default
	category (category &&)=default
category &	operator= (category &&)=default

Static Public Member Functions
template<typename C , typename std::enable_if< detail::is_c_string< decltype(C::name)>::value &&detail::is_uint32< decltype(C::id)>::value, int >::type = 0>
static named_category_in const &	get () noexcept
	Returns a global instance of a named_category_in as a function-local static.
template<typename C , typename std::enable_if< !detail::is_c_string< decltype(C::name)>::value||!detail::is_uint32< decltype(C::id)>::value, int >::type = 0>
static named_category_in const &	get () noexcept
	Overload of named_category_in::get to provide a clear compile error when C has the required name and id members, but they are not the required types. name must be directly convertible to char const* or wchar_t const*, and id must be uint32_t.
template<typename C , typename std::enable_if< !detail::has_name< C >::value||!detail::has_id< C >::value, int >::type = 0>
static named_category_in const &	get () noexcept
	Overload of named_category_in::get to provide a clear compile error when C does not have the required name and id members.

Additional Inherited Members
Public Types inherited from nvtx3::v1::category
using	id_type = uint32_t
	Type used for categorys integer id.

Detailed Description

template<typename D = domain::global>
class nvtx3::v1::named_category_in< D >

A category with an associated name string.

Associates a name string with a category id to help differentiate among categories.

For any given category id Id, a named_category(Id, "name") should only be constructed once and reused throughout an application. This can be done by either explicitly creating static named_category objects, or using the named_category::get construct on first use helper (recommended).

Creating two or more named_category objects with the same value for id in the same domain results in undefined behavior.

Similarly, behavior is undefined when a named_category and category share the same value of id.

Example:

// Explicitly constructed, static `named_category` in global domain:
static nvtx3::named_category static_category{42, "my category"};
 
// Range `r` associated with category id `42`
nvtx3::scoped_range r{static_category};
 
// OR use construct on first use:
 
// Define a type with `name` and `id` members
struct my_category {
   static constexpr char const* name{"my category"}; // category name
   static constexpr uint32_t id{42}; // category id
};
 
// Use construct on first use to name the category id `42`
// with name "my category"
auto& cat = named_category_in<my_domain>::get<my_category>();
 
// Range `r` associated with category id `42`
nvtx3::scoped_range r{cat};

named_category_in<D>'s association of a name to a category id is local to the domain specified by the type D. An id may have a different name in another domain.

Template Parameters

D	Type containing name member used to identify the domain to which the named_category_in belongs. Else, domain::global to indicate that the global NVTX domain should be used.

Definition at line 1236 of file nvtx3.hpp.

Constructor & Destructor Documentation

named_category_in() [1/2]

template<typename D = domain::global>

nvtx3::v1::named_category_in< D >::named_category_in ( id_type  id, char const *  name  )

inlinenoexcept

Construct a named_category_in with the specified id and name.

The name name will be registered with id.

Every unique value of id should only be named once.

Parameters

[in]	id	The category id to name
[in]	name	The name to associated with id

Definition at line 1352 of file nvtx3.hpp.

named_category_in() [2/2]

template<typename D = domain::global>

nvtx3::v1::named_category_in< D >::named_category_in ( id_type  id, wchar_t const *  name  )

inlinenoexcept

Construct a named_category_in with the specified id and name.

The name name will be registered with id.

Every unique value of id should only be named once.

Parameters

[in]	id	The category id to name
[in]	name	The name to associated with id

Definition at line 1372 of file nvtx3.hpp.

Member Function Documentation

get() [1/3]

template<typename D = domain::global>

template<typename C , typename std::enable_if< detail::is_c_string< decltype(C::name)>::value &&detail::is_uint32< decltype(C::id)>::value, int >::type = 0>

static named_category_in const & nvtx3::v1::named_category_in< D >::get ( )

inlinestaticnoexcept

Returns a global instance of a named_category_in as a function-local static.

Creates a named_category_in<D> with name and id specified by the contents of a type C. C::name determines the name and C::id determines the category id.

This function is useful for constructing a named category exactly once and reusing the same instance throughout an application.

Example:

// Define a type with `name` and `id` members
struct my_category {
   static constexpr char const* name{"my category"}; // category name
   static constexpr uint32_t id{42}; // category id
};
 
// Use construct on first use to name the category id `42`
// with name "my category"
auto& cat = named_category_in<my_domain>::get<my_category>();
 
// Range `r` associated with category id `42`
nvtx3::scoped_range r{cat};

Uses the "construct on first use" idiom to safely ensure the category object is initialized exactly once. See https://isocpp.org/wiki/faq/ctors#static-init-order-on-first-use

Template Parameters

C	Type containing a member C::name that resolves to either a char const* or wchar_t const* and C::id.

Definition at line 1278 of file nvtx3.hpp.

get() [2/3]

template<typename D = domain::global>

template<typename C , typename std::enable_if< !detail::is_c_string< decltype(C::name)>::value||!detail::is_uint32< decltype(C::id)>::value, int >::type = 0>

static named_category_in const & nvtx3::v1::named_category_in< D >::get ( )

inlinestaticnoexcept

Overload of named_category_in::get to provide a clear compile error when C has the required name and id members, but they are not the required types. name must be directly convertible to char const* or wchar_t const*, and id must be uint32_t.

Definition at line 1295 of file nvtx3.hpp.

get() [3/3]

template<typename D = domain::global>

template<typename C , typename std::enable_if< !detail::has_name< C >::value||!detail::has_id< C >::value, int >::type = 0>

static named_category_in const & nvtx3::v1::named_category_in< D >::get ( )

inlinestaticnoexcept

Overload of named_category_in::get to provide a clear compile error when C does not have the required name and id members.

Definition at line 1317 of file nvtx3.hpp.

---

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

• nvtx3.hpp