Provides C++ constructs making the NVTX library safer and easier to use with zero overhead. More...

Include dependency graph for nvtx3.hpp:

Classes
class	nvtx3::v1::mv2::domain
	`domain`s allow for grouping NVTX events into a single scope to differentiate them from events in other `domain`s. More...

struct	nvtx3::v1::mv2::domain::global
	Tag type for the "global" NVTX domain. More...

struct	nvtx3::v1::mv2::rgb
	Indicates the values of the red, green, and blue color channels for an RGB color to use as an event attribute (assumes no transparency). More...

struct	nvtx3::v1::mv2::argb
	Indicates the value of the alpha, red, green, and blue color channels for an ARGB color to use as an event attribute. More...

class	nvtx3::v1::mv2::color
	Represents a custom color that can be associated with an NVTX event via its `event_attributes`. More...

class	nvtx3::v1::mv2::category
	Object for intra-domain grouping of NVTX events. More...

class	nvtx3::v1::mv2::named_category_in< D >
	A `category` with an associated name string. More...

class	nvtx3::v1::mv2::registered_string_in< D >
	A message registered with NVTX. More...

class	nvtx3::v1::mv2::message
	Allows associating a message string with an NVTX event via its `EventAttribute`s. More...

class	nvtx3::v1::mv2::payload
	A numerical value that can be associated with an NVTX event via its `event_attributes`. More...

class	nvtx3::v1::mv2::schema
	Represents the registered schema for a payload struct. More...

class	nvtx3::v1::mv2::payload_data
	Wrapper around the NVTX C API `nvtxPayloadData_t` struct. More...

class	nvtx3::v1::mv2::event_attributes
	Describes the attributes of a NVTX event. More...

class	nvtx3::v1::mv2::scoped_range_in< D >
	A RAII object for creating a NVTX range local to a thread within a domain. More...

struct	nvtx3::v1::mv2::range_handle
	Handle used for correlating explicit range start and end events. More...

class	nvtx3::v1::mv2::unique_range_in< D >
	A RAII object for creating a NVTX range within a domain that can be created and destroyed on different threads. More...

class	nvtx3::v1::mv2::scope
	Type-safe wrapper for NVTX scope identifiers. More...

class	nvtx3::v1::mv2::counter_semantic
	Builder class for configuring counter semantics. More...

class	nvtx3::v1::mv2::scope_semantic
	Builder for the scope semantic applied to a payload entry. More...

class	nvtx3::v1::mv2::scope_in< D >
	A domain-scoped handle to a user-registered NVTX scope. More...

class	nvtx3::v1::mv2::time_semantic
	Builder for the time semantic applied to a payload entry. More...

class	nvtx3::v1::mv2::time_domain_in< D >
	A domain-scoped handle to a user-registered NVTX time domain. More...

class	nvtx3::v1::mv2::correlation_semantic
	Builder for the correlation semantic applied to a payload entry. More...

class	nvtx3::v1::mv2::counter_in< T, D >
	A type-safe NVTX counter in a specific domain. More...

Macros
#define	NVTX3_CPP_VERSION_MAJOR 1

#define	NVTX3_CPP_VERSION_MINOR 2

#define	NVTX3_INLINE_THIS_VERSION

#define	NVTX3_CPP_INLINED_VERSION_MAJOR 1
	Semantic major version number for NVTX C++ wrappers of unversioned symbols.

#define	NVTX3_CPP_INLINED_VERSION_MINOR 2
	Semantic minor version number for NVTX C++ wrappers of unversioned symbols.

#define	NVTX3_USE_CHECKED_OVERLOADS_FOR_GET 1

#define	NVTX3_USE_CHECKED_OVERLOADS_FOR_GET_DEFINED_HERE

#define	NVTX3_CONCAT(A, B) A##B

#define	NVTX3_NAMESPACE_FOR(VERSION) NVTX3_CONCAT(v, VERSION)

#define	NVTX3_VERSION_NAMESPACE NVTX3_NAMESPACE_FOR(NVTX3_CPP_VERSION_MAJOR)

#define	NVTX3_MINOR_NAMESPACE_FOR(VERSION) NVTX3_CONCAT(mv, VERSION)

#define	NVTX3_MINOR_VERSION_NAMESPACE NVTX3_MINOR_NAMESPACE_FOR(NVTX3_CPP_VERSION_MINOR)

#define	NVTX3_INLINE_IF_REQUESTED inline

#define	NVTX3_CONSTEXPR_IF_CPP14

#define	NVTX3_CONSTEXPR_IF_CPP20

#define	__has_cpp_attribute(x) 0

#define	NVTX3_MAYBE_UNUSED

#define	NVTX3_NO_DISCARD

#define	NVTX3_STATIC_ASSERT(condition, message) static_assert(condition, message)

#define	NVTX3_STATIC_ASSERT_DEFINED_HERE

#define	NVTX3_CPP_DEFINITIONS_V1_0

#define	NVTX3_V1_FUNC_RANGE_IN(D)
	Convenience macro for generating a range in the specified `domain` from the lifetime of a function.

#define	NVTX3_V1_FUNC_RANGE_IF_IN(D, C)
	Convenience macro for generating a range in the specified `domain` from the lifetime of a function if the given boolean expression evaluates to true.

#define	NVTX3_V1_FUNC_RANGE() NVTX3_V1_FUNC_RANGE_IN(::nvtx3::v1::domain::global)
	Convenience macro for generating a range in the global domain from the lifetime of a function.

#define	NVTX3_V1_FUNC_RANGE_IF(C) NVTX3_V1_FUNC_RANGE_IF_IN(::nvtx3::v1::domain::global, C)
	Convenience macro for generating a range in the global domain from the lifetime of a function if the given boolean expression evaluates to true.

