nvtx3::registered_message< D > Class Template Reference

A message registered with NVTX. More...

#include <nvtx3.hpp>

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

Static Public Member Functions
template<typename M >
static registered_message< D > const &	get () noexcept
	Returns a global instance of a registered_message as a function local static. More...

Detailed Description

template<typename D = domain::global>
class nvtx3::registered_message< 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_message objects, or using the registered_message::get construct on first use helper (recommended).

Example:

// Explicitly constructed, static `registered_message`
static registered_message<my_domain> static_message{"message"};

// "message" is associated with the range `r`
nvtx3::thread_range r{static_message};

// Or use construct on first use:

// Define a type with a `message` member that defines the contents of the
// registered message
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_message<my_domain>::get<my_message>();

// "my message" is associated with the range `r`
nvtx3::thread_range r{msg};

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

Constructor & Destructor Documentation

template<typename D = domain::global>

nvtx3::registered_message< D >::registered_message ( char const *  msg )

inlineexplicitnoexcept

Constructs a registered_message 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

template<typename D = domain::global>

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

inlineexplicitnoexcept

Constructs a registered_message 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

template<typename D = domain::global>

nvtx3::registered_message< D >::registered_message ( wchar_t const *  msg )

inlineexplicitnoexcept

Constructs a registered_message 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

template<typename D = domain::global>

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

inlineexplicitnoexcept

Constructs a registered_message 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

Member Function Documentation

template<typename D = domain::global>

template<typename M >

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

inlinestaticnoexcept

Returns a global instance of a registered_message 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_message 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 message
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_message<my_domain>::get<my_message>();

// "my message" is associated with the range `r`
nvtx3::thread_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 message's contents.

Returns

Reference to a registered_message associated with the type M.

---

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

• nvtx3.hpp