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

A message registered with NVTX. More...

#include <nvtx3.hpp>

Public Member Functions
	registered_string_in (char const *msg) noexcept
	Constructs a registered_string_in from the specified msg string. More...
	registered_string_in (std::string const &msg) noexcept
	Constructs a registered_string_in from the specified msg string. More...
	registered_string_in (wchar_t const *msg) noexcept
	Constructs a registered_string_in from the specified msg string. More...
	registered_string_in (std::wstring const &msg) noexcept
	Constructs a registered_string_in from the specified msg string. More...
nvtxStringHandle_t	get_handle () const noexcept
	Returns the registered string's handle. More...
	registered_string_in (registered_string_in const &)=default
registered_string_in &	operator= (registered_string_in const &)=default
	registered_string_in (registered_string_in &&)=default
registered_string_in &	operator= (registered_string_in &&)=default

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

Detailed Description

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

A message registered with NVTX.

Normally, associating a message with an NVTX event requires copying the contents of the message string. This may cause non-trivial overhead in highly performance sensitive regions of code.

message registration is an optimization to lower the overhead of associating a message with an NVTX event. Registering a message yields a handle that is inexpensive to copy that may be used in place of a message string.

A particular message should only be registered once and the handle reused throughout the rest of the application. This can be done by either explicitly creating static registered_string_in objects, or using the registered_string_in::get construct on first use helper (recommended).

Example:

// Explicitly constructed, static `registered_string` in my_domain:
static registered_string_in<my_domain> static_message{"message"};
 
// "message" is associated with the range `r`
nvtx3::scoped_range r{static_message};
 
// Or use construct on first use:
 
// Define a type with a `message` member that defines the contents of the
// registered string
struct my_message{ static constexpr char const* message{ "my message" }; };
 
// Uses construct on first use to register the contents of
// `my_message::message`
auto& msg = registered_string_in<my_domain>::get<my_message>();
 
// "my message" is associated with the range `r`
nvtx3::scoped_range r{msg};

registered_string_ins are local to a particular domain specified via the type D.

Template Parameters

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

Definition at line 1408 of file nvtx3.hpp.

Constructor & Destructor Documentation

registered_string_in() [1/4]

template<typename D = domain::global>

nvtx3::v1::registered_string_in< D >::registered_string_in ( char const *  msg )

inlineexplicitnoexcept

Constructs a registered_string_in from the specified msg string.

Registers msg with NVTX and associates a handle with the registered message.

A particular message should should only be registered once and the handle reused throughout the rest of the application.

Parameters

msg	The contents of the message

Definition at line 1510 of file nvtx3.hpp.

registered_string_in() [2/4]

template<typename D = domain::global>

nvtx3::v1::registered_string_in< D >::registered_string_in ( std::string const &  msg )

inlineexplicitnoexcept

Constructs a registered_string_in from the specified msg string.

Registers msg with NVTX and associates a handle with the registered message.

A particular message should should only be registered once and the handle reused throughout the rest of the application.

Parameters

msg	The contents of the message

Definition at line 1526 of file nvtx3.hpp.

registered_string_in() [3/4]

template<typename D = domain::global>

nvtx3::v1::registered_string_in< D >::registered_string_in ( wchar_t const *  msg )

inlineexplicitnoexcept

Constructs a registered_string_in from the specified msg string.

Registers msg with NVTX and associates a handle with the registered message.

A particular message should should only be registered once and the handle reused throughout the rest of the application.

Parameters

msg	The contents of the message

Definition at line 1540 of file nvtx3.hpp.

registered_string_in() [4/4]

template<typename D = domain::global>

nvtx3::v1::registered_string_in< D >::registered_string_in ( std::wstring const &  msg )

inlineexplicitnoexcept

Constructs a registered_string_in from the specified msg string.

Registers msg with NVTX and associates a handle with the registered message.

A particular message should only be registered once and the handle reused throughout the rest of the application.

Parameters

msg	The contents of the message

Definition at line 1556 of file nvtx3.hpp.

Member Function Documentation

get() [1/3]

template<typename D = domain::global>

template<typename M , typename std::enable_if< detail::is_c_string< decltype(M::message)>::value, int >::type = 0>

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

inlinestaticnoexcept

Returns a global instance of a registered_string_in as a function local static.

Provides a convenient way to register a message with NVTX without having to explicitly register the message.

Upon first invocation, constructs a registered_string_in whose contents are specified by message::message.

All future invocations will return a reference to the object constructed in the first invocation.

Example:

// Define a type with a `message` member that defines the contents of the
// registered string
struct my_message{ static constexpr char const* message{ "my message" };
};
 
// Uses construct on first use to register the contents of
// `my_message::message`
auto& msg = registered_string_in<my_domain>::get<my_message>();
 
// "my message" is associated with the range `r`
nvtx3::scoped_range r{msg};

Template Parameters

M	Type required to contain a member M::message that resolves to either a char const* or wchar_t const* used as the registered string's contents.

Returns

Reference to a registered_string_in associated with the type M.

Definition at line 1448 of file nvtx3.hpp.

get() [2/3]

template<typename D = domain::global>

template<typename M , typename std::enable_if< !detail::is_c_string< decltype(M::message)>::value, int >::type = 0>

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

inlinestaticnoexcept

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

Definition at line 1463 of file nvtx3.hpp.

get() [3/3]

template<typename D = domain::global>

template<typename M , typename std::enable_if< !detail::has_message< M >::value, int >::type = 0>

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

inlinestaticnoexcept

Overload of registered_string_in::get to provide a clear compile error when M does not have a message member.

Definition at line 1481 of file nvtx3.hpp.

get_handle()

template<typename D = domain::global>

nvtxStringHandle_t nvtx3::v1::registered_string_in< D >::get_handle ( ) const

inlinenoexcept

Returns the registered string's handle.

Definition at line 1563 of file nvtx3.hpp.

---

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

• nvtx3.hpp