nvtx3::named_category< D > Class Template Reference

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

#include <nvtx3.hpp>

Inheritance diagram for nvtx3::named_category< D >:

Collaboration diagram for nvtx3::named_category< D >:

Public Member Functions
	named_category (id_type id, char const *name) noexcept
	Construct a category with the specified id and name. More...
	named_category (id_type id, wchar_t const *name) noexcept
	Construct a category with the specified id and name. More...
Public Member Functions inherited from nvtx3::category
constexpr	category (id_type id) noexcept
	Construct a category with the specified id. More...
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 >
static named_category< D > const &	get () noexcept
	Returns a global instance of a named_category as a function-local static. More...

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

Detailed Description

template<typename D = domain::global>
class nvtx3::named_category< 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`
static nvtx3::named_category static_category{42, "my category"};

// Range `r` associated with category id `42`
nvtx3::thread_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 category::id_type id{42}; // category id
};

// Use construct on first use to name the category id `42`
// with name "my category"
auto my_category = named_category<my_domain>::get<my_category>();

// Range `r` associated with category id `42`
nvtx3::thread_range r{my_category};

named_category'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 belongs. Else, domain::global to indicate that the global NVTX domain should be used.

Constructor & Destructor Documentation

template<typename D = domain::global>

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

inlinenoexcept

Construct a category 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

template<typename D = domain::global>

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

inlinenoexcept

Construct a category 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

Member Function Documentation

template<typename D = domain::global>

template<typename C >

static named_category<D> const& nvtx3::named_category< D >::get ( )

inlinestaticnoexcept

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

Creates a named_category 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<my_domain>::get<my_category>();

// Range `r` associated with category id `42`
nvtx3::thread_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.

---

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

• nvtx3.hpp