#define	NVTX3_V1_NO_DISCARD

#define	NVTX3_V1_DEFINE_SCHEMA_GET(dom, struct_id, schema_name, entries)
	Convenience macro for generating a sspecialization of nvtx3::schema::get for an existing `struct`.

#define	NVTX3_V1_SEMANTIC(expr)
	Macro for inline semantic definitions in schema entries.

#define	NVTX3_FUNC_RANGE NVTX3_V1_FUNC_RANGE

#define	NVTX3_FUNC_RANGE_IF NVTX3_V1_FUNC_RANGE_IF

#define	NVTX3_FUNC_RANGE_IN NVTX3_V1_FUNC_RANGE_IN

#define	NVTX3_FUNC_RANGE_IF_IN NVTX3_V1_FUNC_RANGE_IF_IN

#define	NVTX3_DEFINE_SCHEMA_GET NVTX3_V1_DEFINE_SCHEMA_GET

#define	NVTX3_SEMANTIC NVTX3_V1_SEMANTIC

Typedefs
template<typename T >
using	nvtx3::v1::mv2::detail::is_uint32 = std::is_same< typename std::decay< T >::type, uint32_t >

using	nvtx3::v1::named_category = named_category_in< domain::global >
	Alias for a `named_category_in` in the global NVTX domain.

using	nvtx3::v1::registered_string = registered_string_in< domain::global >
	Alias for a `registered_string_in` in the global NVTX domain.

using	nvtx3::v1::scoped_range = scoped_range_in< domain::global >
	Alias for a `scoped_range_in` in the global NVTX domain.

using	nvtx3::v1::unique_range = unique_range_in< domain::global >
	Alias for a `unique_range_in` in the global NVTX domain.

template<typename T >
using	nvtx3::v1::counter = counter_in< T, domain::global >
	Alias for a counter in the global NVTX domain.

Enumerations
enum class	nvtx3::v1::no_value_reason : uint8_t { zero = 0 , unchanged = 1 , unavailable = 2 }
	Reasons for sampling a counter without a value. More...

Functions
template<>
domain const &	nvtx3::v1::domain::get< domain::global > () noexcept
	Returns reference to the `domain` object that represents the global NVTX domain.

template<typename D = domain::global>
int	nvtx3::v1::push_range_in (event_attributes const &attr) noexcept
	Manually begin a nested thread range in a domain.

template<typename D = domain::global, typename... Args>
int	nvtx3::v1::push_range_in (Args const &... args) noexcept
	Manually begin a nested thread range in a domain.

int	nvtx3::v1::push_range (event_attributes const &attr) noexcept
	Manually begin a nested thread range in the global domain.

template<typename... Args>
int	nvtx3::v1::push_range (Args const &... args) noexcept
	Manually begin a nested thread range in the global domain.

template<typename D = domain::global>
int	nvtx3::v1::pop_range_in () noexcept
	Manually end the current nested thread range in a domain.

int	nvtx3::v1::pop_range () noexcept
	Manually end the current nested thread range in the global domain.

constexpr bool	nvtx3::v1::operator== (range_handle lhs, range_handle rhs) noexcept
	Compares two range_handles for equality.

constexpr bool	nvtx3::v1::operator!= (range_handle lhs, range_handle rhs) noexcept
	Compares two range_handles for inequality.

template<typename D = domain::global>
range_handle	nvtx3::v1::start_range_in (event_attributes const &attr) noexcept
	Manually begin an NVTX range.

template<typename D = domain::global, typename... Args>
range_handle	nvtx3::v1::start_range_in (Args const &... args) noexcept
	Manually begin an NVTX range.

range_handle	nvtx3::v1::start_range (event_attributes const &attr) noexcept
	Manually begin an NVTX range in the global domain.

template<typename... Args>
range_handle	nvtx3::v1::start_range (Args const &... args) noexcept
	Manually begin an NVTX range in the global domain.

template<typename D = domain::global>
void	nvtx3::v1::end_range_in (range_handle r) noexcept
	Manually end the range associated with the handle `r` in domain `D`.

void	nvtx3::v1::end_range (range_handle r) noexcept
	Manually end the range associated with the handle `r` in the global domain.

template<typename D = domain::global>
void	nvtx3::v1::mark_in (event_attributes const &attr) noexcept
	Annotates an instantaneous point in time with a "marker", using the attributes specified by `attr`.

template<typename D = domain::global, typename... Args>
void	nvtx3::v1::mark_in (Args const &... args) noexcept
	Annotates an instantaneous point in time with a "marker", using the arguments to construct an `event_attributes`.

void	nvtx3::v1::mark (event_attributes const &attr) noexcept
	Annotates an instantaneous point in time with a "marker", using the attributes specified by `attr`, in the global domain.

template<typename... Args>
void	nvtx3::v1::mark (Args const &... args) noexcept
	Annotates an instantaneous point in time with a "marker", using the arguments to construct an `event_attributes`, in the global domain.

int64_t	nvtx3::v1::timestamp () noexcept
	Read a timestamp from the NVTX handler (wraps `nvtxTimestampGet`).

Detailed Description

Provides C++ constructs making the NVTX library safer and easier to use with zero overhead.

Definition in file nvtx3.hpp.

Macro Definition Documentation

◆ __has_cpp_attribute

#define __has_cpp_attribute ( x ) 0

Definition at line 751 of file nvtx3.hpp.

◆ NVTX3_CONCAT

#define NVTX3_CONCAT	(	A,
		B
	)	A##B

Definition at line 709 of file nvtx3.hpp.

