NVTX C++ API Reference 1.0
C++ convenience wrappers for NVTX v3 C API
•All Classes Files Functions Variables Typedefs Macros Pages
Public Member Functions | Static Public Member Functions | List of all members
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.
 
 registered_string_in (std::string const &msg) noexcept
 Constructs a registered_string_in from the specified msg string.
 
 registered_string_in (wchar_t const *msg) noexcept
 Constructs a registered_string_in from the specified msg string.
 
 registered_string_in (std::wstring const &msg) noexcept
 Constructs a registered_string_in from the specified msg string.
 
nvtxStringHandle_t get_handle () const noexcept
 Returns the registered string's handle.
 
 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.
 
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*.
 
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.
 

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};
nvtx3::message
Allows associating a message string with an NVTX event via its EventAttributes.
Definition nvtx3.hpp:1651
nvtx3::v1::registered_string_in
A message registered with NVTX.
Definition nvtx3.hpp:1436
nvtx3::v1::registered_string_in::get
static registered_string_in const & get() noexcept
Returns a global instance of a registered_string_in as a function local static.
Definition nvtx3.hpp:1476
nvtx3::v1::scoped_range
scoped_range_in< domain::global > scoped_range
Alias for a scoped_range_in in the global NVTX domain.
Definition nvtx3.hpp:2174

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

Template Parameters
DType 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 1436 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
msgThe contents of the message

Definition at line 1538 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
msgThe contents of the message

Definition at line 1554 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
msgThe contents of the message

Definition at line 1568 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
msgThe contents of the message

Definition at line 1584 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
MType 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 1476 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 1491 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 1509 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 1591 of file nvtx3.hpp.

The documentation for this class was generated from the following file:
Generated by doxygen 1.9.8