◆ NVTX3_CONSTEXPR_IF_CPP14

#define NVTX3_CONSTEXPR_IF_CPP14

Definition at line 738 of file nvtx3.hpp.

◆ NVTX3_CONSTEXPR_IF_CPP20

#define NVTX3_CONSTEXPR_IF_CPP20

Definition at line 746 of file nvtx3.hpp.

◆ NVTX3_CPP_DEFINITIONS_V1_0

#define NVTX3_CPP_DEFINITIONS_V1_0

Definition at line 782 of file nvtx3.hpp.

◆ NVTX3_CPP_INLINED_VERSION_MAJOR

#define NVTX3_CPP_INLINED_VERSION_MAJOR 1

Semantic major version number for NVTX C++ wrappers of unversioned symbols.

Breaking changes may occur between major versions, and different major versions cannot provide unversioned symbols in the same translation unit (.cpp file).

Note: If NVTX3_CPP_REQUIRE_EXPLICIT_VERSION is defined, this macro is not defined.

Not to be confused with the version number of the NVTX core library.

Definition at line 110 of file nvtx3.hpp.

◆ NVTX3_CPP_INLINED_VERSION_MINOR

#define NVTX3_CPP_INLINED_VERSION_MINOR 2

Semantic minor version number for NVTX C++ wrappers of unversioned symbols.

No breaking changes occur between minor versions – minor version changes within a major version are purely additive.

Note: If NVTX3_CPP_REQUIRE_EXPLICIT_VERSION is defined, this macro is not defined.

Not to be confused with the version number of the NVTX core library.

Definition at line 122 of file nvtx3.hpp.

◆ NVTX3_CPP_VERSION_MAJOR

#define NVTX3_CPP_VERSION_MAJOR 1

Definition at line 32 of file nvtx3.hpp.

◆ NVTX3_CPP_VERSION_MINOR

#define NVTX3_CPP_VERSION_MINOR 2

Definition at line 33 of file nvtx3.hpp.

◆ NVTX3_DEFINE_SCHEMA_GET

#define NVTX3_DEFINE_SCHEMA_GET NVTX3_V1_DEFINE_SCHEMA_GET

Definition at line 4958 of file nvtx3.hpp.

◆ NVTX3_FUNC_RANGE

#define NVTX3_FUNC_RANGE NVTX3_V1_FUNC_RANGE

Definition at line 4954 of file nvtx3.hpp.

◆ NVTX3_FUNC_RANGE_IF

#define NVTX3_FUNC_RANGE_IF NVTX3_V1_FUNC_RANGE_IF

Definition at line 4955 of file nvtx3.hpp.

◆ NVTX3_FUNC_RANGE_IF_IN

#define NVTX3_FUNC_RANGE_IF_IN NVTX3_V1_FUNC_RANGE_IF_IN

Definition at line 4957 of file nvtx3.hpp.

◆ NVTX3_FUNC_RANGE_IN

#define NVTX3_FUNC_RANGE_IN NVTX3_V1_FUNC_RANGE_IN

Definition at line 4956 of file nvtx3.hpp.

◆ NVTX3_INLINE_IF_REQUESTED

#define NVTX3_INLINE_IF_REQUESTED inline

Definition at line 720 of file nvtx3.hpp.

◆ NVTX3_INLINE_THIS_VERSION

#define NVTX3_INLINE_THIS_VERSION

Definition at line 93 of file nvtx3.hpp.

◆ NVTX3_MAYBE_UNUSED

#define NVTX3_MAYBE_UNUSED

Definition at line 756 of file nvtx3.hpp.

◆ NVTX3_MINOR_NAMESPACE_FOR

#define NVTX3_MINOR_NAMESPACE_FOR ( VERSION ) NVTX3_CONCAT(mv, VERSION)

Definition at line 713 of file nvtx3.hpp.

◆ NVTX3_MINOR_VERSION_NAMESPACE

#define NVTX3_MINOR_VERSION_NAMESPACE NVTX3_MINOR_NAMESPACE_FOR(NVTX3_CPP_VERSION_MINOR)

Definition at line 714 of file nvtx3.hpp.

◆ NVTX3_NAMESPACE_FOR

#define NVTX3_NAMESPACE_FOR ( VERSION ) NVTX3_CONCAT(v, VERSION)

Definition at line 710 of file nvtx3.hpp.

◆ NVTX3_NO_DISCARD

#define NVTX3_NO_DISCARD

Definition at line 761 of file nvtx3.hpp.

◆ NVTX3_SEMANTIC

#define NVTX3_SEMANTIC NVTX3_V1_SEMANTIC

Definition at line 4959 of file nvtx3.hpp.

◆ NVTX3_STATIC_ASSERT

#define NVTX3_STATIC_ASSERT	(	condition,
		message
	)	static_assert(condition, message)

Definition at line 770 of file nvtx3.hpp.

◆ NVTX3_STATIC_ASSERT_DEFINED_HERE

#define NVTX3_STATIC_ASSERT_DEFINED_HERE

Definition at line 771 of file nvtx3.hpp.

◆ NVTX3_USE_CHECKED_OVERLOADS_FOR_GET

#define NVTX3_USE_CHECKED_OVERLOADS_FOR_GET 1

Definition at line 702 of file nvtx3.hpp.

◆ NVTX3_USE_CHECKED_OVERLOADS_FOR_GET_DEFINED_HERE

#define NVTX3_USE_CHECKED_OVERLOADS_FOR_GET_DEFINED_HERE

Definition at line 704 of file nvtx3.hpp.

◆ NVTX3_V1_DEFINE_SCHEMA_GET

#define NVTX3_V1_DEFINE_SCHEMA_GET	(	dom,
		struct_id,
		schema_name,
		entries
	)

Value:

    template <>                                                                                        \
    NVTX3_V1_NO_DISCARD inline nvtx3::v1::schema const& nvtx3::v1::schema::get<struct_id>() noexcept   \
    {                                                                                                  \
        static_assert(                                                                                 \
            std::is_standard_layout<struct_id>::value,                                                 \
            "structs used for NVTX3 payload schema must be standard layout");                          \
        static_assert(                                                                                 \
            std::is_trivially_copyable<struct_id>::value,                                              \
            "structs used for NVTX3 payload schema must be trivially copyable");                       \
        using nvtx_struct_id = struct_id; /* avoids issues with namespaced struct_id */                \
        _NVTX_DEFINE_SCHEMA_FOR_STRUCT(nvtx_struct_id, schema_name, static const, entries)              \
        static const schema s{                                                                         \
            nvtxPayloadSchemaRegister(nvtx3::v1::domain::get<dom>(), &nvtx_struct_id##Attr)};          \
        return s;                                                                                      \
    }

Convenience macro for generating a sspecialization of nvtx3::schema::get for an existing struct.

Use this macro after your struct to enable the struct to be used as a payload.

Note: This macro must not be used inside a namespace.

Example:

struct SensorData
{
    int32_t sensorId;
    uint8_t channelId;
};
 
NVTX3_DEFINE_SCHEMA_GET(
    my_domain,
    SensorData,
    "SensorEvent",
    NVTX_PAYLOAD_ENTRIES(
        (sensorId, TYPE_INT32, "SensorID"),
        (channelId, TYPE_UINT8, "ChannelID")
    )
)

Parameters

[in]	dom	The NVTX domain.
[in]	struct_id	The name of the struct.
[in]	schema_name	Name of the payload schema.
[in]	entries	Payload schema entries using NVTX_PAYLOAD_ENTRIES macro.

Note: On MSVC, this macro requires the conforming preprocessor: /Zc:preprocessor (VS 2019+) or /experimental:preprocessor (VS 2017 v15.5+). Not supported on older MSVC versions.

Definition at line 4898 of file nvtx3.hpp.

◆ NVTX3_V1_FUNC_RANGE

#define NVTX3_V1_FUNC_RANGE ( ) NVTX3_V1_FUNC_RANGE_IN(::nvtx3::v1::domain::global)

Convenience macro for generating a range in the global domain from the lifetime of a function.

This macro is useful for generating an NVTX range in the global domain from the entry point of a function to its exit. It is intended to be the first line of the function.

Constructs a static registered_string_in using the name of the immediately enclosing function returned by __func__ and constructs a nvtx3::scoped_range using the registered function name as the range's message.

Example:

void foo(...) {
   NVTX3_FUNC_RANGE(); // Range begins on entry to foo()
   // do stuff
   ...
} // Range ends on return from foo()

Definition at line 4841 of file nvtx3.hpp.

◆ NVTX3_V1_FUNC_RANGE_IF

#define NVTX3_V1_FUNC_RANGE_IF ( C ) NVTX3_V1_FUNC_RANGE_IF_IN(::nvtx3::v1::domain::global, C)

Convenience macro for generating a range in the global domain from the lifetime of a function if the given boolean expression evaluates to true.

Similar to NVTX3_V1_FUNC_RANGE(), the only difference being that NVTX3_V1_FUNC_RANGE_IF(C) only generates a range if the given boolean expression evaluates to true.

Parameters

[in] C Boolean expression used to determine if a range should be generated.

Definition at line 4854 of file nvtx3.hpp.

◆ NVTX3_V1_FUNC_RANGE_IF_IN

#define NVTX3_V1_FUNC_RANGE_IF_IN	(	D,
		C
	)

Value:

  ::nvtx3::v1::detail::optional_scoped_range_in<D> optional_nvtx3_range__;           \
  if (C) {                                                                           \
    static ::nvtx3::v1::registered_string_in<D> const nvtx3_func_name__{__func__};   \
    static ::nvtx3::v1::event_attributes const nvtx3_func_attr__{nvtx3_func_name__}; \
    optional_nvtx3_range__.begin(nvtx3_func_attr__);                                 \
  } (void)0

Convenience macro for generating a range in the specified domain from the lifetime of a function if the given boolean expression evaluates to true.

Similar to NVTX3_V1_FUNC_RANGE_IN(D), the only difference being that NVTX3_V1_FUNC_RANGE_IF_IN(D, C) only generates a range if the given boolean expression evaluates to true.

Parameters

[in]	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.
[in]	C	Boolean expression used to determine if a range should be generated.

Definition at line 4807 of file nvtx3.hpp.

◆ NVTX3_V1_FUNC_RANGE_IN

#define NVTX3_V1_FUNC_RANGE_IN ( D )

Value:

  static ::nvtx3::v1::registered_string_in<D> const nvtx3_func_name__{__func__};   \
  static ::nvtx3::v1::event_attributes const nvtx3_func_attr__{nvtx3_func_name__}; \
  ::nvtx3::v1::scoped_range_in<D> const nvtx3_range__{nvtx3_func_attr__}

Convenience macro for generating a range in the specified domain from the lifetime of a function.

This macro is useful for generating an NVTX range in domain from the entry point of a function to its exit. It is intended to be the first line of the function.

Constructs a static registered_string_in using the name of the immediately enclosing function returned by __func__ and constructs a nvtx3::scoped_range using the registered function name as the range's message.

Example:

struct my_domain{static constexpr char const* name{"my_domain"};};
 
void foo(...) {
   NVTX3_FUNC_RANGE_IN(my_domain); // Range begins on entry to foo()
   // do stuff
   ...
} // Range ends on return from foo()

Parameters

[in] 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 4786 of file nvtx3.hpp.

◆ NVTX3_V1_NO_DISCARD

#define NVTX3_V1_NO_DISCARD

Definition at line 4860 of file nvtx3.hpp.

◆ NVTX3_V1_SEMANTIC

#define NVTX3_V1_SEMANTIC ( expr )

Value:

    ([]() -> nvtxSemanticsHeader_t const* {                        \
        static auto const s_ = (expr);                             \
        return s_.get();                                           \
    }())

Macro for inline semantic definitions in schema entries.

Use this macro within NVTX_PAYLOAD_ENTRIES to attach per-field semantics or a chain thereof. The macro creates a static local to give the semantic object stable storage for the lifetime of the program, and returns the pointer to its header that the schema entry's semantics field expects.

The type of the semantic is deduced from the expression, so any builder in the nvtx3::v1 semantic family works. If the semantic is chained to another semantic, the chain is copied into the static semantic object.

Example:

NVTX3_DEFINE_SCHEMA_GET(
    my_domain,
    sensor_data,
    "SensorData",
    NVTX_PAYLOAD_ENTRIES(
        (temperature, TYPE_FLOAT, "Temperature", nullptr, 0, UNUSED,
            NVTX3_SEMANTIC(nvtx3::counter_semantic{}.unit("C").limits(-40.0, 85.0))),
        (pressure, TYPE_FLOAT, "Pressure", nullptr, 0, UNUSED,
            NVTX3_SEMANTIC(nvtx3::counter_semantic{}.unit("hPa")))))

Parameters

expr	Any semantic builder expression exposing a `get()` method returning an `nvtxSemanticsHeader_t` const*.

Definition at line 4944 of file nvtx3.hpp.

◆ NVTX3_VERSION_NAMESPACE

#define NVTX3_VERSION_NAMESPACE NVTX3_NAMESPACE_FOR(NVTX3_CPP_VERSION_MAJOR)

Definition at line 711 of file nvtx3.hpp.

Typedef Documentation

◆ counter

template<typename T >

using nvtx3::v1::mv2::counter = typedef counter_in<T, domain::global>

Alias for a counter in the global NVTX domain.

Example:

nvtx3::counter<int64_t> my_counter{"name"};

Definition at line 4751 of file nvtx3.hpp.

◆ is_uint32

template<typename T >

using nvtx3::v1::mv2::detail::is_uint32 = typedef std::is_same<typename std::decay<T>::type, uint32_t>

Definition at line 837 of file nvtx3.hpp.

◆ named_category

using nvtx3::v1::mv2::named_category = typedef named_category_in<domain::global>

Alias for a named_category_in in the global NVTX domain.

Definition at line 1706 of file nvtx3.hpp.

◆ registered_string

using nvtx3::v1::mv2::registered_string = typedef registered_string_in<domain::global>

Alias for a registered_string_in in the global NVTX domain.

Definition at line 1939 of file nvtx3.hpp.

◆ scoped_range

using nvtx3::v1::mv2::scoped_range = typedef scoped_range_in<domain::global>

Alias for a scoped_range_in in the global NVTX domain.

Definition at line 2726 of file nvtx3.hpp.

◆ unique_range

using nvtx3::v1::mv2::unique_range = typedef unique_range_in<domain::global>

Alias for a unique_range_in in the global NVTX domain.

Definition at line 3380 of file nvtx3.hpp.

Enumeration Type Documentation

◆ no_value_reason

enum class nvtx3::v1::mv2::no_value_reason : uint8_t

strong

Reasons for sampling a counter without a value.

Used with counter_in::sample_no_value() to indicate why a sample has no associated value.

Definition at line 3610 of file nvtx3.hpp.

Function Documentation

◆ domain::get< domain::global >()

template<>

domain const & nvtx3::v1::mv2::domain::get< domain::global > ( )

inlinenoexcept

Returns reference to the domain object that represents the global NVTX domain.

This specialization for domain::global returns a default constructed, domain object for use when the "global" domain is desired.

All NVTX events in the global domain across all libraries and applications will be grouped together.

Returns: Reference to the domain corresponding to the global NVTX domain.

Definition at line 1262 of file nvtx3.hpp.

◆ end_range()

void nvtx3::v1::mv2::end_range ( range_handle r )

inlinenoexcept

Manually end the range associated with the handle r in the global domain.

Explicitly ends the NVTX range indicated by the handle r returned from a prior call to start_range. The range may end on a different thread from where it began.

Parameters

r	Handle to a range started by a prior call to `start_range`.

Warning: The domain type specified as template parameter to this function must be the same that was specified on the associated start_range call.

Definition at line 3252 of file nvtx3.hpp.

◆ end_range_in()

template<typename D = domain::global>

void nvtx3::v1::mv2::end_range_in ( range_handle r )

inlinenoexcept

Manually end the range associated with the handle r in domain D.

Explicitly ends the NVTX range indicated by the handle r returned from a prior call to start_range_in<D>. The range may end on a different thread from where it began.

Template Parameters

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

Parameters

r	Handle to a range started by a prior call to `start_range_in`.

Warning: The domain type specified as template parameter to this function must be the same that was specified on the associated start_range_in call.

Definition at line 3230 of file nvtx3.hpp.

◆ mark() [1/2]

template<typename... Args>

void nvtx3::v1::mv2::mark ( Args const &... args )

inlinenoexcept

Annotates an instantaneous point in time with a "marker", using the arguments to construct an event_attributes, in the global domain.

Unlike a "range" which has a beginning and an end, a marker is a single event in an application, such as detecting a problem:

bool success = do_operation(...);
if (!success) {
   nvtx3::mark("operation failed!", nvtx3::rgb{255,0,0});
}

Note that nvtx3::mark is a function, not a class like scoped_range.

Forwards the arguments args... to construct an event_attributes object. The attributes are then associated with the marker. For more detail, see the event_attributes documentation.

Parameters

[in] args Variadic parameter pack of arguments to construct an event_attributes associated with this range.

Definition at line 3506 of file nvtx3.hpp.

◆ mark() [2/2]

void nvtx3::v1::mv2::mark ( event_attributes const & attr )

inlinenoexcept

Annotates an instantaneous point in time with a "marker", using the attributes specified by attr, in the global domain.

Unlike a "range" which has a beginning and an end, a marker is a single event in an application, such as detecting a problem:

bool success = do_operation(...);
if (!success) {
   nvtx3::event_attributes attr{"operation failed!", nvtx3::rgb{255,0,0}};
   nvtx3::mark(attr);
}

Note that nvtx3::mark is a function, not a class like scoped_range.

Parameters

[in] attr event_attributes that describes the desired attributes of the mark.

Definition at line 3472 of file nvtx3.hpp.

◆ mark_in() [1/2]

template<typename D = domain::global, typename... Args>

void nvtx3::v1::mv2::mark_in ( Args const &... args )

inlinenoexcept

Annotates an instantaneous point in time with a "marker", using the arguments to construct an event_attributes.

Unlike a "range" which has a beginning and an end, a marker is a single event in an application, such as detecting a problem:

bool success = do_operation(...);
if (!success) {
   nvtx3::mark_in<my_domain>("operation failed!", nvtx3::rgb{255,0,0});
}

Note that nvtx3::mark_in<D> is a function, not a class like scoped_range_in<D>.

Forwards the arguments args... to construct an event_attributes object. The attributes are then associated with the marker. For more detail, see the event_attributes documentation.

Template Parameters

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

Parameters

[in] args Variadic parameter pack of arguments to construct an event_attributes associated with this range.

Definition at line 3443 of file nvtx3.hpp.

◆ mark_in() [2/2]

template<typename D = domain::global>

void nvtx3::v1::mv2::mark_in ( event_attributes const & attr )

inlinenoexcept

Annotates an instantaneous point in time with a "marker", using the attributes specified by attr.

Unlike a "range" which has a beginning and an end, a marker is a single event in an application, such as detecting a problem:

bool success = do_operation(...);
if (!success) {
   nvtx3::event_attributes attr{"operation failed!", nvtx3::rgb{255,0,0}};
   nvtx3::mark_in<my_domain>(attr);
}

Note that nvtx3::mark_in<D> is a function, not a class like scoped_range_in<D>.

Template Parameters

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

Parameters

[in] attr event_attributes that describes the desired attributes of the mark.

Definition at line 3406 of file nvtx3.hpp.

◆ operator!=()

constexpr bool nvtx3::v1::mv2::operator!=	(	range_handle	lhs,
		range_handle	rhs
	)

inlineconstexprnoexcept

Compares two range_handles for inequality.

Parameters

lhs	The first range_handle to compare
rhs	The second range_handle to compare

Definition at line 3057 of file nvtx3.hpp.

◆ operator==()

constexpr bool nvtx3::v1::mv2::operator==	(	range_handle	lhs,
		range_handle	rhs
	)

inlineconstexprnoexcept

Compares two range_handles for equality.

Parameters

lhs	The first range_handle to compare
rhs	The second range_handle to compare

Definition at line 3046 of file nvtx3.hpp.

◆ pop_range()

int nvtx3::v1::mv2::pop_range ( )

inlinenoexcept

Manually end the current nested thread range in the global domain.

This function is equivalent to nvtx3::pop_range_in<>() and nvtx3::pop_range_in<nvtx3::domain::global>().

Prefer nvtx3::scoped_range when a range can be tied to a C++ object lifetime. Use this manual push/pop API for callback-driven code or other control flows where the range begin and end happen in separate C++ scopes.

Warning: Manual push/pop ranges are not RAII protected. The caller is responsible for ensuring each pushed range has exactly one matching pop, ranges are properly nested, and the matching pop is called on the same thread.

Returns: The level of the range being ended, or a negative value if an error occurs.

Definition at line 2923 of file nvtx3.hpp.

◆ pop_range_in()

template<typename D = domain::global>

int nvtx3::v1::mv2::pop_range_in ( )

inlinenoexcept

Manually end the current nested thread range in a domain.

Ends the innermost range previously started by push_range_in<D>() on the same thread.

Prefer nvtx3::scoped_range_in when a range can be tied to a C++ object lifetime. Use this manual push/pop API for callback-driven code or other control flows where the range begin and end happen in separate C++ scopes.

Warning: Manual push/pop ranges are not RAII protected. The caller is responsible for ensuring each pushed range has exactly one matching pop, ranges are properly nested, and the matching pop is called on the same thread.

Template Parameters

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

Returns: The level of the range being ended, or a negative value if an error occurs.

Definition at line 2896 of file nvtx3.hpp.

◆ push_range() [1/2]

template<typename... Args>

int nvtx3::v1::mv2::push_range ( Args const &... args )

inlinenoexcept

Manually begin a nested thread range in the global domain.

This function is equivalent to nvtx3::push_range_in<>() and nvtx3::push_range_in<nvtx3::domain::global>().

This overload uses args... to construct an event_attributes object to associate with the range. For more detail, see event_attributes.

Prefer nvtx3::scoped_range when a range can be tied to a C++ object lifetime. Use this manual push/pop API for callback-driven code or other control flows where the range begin and end happen in separate C++ scopes.

Warning: Manual push/pop ranges are not RAII protected. The caller is responsible for ensuring each pushed range has exactly one matching pop, ranges are properly nested, and the matching pop is called on the same thread.

Parameters

[in] args Variadic parameter pack of the arguments for an event_attributes.

Returns: The 0-based level of the range being started, or a negative value if an error occurs.

Definition at line 2864 of file nvtx3.hpp.

◆ push_range() [2/2]

int nvtx3::v1::mv2::push_range ( event_attributes const & attr )

inlinenoexcept

Manually begin a nested thread range in the global domain.

This function is equivalent to nvtx3::push_range_in<>() and nvtx3::push_range_in<nvtx3::domain::global>().

Prefer nvtx3::scoped_range when a range can be tied to a C++ object lifetime. Use this manual push/pop API for callback-driven code or other control flows where the range begin and end happen in separate C++ scopes.

Warning: Manual push/pop ranges are not RAII protected. The caller is responsible for ensuring each pushed range has exactly one matching pop, ranges are properly nested, and the matching pop is called on the same thread.

Parameters

[in] attr event_attributes that describes the desired attributes of the range.

Returns: The 0-based level of the range being started, or a negative value if an error occurs.

Definition at line 2831 of file nvtx3.hpp.

◆ push_range_in() [1/2]

template<typename D = domain::global, typename... Args>

int nvtx3::v1::mv2::push_range_in ( Args const &... args )

inlinenoexcept

Manually begin a nested thread range in a domain.

This overload uses args... to construct an event_attributes object to associate with the range. For more detail, see event_attributes.

Prefer nvtx3::scoped_range_in when a range can be tied to a C++ object lifetime. Use this manual push/pop API for callback-driven code or other control flows where the range begin and end happen in separate C++ scopes.

Warning: Manual push/pop ranges are not RAII protected. The caller is responsible for ensuring each pushed range has exactly one matching pop, ranges are properly nested, and the matching pop is called on the same thread.

Example:

nvtx3::push_range_in<my_domain>("msg", nvtx3::rgb{127,255,0});
...
nvtx3::pop_range_in<my_domain>();

Template Parameters

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

Parameters

[in] args Variadic parameter pack of the arguments for an event_attributes.

Returns: The 0-based level of the range being started, or a negative value if an error occurs.

Definition at line 2801 of file nvtx3.hpp.

◆ push_range_in() [2/2]

template<typename D = domain::global>

int nvtx3::v1::mv2::push_range_in ( event_attributes const & attr )

inlinenoexcept

Manually begin a nested thread range in a domain.

This function begins a nested range on the calling thread in the specified domain. End the range with a matching call to pop_range_in<D>() on the same thread.

Prefer nvtx3::scoped_range_in when a range can be tied to a C++ object lifetime. Use this manual push/pop API for callback-driven code or other control flows where the range begin and end happen in separate C++ scopes.

Warning: Manual push/pop ranges are not RAII protected. The caller is responsible for ensuring each pushed range has exactly one matching pop, ranges are properly nested, and the matching pop is called on the same thread.

Example:

nvtx3::event_attributes attr{"msg", nvtx3::rgb{127,255,0}};
nvtx3::push_range_in<my_domain>(attr);
...
nvtx3::pop_range_in<my_domain>();

Template Parameters

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

Parameters

[in] attr event_attributes that describes the desired attributes of the range.

Returns: The 0-based level of the range being started, or a negative value if an error occurs.

Definition at line 2761 of file nvtx3.hpp.

◆ start_range() [1/2]

template<typename... Args>

range_handle nvtx3::v1::mv2::start_range ( Args const &... args )

inlinenoexcept

Manually begin an NVTX range in the global domain.

Explicitly begins an NVTX range and returns a unique handle. To end the range, pass the handle to end_range_in<D>().

nvtx3::start_range(...) is equivalent to nvtx3::start_range_in<>(...) and nvtx3::start_range_in<nvtx3::domain::global>(...).

start_range_in/end_range_in are the most explicit and lowest level APIs provided for creating ranges. Use of nvtx3::unique_range_in should be preferred unless one is unable to tie the range to the lifetime of an object.

This overload uses args... to construct an event_attributes to associate with the range. For more detail, see event_attributes.

Example:

// Manually begin a range
nvtx3::range_handle h = nvtx3::start_range("msg", nvtx3::rgb{127,255,0});
...
nvtx3::end_range(h); // Ends the range

Parameters

[in] args Variadic parameter pack of the arguments for an event_attributes.

Returns: Unique handle to be passed to end_range to end the range.

Definition at line 3204 of file nvtx3.hpp.

◆ start_range() [2/2]

range_handle nvtx3::v1::mv2::start_range ( event_attributes const & attr )

inlinenoexcept

Manually begin an NVTX range in the global domain.

Explicitly begins an NVTX range and returns a unique handle. To end the range, pass the handle to end_range().

nvtx3::start_range(...) is equivalent to nvtx3::start_range_in<>(...) and nvtx3::start_range_in<nvtx3::domain::global>(...).

start_range/end_range are the most explicit and lowest level APIs provided for creating ranges. Use of nvtx3::unique_range should be preferred unless one is unable to tie the range to the lifetime of an object.

Example:

nvtx3::event_attributes attr{"msg", nvtx3::rgb{127,255,0}};
// Manually begin a range
nvtx3::range_handle h = nvtx3::start_range(attr);
...
nvtx3::end_range(h); // End the range

Parameters

[in] attr event_attributes that describes the desired attributes of the range.

Returns: Unique handle to be passed to end_range_in to end the range.

Definition at line 3166 of file nvtx3.hpp.

◆ start_range_in() [1/2]

template<typename D = domain::global, typename... Args>

range_handle nvtx3::v1::mv2::start_range_in ( Args const &... args )

inlinenoexcept

Manually begin an NVTX range.

Explicitly begins an NVTX range and returns a unique handle. To end the range, pass the handle to end_range_in<D>().

nvtx3::start_range(...) is equivalent to nvtx3::start_range_in<>(...) and nvtx3::start_range_in<nvtx3::domain::global>(...).

start_range_in/end_range_in are the most explicit and lowest level APIs provided for creating ranges. Use of nvtx3::unique_range_in should be preferred unless one is unable to tie the range to the lifetime of an object.

This overload uses args... to construct an event_attributes to associate with the range. For more detail, see event_attributes.

Example:

// Manually begin a range
nvtx3::range_handle h = nvtx3::start_range_in<D>("msg", nvtx3::rgb{127,255,0});
...
nvtx3::end_range_in<D>(h); // Ends the range

Template Parameters

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

Parameters

[in] args Variadic parameter pack of the arguments for an event_attributes.

Returns: Unique handle to be passed to end_range to end the range.

Definition at line 3130 of file nvtx3.hpp.

◆ start_range_in() [2/2]

template<typename D = domain::global>

range_handle nvtx3::v1::mv2::start_range_in ( event_attributes const & attr )

inlinenoexcept

Manually begin an NVTX range.

Explicitly begins an NVTX range and returns a unique handle. To end the range, pass the handle to end_range_in<D>().

nvtx3::start_range(...) is equivalent to nvtx3::start_range_in<>(...) and nvtx3::start_range_in<nvtx3::domain::global>(...).

start_range_in/end_range_in are the most explicit and lowest level APIs provided for creating ranges. Use of nvtx3::unique_range_in should be preferred unless one is unable to tie the range to the lifetime of an object.

Example:

nvtx3::event_attributes attr{"msg", nvtx3::rgb{127,255,0}};
// Manually begin a range
nvtx3::range_handle h = nvtx3::start_range_in<my_domain>(attr);
...
nvtx3::end_range_in<my_domain>(h); // End the range

Template Parameters

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

Parameters

[in] attr event_attributes that describes the desired attributes of the range.

Returns: Unique handle to be passed to end_range_in to end the range.

Definition at line 3089 of file nvtx3.hpp.

◆ timestamp()

int64_t nvtx3::v1::mv2::timestamp ( )

inlinenoexcept

Read a timestamp from the NVTX handler (wraps nvtxTimestampGet).

If no tool is attached, the returned value is tool-defined (often a CPU TSC read). The timestamp is only meaningful alongside a registered timer source or time domain that tells the tool how to interpret it.

Returns: The current NVTX timestamp.

Definition at line 4129 of file nvtx3.hpp.

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ __has_cpp_attribute

◆ NVTX3_CONCAT

◆ NVTX3_CONSTEXPR_IF_CPP14

◆ NVTX3_CONSTEXPR_IF_CPP20

◆ NVTX3_CPP_DEFINITIONS_V1_0

◆ NVTX3_CPP_INLINED_VERSION_MAJOR

◆ NVTX3_CPP_INLINED_VERSION_MINOR

◆ NVTX3_CPP_VERSION_MAJOR

◆ NVTX3_CPP_VERSION_MINOR

◆ NVTX3_DEFINE_SCHEMA_GET

◆ NVTX3_FUNC_RANGE

◆ NVTX3_FUNC_RANGE_IF

◆ NVTX3_FUNC_RANGE_IF_IN

◆ NVTX3_FUNC_RANGE_IN

◆ NVTX3_INLINE_IF_REQUESTED

◆ NVTX3_INLINE_THIS_VERSION

◆ NVTX3_MAYBE_UNUSED

◆ NVTX3_MINOR_NAMESPACE_FOR

◆ NVTX3_MINOR_VERSION_NAMESPACE

◆ NVTX3_NAMESPACE_FOR

◆ NVTX3_NO_DISCARD

◆ NVTX3_SEMANTIC

◆ NVTX3_STATIC_ASSERT

◆ NVTX3_STATIC_ASSERT_DEFINED_HERE

◆ NVTX3_USE_CHECKED_OVERLOADS_FOR_GET

◆ NVTX3_USE_CHECKED_OVERLOADS_FOR_GET_DEFINED_HERE

◆ NVTX3_V1_DEFINE_SCHEMA_GET

◆ NVTX3_V1_FUNC_RANGE

◆ NVTX3_V1_FUNC_RANGE_IF

◆ NVTX3_V1_FUNC_RANGE_IF_IN

◆ NVTX3_V1_FUNC_RANGE_IN

◆ NVTX3_V1_NO_DISCARD

◆ NVTX3_V1_SEMANTIC

◆ NVTX3_VERSION_NAMESPACE

Typedef Documentation

◆ counter

◆ is_uint32

◆ named_category

◆ registered_string

◆ scoped_range

◆ unique_range

Enumeration Type Documentation

◆ no_value_reason

Function Documentation

◆ domain::get< domain::global >()

◆ end_range()

◆ end_range_in()

◆ mark() [1/2]

◆ mark() [2/2]

◆ mark_in() [1/2]

◆ mark_in() [2/2]

◆ operator!=()

◆ operator==()

◆ pop_range()

◆ pop_range_in()

◆ push_range() [1/2]

◆ push_range() [2/2]

◆ push_range_in() [1/2]

◆ push_range_in() [2/2]

◆ start_range() [1/2]

◆ start_range() [2/2]

◆ start_range_in() [1/2]

◆ start_range_in() [2/2]

◆ timestamp()