NVTX C++ API Reference 1.0
C++ convenience wrappers for NVTX v3 C API
Loading...
Searching...
No Matches
nvtx3.hpp
Go to the documentation of this file.
1/*
2 * SPDX-FileCopyrightText: Copyright (c) 2020-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
3 * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 *
17 * Licensed under the Apache License v2.0 with LLVM Exceptions.
18 * See https://nvidia.github.io/NVTX/LICENSE.txt for license information.
19 */
20
21#if defined(NVTX_AS_SYSTEM_HEADER)
22#if defined(__clang__)
23#pragma clang system_header
24#elif defined(__GNUC__) || defined(__NVCOMPILER)
25#pragma GCC system_header
26#elif defined(_MSC_VER)
27#pragma system_header
28#endif
29#endif
30
31/* Temporary helper #defines, #undef'ed at end of header */
32#define NVTX3_CPP_VERSION_MAJOR 1
33#define NVTX3_CPP_VERSION_MINOR 1
34
35/* This section handles the decision of whether to provide unversioned symbols.
36 * If NVTX3_CPP_REQUIRE_EXPLICIT_VERSION is #defined, unversioned symbols are
37 * not provided, and explicit-version symbols such as nvtx3::v1::scoped_range
38 * and NVTX3_V1_FUNC_RANGE must be used. By default, the first #include of this
39 * header will define the unversioned symbols such as nvtx3::scoped_range and
40 * NVTX3_FUNC_RANGE. Subsequently including a different major version of this
41 * header without #defining NVTX3_CPP_REQUIRE_EXPLICIT_VERSION triggers an error
42 * since the symbols would conflict. Subsequently including of a different
43 * minor version within the same major version is allowed. Functionality of
44 * minor versions is cumulative, regardless of include order.
45 *
46 * Since NVTX3_CPP_REQUIRE_EXPLICIT_VERSION allows all combinations of versions
47 * to coexist without problems within a translation unit, the recommended best
48 * practice for instrumenting header-based libraries with NVTX C++ Wrappers is
49 * is to #define NVTX3_CPP_REQUIRE_EXPLICIT_VERSION before including nvtx3.hpp,
50 * #undef it afterward, and only use explicit-version symbols. This is not
51 * necessary in common cases, such as instrumenting a standalone application, or
52 * static/shared libraries in .cpp files or headers private to those projects.
53 */
54/* clang-format off */
55#if !defined(NVTX3_CPP_REQUIRE_EXPLICIT_VERSION)
56 /* Define macro used by all definitions in this header to indicate the
57 * unversioned symbols should be defined in addition to the versioned ones.
58 */
59 #define NVTX3_INLINE_THIS_VERSION
60
61 #if !defined(NVTX3_CPP_INLINED_VERSION_MAJOR)
62 /* First occurrence of this header in the translation unit. Define macros
63 * indicating which version shall be used for unversioned symbols.
64 */
65
76 #define NVTX3_CPP_INLINED_VERSION_MAJOR 1 // NVTX3_CPP_VERSION_MAJOR
77
88 #define NVTX3_CPP_INLINED_VERSION_MINOR 1 // NVTX3_CPP_VERSION_MINOR
89 #elif NVTX3_CPP_INLINED_VERSION_MAJOR != NVTX3_CPP_VERSION_MAJOR
90 /* Unsupported case -- cannot define unversioned symbols for different major versions
91 * in the same translation unit.
92 */
93 #error \
94 "Two different major versions of the NVTX C++ Wrappers are being included in a single .cpp file, with unversioned symbols enabled in both. Only one major version can enable unversioned symbols in a .cpp file. To disable unversioned symbols, #define NVTX3_CPP_REQUIRE_EXPLICIT_VERSION before #including nvtx3.hpp, and use the explicit-version symbols instead -- this is the preferred way to use nvtx3.hpp from a header file."
95 #elif (NVTX3_CPP_INLINED_VERSION_MAJOR == NVTX3_CPP_VERSION_MAJOR) && \
96 (NVTX3_CPP_INLINED_VERSION_MINOR < NVTX3_CPP_VERSION_MINOR)
97 /* An older minor version of the same major version already defined unversioned
98 * symbols. The new features provided in this header will be inlined
99 * redefine the minor version macro to this header's version.
100 */
101 #undef NVTX3_CPP_INLINED_VERSION_MINOR
102 #define NVTX3_CPP_INLINED_VERSION_MINOR 1 // NVTX3_CPP_VERSION_MINOR
103 // else, already have this version or newer, nothing to do
104 #endif
105#endif
106/* clang-format on */
107
618/* Temporary helper #defines, removed with #undef at end of header */
619
620/* Some compilers do not correctly support SFINAE, which is used in this API
621 * to detect common usage errors and provide clearer error messages (by using
622 * static_assert) than the compiler would produce otherwise. These compilers
623 * will generate errors while compiling this file such as:
624 *
625 * error: 'name' is not a member of 'nvtx3::v1::domain::global'
626 *
627 * The following compiler versions are known to have this problem, and so are
628 * set by default to disable the SFINAE-based checks:
629 *
630 * - All MSVC versions prior to VS2017 Update 7 (15.7)
631 * - GCC 8.1-8.3 (the problem was fixed in GCC 8.4)
632 *
633 * If you find your compiler hits this problem, you can work around it by
634 * defining NVTX3_USE_CHECKED_OVERLOADS_FOR_GET to 0 before including this
635 * header, or you can add a check for your compiler version to this #if.
636 * Also, please report the issue on the NVTX GitHub page.
637 */
638#if !defined(NVTX3_USE_CHECKED_OVERLOADS_FOR_GET)
639#if defined(_MSC_VER) && _MSC_VER < 1914 \
640 || defined(__GNUC__) && __GNUC__ == 8 && __GNUC_MINOR__ < 4
641#define NVTX3_USE_CHECKED_OVERLOADS_FOR_GET 0
642#else
643#define NVTX3_USE_CHECKED_OVERLOADS_FOR_GET 1
644#endif
645#define NVTX3_USE_CHECKED_OVERLOADS_FOR_GET_DEFINED_HERE
646#endif
647
648/* Within this header, nvtx3::NVTX3_VERSION_NAMESPACE resolves to nvtx3::vX,
649 * where "X" is the major version number. */
650#define NVTX3_CONCAT(A, B) A##B
651#define NVTX3_NAMESPACE_FOR(VERSION) NVTX3_CONCAT(v, VERSION)
652#define NVTX3_VERSION_NAMESPACE NVTX3_NAMESPACE_FOR(NVTX3_CPP_VERSION_MAJOR)
653/* We use a different prefix to avoid ambiguity with the version namespace */
654#define NVTX3_MINOR_NAMESPACE_FOR(VERSION) NVTX3_CONCAT(mv, VERSION)
655#define NVTX3_MINOR_VERSION_NAMESPACE NVTX3_MINOR_NAMESPACE_FOR(NVTX3_CPP_VERSION_MINOR)
656
657/* Avoid duplicating #if defined(NVTX3_INLINE_THIS_VERSION) for namespaces
658 * in each minor version by making a macro to use unconditionally, which
659 * resolves to "inline" or nothing as appropriate. */
660#if defined(NVTX3_INLINE_THIS_VERSION)
661#define NVTX3_INLINE_IF_REQUESTED inline
662#else
663#define NVTX3_INLINE_IF_REQUESTED
664#endif
665
666/* Enables the use of constexpr when support for C++14 constexpr is present.
667 *
668 * Initialization of a class member that is a union to a specific union member
669 * can only be done in the body of a constructor, not in a member initializer
670 * list. A constexpr constructor must have an empty body until C++14, so there
671 * is no way to make an initializer of a member union constexpr in C++11. This
672 * macro allows making functions constexpr in C++14 or newer, but non-constexpr
673 * in C++11 compilation. It is used here on constructors that initialize their
674 * member unions.
675 */
676#if __cpp_constexpr >= 201304L
677#define NVTX3_CONSTEXPR_IF_CPP14 constexpr
678#else
679#define NVTX3_CONSTEXPR_IF_CPP14
680#endif
681
682/* Enables the use of constexpr when support for C++20 constexpr is present.
683 */
684#if __cplusplus >= 202002L
685#define NVTX3_CONSTEXPR_IF_CPP20 constexpr
686#else
687#define NVTX3_CONSTEXPR_IF_CPP20
688#endif
689
690// Macro wrappers for C++ attributes
691#if !defined(__has_cpp_attribute)
692#define __has_cpp_attribute(x) 0
693#endif
694#if __has_cpp_attribute(maybe_unused)
695#define NVTX3_MAYBE_UNUSED [[maybe_unused]]
696#else
697#define NVTX3_MAYBE_UNUSED
698#endif
699#if __has_cpp_attribute(nodiscard)
700#define NVTX3_NO_DISCARD [[nodiscard]]
701#else
702#define NVTX3_NO_DISCARD
703#endif
704
705 /* Use a macro for static asserts, which defaults to static_assert, but that
706 * testing tools can replace with a logging function. For example:
707 * #define NVTX3_STATIC_ASSERT(c, m) \
708 * do { if (!(c)) printf("static_assert would fail: %s\n", m); } while (0)
709 */
710#if !defined(NVTX3_STATIC_ASSERT)
711#define NVTX3_STATIC_ASSERT(condition, message) static_assert(condition, message)
712#define NVTX3_STATIC_ASSERT_DEFINED_HERE
713#endif
714
715/* Implementation sections, enclosed in guard macros for each minor version */
716
717#ifndef NVTX3_CPP_DEFINITIONS_V1_0
718#define NVTX3_CPP_DEFINITIONS_V1_0
719
720#include "nvToolsExt.h"
721#include "nvToolsExtPayload.h"
722#include "nvToolsExtPayloadHelper.h"
723
724#include <memory>
725#include <string>
726#include <type_traits>
727#include <utility>
728#include <cstddef>
729#include <cstdint>
730
731namespace nvtx3 {
732
733NVTX3_INLINE_IF_REQUESTED namespace NVTX3_VERSION_NAMESPACE
734{
735inline namespace NVTX3_MINOR_VERSION_NAMESPACE
736{
737
738namespace detail {
739
740template <typename Unused>
741struct always_false : std::false_type {};
742
743template <typename T, typename = void>
744struct has_name : std::false_type {};
745template <typename T>
746struct has_name<T, decltype((void)T::name, void())> : std::true_type {};
747
748template <typename T, typename = void>
749struct has_id : std::false_type {};
750template <typename T>
751struct has_id<T, decltype((void)T::id, void())> : std::true_type {};
752
753template <typename T, typename = void>
754struct has_message : std::false_type {};
755template <typename T>
756struct has_message<T, decltype((void)T::message, void())> : std::true_type {};
757
758template <typename T, typename = void>
759struct is_c_string : std::false_type {};
760template <typename T>
761struct is_c_string<T, typename std::enable_if<
762 std::is_convertible<T, char const* >::value ||
763 std::is_convertible<T, wchar_t const*>::value
764>::type> : std::true_type {};
765
766template <typename T>
767using is_uint32 = std::is_same<typename std::decay<T>::type, uint32_t>;
768
769template <typename... Args>
770static inline void silence_unused(Args const&...) noexcept {}
771
772// Type trait to check for a .data() member returning T* or const T*
773// Some day, we can just use std::span
774template <typename T, typename TD>
775struct has_data_member
776{
777private:
778 template <typename U>
779 static auto test_data(int) -> decltype(std::declval<const U>().data());
780 template <typename>
781 static auto test_data(...) -> void;
782 using return_type = decltype(test_data<T>(0));
783
784public:
785 static constexpr bool value =
786 std::is_same<return_type, TD*>::value || std::is_same<return_type, TD const*>::value;
787};
788
789// Type trait to check for a .size() member returning something convertible to size_t
790template <typename T>
791struct has_size_member
792{
793private:
794 template <typename U>
795 static auto test_size(int) -> decltype(std::declval<const U>().size());
796 template <typename>
797 static auto test_size(...) -> void;
798 using return_type = decltype(test_size<T>(0));
799
800public:
801 static constexpr bool value = !std::is_same<return_type, void>::value &&
802 std::is_convertible<return_type, size_t>::value;
803};
804
815template <typename W, typename U, typename = void>
816struct is_safe_wrapper_of : std::false_type
817{
818};
819
820template <typename W, typename U>
821struct is_safe_wrapper_of<
822 W,
823 U,
824 typename std::enable_if<
825 std::is_standard_layout<W>::value && std::is_standard_layout<U>::value &&
826 std::is_trivially_copyable<W>::value && std::is_trivially_copyable<U>::value &&
827 sizeof(W) == sizeof(U)>::type> : std::true_type
828{
829};
830} // namespace detail
831
885class domain {
886 public:
887 domain(domain const&) = delete;
888 domain& operator=(domain const&) = delete;
889 domain(domain&&) = delete;
890 domain& operator=(domain&&) = delete;
891
903 struct global {
904 };
905
906#if NVTX3_USE_CHECKED_OVERLOADS_FOR_GET
951 template <typename D = global,
952 typename std::enable_if<
953 detail::is_c_string<decltype(D::name)>::value
954 , int>::type = 0>
955 NVTX3_NO_DISCARD static domain const& get() noexcept
956 {
957 static domain const d(D::name);
958 return d;
959 }
960
966 template <typename D = global,
967 typename std::enable_if<
968 !detail::is_c_string<decltype(D::name)>::value
969 , int>::type = 0>
970 NVTX3_NO_DISCARD static domain const& get() noexcept
971 {
972 NVTX3_STATIC_ASSERT(detail::always_false<D>::value,
973 "Type used to identify an NVTX domain must contain a static constexpr member "
974 "called 'name' of type const char* or const wchar_t* -- 'name' member is not "
975 "convertible to either of those types");
976 static domain const unused;
977 return unused; // Function must compile for static_assert to be triggered
978 }
979
984 template <typename D = global,
985 typename std::enable_if<
986 !detail::has_name<D>::value
987 , int>::type = 0>
988 NVTX3_NO_DISCARD static domain const& get() noexcept
989 {
990 NVTX3_STATIC_ASSERT(detail::always_false<D>::value,
991 "Type used to identify an NVTX domain must contain a static constexpr member "
992 "called 'name' of type const char* or const wchar_t* -- 'name' member is missing");
993 static domain const unused;
994 return unused; // Function must compile for static_assert to be triggered
995 }
996#else
997 template <typename D = global>
998 NVTX3_NO_DISCARD static domain const& get() noexcept
999 {
1000 static domain const d(D::name);
1001 return d;
1002 }
1003#endif
1004
1011 operator nvtxDomainHandle_t() const noexcept { return _domain; }
1012
1013 private:
1022 explicit domain(char const* name) noexcept : _domain{nvtxDomainCreateA(name)} {}
1023
1032 explicit domain(wchar_t const* name) noexcept : _domain{nvtxDomainCreateW(name)} {}
1033
1042 explicit domain(std::string const& name) noexcept : domain{name.c_str()} {}
1043
1052 explicit domain(std::wstring const& name) noexcept : domain{name.c_str()} {}
1053
1062 constexpr domain() noexcept {}
1063
1078 ~domain() = default;
1079
1080 private:
1081 nvtxDomainHandle_t const _domain{};
1082};
1083
1097template <>
1098NVTX3_NO_DISCARD inline domain const& domain::get<domain::global>() noexcept
1099{
1100 static domain const d{};
1101 return d;
1102}
1103
1109struct rgb {
1111 using component_type = uint8_t;
1112
1123 constexpr rgb(
1124 component_type red_,
1125 component_type green_,
1126 component_type blue_) noexcept
1127 : red{red_}, green{green_}, blue{blue_}
1128 {
1129 }
1130
1134};
1135
1141struct argb final : rgb {
1154 constexpr argb(
1155 component_type alpha_,
1156 component_type red_,
1157 component_type green_,
1158 component_type blue_) noexcept
1159 : rgb{red_, green_, blue_}, alpha{alpha_}
1160 {
1161 }
1162
1164};
1165
1175class color {
1176 public:
1178 using value_type = uint32_t;
1179
1197 constexpr explicit color(value_type hex_code) noexcept : _value{hex_code} {}
1198
1205 constexpr color(argb argb_) noexcept
1206 : color{from_bytes_msb_to_lsb(argb_.alpha, argb_.red, argb_.green, argb_.blue)}
1207 {
1208 }
1209
1218 constexpr color(rgb rgb_) noexcept
1219 : color{from_bytes_msb_to_lsb(0xFF, rgb_.red, rgb_.green, rgb_.blue)}
1220 {
1221 }
1222
1227 constexpr value_type get_value() const noexcept { return _value; }
1228
1233 constexpr nvtxColorType_t get_type() const noexcept { return _type; }
1234
1235 color() = delete;
1236 ~color() = default;
1237 color(color const&) = default;
1238 color& operator=(color const&) = default;
1239 color(color&&) = default;
1240 color& operator=(color&&) = default;
1241
1242 private:
1248 constexpr static value_type from_bytes_msb_to_lsb(
1249 uint8_t byte3,
1250 uint8_t byte2,
1251 uint8_t byte1,
1252 uint8_t byte0) noexcept
1253 {
1254 return uint32_t{byte3} << 24 | uint32_t{byte2} << 16 | uint32_t{byte1} << 8 | uint32_t{byte0};
1255 }
1256
1257 value_type _value{};
1258 nvtxColorType_t _type{NVTX_COLOR_ARGB};
1259};
1260
1283 public:
1285 using id_type = uint32_t;
1286
1296 constexpr explicit category(id_type id) noexcept : id_{id} {}
1297
1302 constexpr id_type get_id() const noexcept { return id_; }
1303
1304 category() = delete;
1305 ~category() = default;
1306 category(category const&) = default;
1307 category& operator=(category const&) = default;
1308 category(category&&) = default;
1309 category& operator=(category&&) = default;
1310
1311 private:
1312 id_type id_{};
1313};
1314
1364template <typename D = domain::global>
1365class named_category_in final : public category {
1366 public:
1367#if NVTX3_USE_CHECKED_OVERLOADS_FOR_GET
1402 template <typename C,
1403 typename std::enable_if<
1404 detail::is_c_string<decltype(C::name)>::value &&
1405 detail::is_uint32<decltype(C::id)>::value
1406 , int>::type = 0>
1407 static named_category_in const& get() noexcept
1408 {
1409 static named_category_in const cat(C::id, C::name);
1410 return cat;
1411 }
1412
1419 template <typename C,
1420 typename std::enable_if<
1421 !detail::is_c_string<decltype(C::name)>::value ||
1422 !detail::is_uint32<decltype(C::id)>::value
1423 , int>::type = 0>
1424 NVTX3_NO_DISCARD static named_category_in const& get() noexcept
1425 {
1426 NVTX3_STATIC_ASSERT(detail::is_c_string<decltype(C::name)>::value,
1427 "Type used to name an NVTX category must contain a static constexpr member "
1428 "called 'name' of type const char* or const wchar_t* -- 'name' member is not "
1429 "convertible to either of those types");
1430 NVTX3_STATIC_ASSERT(detail::is_uint32<decltype(C::id)>::value,
1431 "Type used to name an NVTX category must contain a static constexpr member "
1432 "called 'id' of type uint32_t -- 'id' member is the wrong type");
1433 static named_category_in const unused;
1434 return unused; // Function must compile for static_assert to be triggered
1435 }
1436
1441 template <typename C,
1442 typename std::enable_if<
1443 !detail::has_name<C>::value ||
1444 !detail::has_id<C>::value
1445 , int>::type = 0>
1446 NVTX3_NO_DISCARD static named_category_in const& get() noexcept
1447 {
1448 NVTX3_STATIC_ASSERT(detail::has_name<C>::value,
1449 "Type used to name an NVTX category must contain a static constexpr member "
1450 "called 'name' of type const char* or const wchar_t* -- 'name' member is missing");
1451 NVTX3_STATIC_ASSERT(detail::has_id<C>::value,
1452 "Type used to name an NVTX category must contain a static constexpr member "
1453 "called 'id' of type uint32_t -- 'id' member is missing");
1454 static named_category_in const unused;
1455 return unused; // Function must compile for static_assert to be triggered
1456 }
1457#else
1458 template <typename C>
1459 NVTX3_NO_DISCARD static named_category_in const& get() noexcept
1460 {
1461 static named_category_in const cat(C::id, C::name);
1462 return cat;
1463 }
1464#endif
1465
1466 private:
1467 // Default constructor is only used internally for static_assert(false) cases.
1468 named_category_in() noexcept : category{0} {}
1469
1470 public:
1481 named_category_in(id_type id, char const* name) noexcept : category{id}
1482 {
1483#ifndef NVTX_DISABLE
1484 nvtxDomainNameCategoryA(domain::get<D>(), get_id(), name);
1485#else
1486 (void)id;
1487 (void)name;
1488#endif
1489 }
1490
1501 named_category_in(id_type id, wchar_t const* name) noexcept : category{id}
1502 {
1503#ifndef NVTX_DISABLE
1504 nvtxDomainNameCategoryW(domain::get<D>(), get_id(), name);
1505#else
1506 (void)id;
1507 (void)name;
1508#endif
1509 }
1510};
1511
1517
1564template <typename D = domain::global>
1566 public:
1567#if NVTX3_USE_CHECKED_OVERLOADS_FOR_GET
1601 template <typename M,
1602 typename std::enable_if<
1603 detail::is_c_string<decltype(M::message)>::value
1604 , int>::type = 0>
1605 NVTX3_NO_DISCARD static registered_string_in const& get() noexcept
1606 {
1607 static registered_string_in const regstr(M::message);
1608 return regstr;
1609 }
1610
1616 template <typename M,
1617 typename std::enable_if<
1618 !detail::is_c_string<decltype(M::message)>::value
1619 , int>::type = 0>
1620 NVTX3_NO_DISCARD static registered_string_in const& get() noexcept
1621 {
1622 NVTX3_STATIC_ASSERT(detail::always_false<M>::value,
1623 "Type used to register an NVTX string must contain a static constexpr member "
1624 "called 'message' of type const char* or const wchar_t* -- 'message' member is "
1625 "not convertible to either of those types");
1626 static registered_string_in const unused;
1627 return unused; // Function must compile for static_assert to be triggered
1628 }
1629
1634 template <typename M,
1635 typename std::enable_if<
1636 !detail::has_message<M>::value
1637 , int>::type = 0>
1638 NVTX3_NO_DISCARD static registered_string_in const& get() noexcept
1639 {
1640 NVTX3_STATIC_ASSERT(detail::always_false<M>::value,
1641 "Type used to register an NVTX string must contain a static constexpr member "
1642 "called 'message' of type const char* or const wchar_t* -- 'message' member "
1643 "is missing");
1644 static registered_string_in const unused;
1645 return unused; // Function must compile for static_assert to be triggered
1646 }
1647#else
1648 template <typename M>
1649 NVTX3_NO_DISCARD static registered_string_in const& get() noexcept
1650 {
1651 static registered_string_in const regstr(M::message);
1652 return regstr;
1653 }
1654#endif
1655
1667 explicit registered_string_in(char const* msg) noexcept
1668 : handle_{nvtxDomainRegisterStringA(domain::get<D>(), msg)}
1669 {
1670 }
1671
1683 explicit registered_string_in(std::string const& msg) noexcept
1684 : registered_string_in{msg.c_str()} {}
1685
1697 explicit registered_string_in(wchar_t const* msg) noexcept
1698 : handle_{nvtxDomainRegisterStringW(domain::get<D>(), msg)}
1699 {
1700 }
1701
1713 explicit registered_string_in(std::wstring const& msg) noexcept
1714 : registered_string_in{msg.c_str()} {}
1715
1720 nvtxStringHandle_t get_handle() const noexcept
1721 {
1722 // We want to ensure that we can use the registered_string in place of a handle
1723 // in a payload data struct.
1724 NVTX3_STATIC_ASSERT(
1725 (detail::is_safe_wrapper_of<registered_string_in<D>, nvtxStringHandle_t>::value),
1726 "Internal error! registered_string_in is potentially unsafe.");
1727 return handle_;
1728 }
1729
1730private:
1731 // Default constructor is only used internally for static_assert(false) cases.
1732 registered_string_in() noexcept {}
1733public:
1734 ~registered_string_in() = default;
1736 registered_string_in& operator=(registered_string_in const&) = default;
1738 registered_string_in& operator=(registered_string_in&&) = default;
1739
1740 private:
1741 nvtxStringHandle_t handle_{};
1743};
1744
1750
1788class message {
1789 public:
1790 using value_type = nvtxMessageValue_t;
1791
1797 NVTX3_CONSTEXPR_IF_CPP14 message(char const* msg) noexcept : type_{NVTX_MESSAGE_TYPE_ASCII}
1798 {
1799 value_.ascii = msg;
1800 }
1801
1807 message(std::string const& msg) noexcept : message{msg.c_str()} {}
1808
1817#ifndef NVTX3_ALLOW_RVALUE_CONSTRUCTORS
1818 message(std::string&&) = delete;
1819#endif
1820
1826 NVTX3_CONSTEXPR_IF_CPP14 message(wchar_t const* msg) noexcept : type_{NVTX_MESSAGE_TYPE_UNICODE}
1827 {
1828 value_.unicode = msg;
1829 }
1830
1836 message(std::wstring const& msg) noexcept : message{msg.c_str()} {}
1837
1846#ifndef NVTX3_ALLOW_RVALUE_CONSTRUCTORS
1847 message(std::wstring&&) = delete;
1848#endif
1849
1858 template <typename D>
1859 NVTX3_CONSTEXPR_IF_CPP14 message(registered_string_in<D> const& msg) noexcept
1860 : type_{NVTX_MESSAGE_TYPE_REGISTERED}
1861 {
1862 value_.registered = msg.get_handle();
1863 }
1864
1871 constexpr message(
1872 nvtxMessageType_t const& type,
1873 nvtxMessageValue_t const& value) noexcept
1874 : type_{type}, value_(value)
1875 {
1876 }
1877
1883 NVTX3_CONSTEXPR_IF_CPP14 message(nvtxStringHandle_t handle) noexcept
1884 : type_{NVTX_MESSAGE_TYPE_REGISTERED}
1885 {
1886 value_.registered = handle;
1887 }
1888
1893 constexpr value_type get_value() const noexcept { return value_; }
1894
1899 constexpr nvtxMessageType_t get_type() const noexcept { return type_; }
1900
1901 private:
1902 nvtxMessageType_t type_{};
1903 nvtxMessageValue_t value_{};
1904};
1905
1922class payload {
1923 public:
1924 using value_type = typename nvtxEventAttributes_v2::payload_t;
1925
1931 NVTX3_CONSTEXPR_IF_CPP14 explicit payload(int64_t value) noexcept
1932 : type_{NVTX_PAYLOAD_TYPE_INT64}, value_{}
1933 {
1934 value_.llValue = value;
1935 }
1936
1942 NVTX3_CONSTEXPR_IF_CPP14 explicit payload(int32_t value) noexcept
1943 : type_{NVTX_PAYLOAD_TYPE_INT32}, value_{}
1944 {
1945 value_.iValue = value;
1946 }
1947
1953 NVTX3_CONSTEXPR_IF_CPP14 explicit payload(uint64_t value) noexcept
1954 : type_{NVTX_PAYLOAD_TYPE_UNSIGNED_INT64}, value_{}
1955 {
1956 value_.ullValue = value;
1957 }
1958
1964 NVTX3_CONSTEXPR_IF_CPP14 explicit payload(uint32_t value) noexcept
1965 : type_{NVTX_PAYLOAD_TYPE_UNSIGNED_INT32}, value_{}
1966 {
1967 value_.uiValue = value;
1968 }
1969
1976 NVTX3_CONSTEXPR_IF_CPP14 explicit payload(float value) noexcept
1977 : type_{NVTX_PAYLOAD_TYPE_FLOAT}, value_{}
1978 {
1979 value_.fValue = value;
1980 }
1981
1988 NVTX3_CONSTEXPR_IF_CPP14 explicit payload(double value) noexcept
1989 : type_{NVTX_PAYLOAD_TYPE_DOUBLE}, value_{}
1990 {
1991 value_.dValue = value;
1992 }
1993
2000 constexpr payload(
2001 nvtxPayloadType_t const& type,
2002 value_type const& value) noexcept
2003 : type_{type}, value_(value)
2004 {
2005 }
2006
2011 constexpr value_type get_value() const noexcept { return value_; }
2012
2017 constexpr nvtxPayloadType_t get_type() const noexcept { return type_; }
2018
2019 private:
2020 nvtxPayloadType_t type_;
2021 value_type value_;
2022};
2023
2036{
2037private:
2043 schema()
2044 : _schema_id{0}
2045 {}
2046
2047 public:
2048 schema(schema const&) = delete;
2049 schema& operator=(schema const&) = delete;
2050 schema(schema&&) = delete;
2051 schema& operator=(schema&&) = delete;
2052
2061 explicit schema(uint64_t id)
2062 : _schema_id{id}
2063 {}
2064
2075 template <typename T>
2076 NVTX3_NO_DISCARD static schema const& get() noexcept
2077 {
2078 NVTX3_STATIC_ASSERT(
2079 detail::always_false<T>::value,
2080 "payload_data schema deduction requires a template specialization. Use the macro "
2081 "NVTX3_DEFINE_SCHEMA_GET to generate this specialization.");
2082 static schema unused;
2083 return unused;
2084 }
2085
2089 uint64_t get_handle() const noexcept
2090 {
2091 return _schema_id;
2092 }
2093
2094private:
2095 uint64_t const _schema_id;
2096};
2097
2106{
2107public:
2115 explicit payload_data(nvtxPayloadData_t const& pd)
2116 : data_(pd)
2117 {}
2118
2132 // We cannot simply delete the rvalue constructor here because with a template
2133 // parameter that would be a forwarding reference. Thus, we have this one
2134 // ctor with a forwarding reference and use a static assert for the rvalue check.
2135 // Disable this for the C-style nvtxPayloadData_t to prefer above ctor for non-const.
2136 template <
2137 typename R,
2138 typename T = typename std::remove_cv<typename std::remove_reference<R>::type>::type,
2139 typename = typename std::enable_if<!std::is_same<T, nvtxPayloadData_t>::value>::type>
2140 explicit payload_data(R&& t)
2141 : data_{schema::get<T>().get_handle(), sizeof(T), &t}
2142 {
2143#ifndef NVTX3_ALLOW_RVALUE_CONSTRUCTORS
2144 NVTX3_STATIC_ASSERT(
2145 std::is_lvalue_reference<R>::value,
2146 "payload_data requires an lvalue reference to the underlying data. Constructing "
2147 "from an rvalue is potentially unsafe and therefore forbidden.");
2148#endif
2149 NVTX3_STATIC_ASSERT(
2150 std::is_standard_layout<T>::value && std::is_trivially_copyable<T>::value,
2151 "structs used for NVTX3 payload schema must be standard layout and trivially copyable");
2152 }
2153
2166 template <typename T>
2167 explicit payload_data(T const& t, schema s)
2168 : data_{s.get_handle(), sizeof(T), &t}
2169 {
2170 NVTX3_STATIC_ASSERT(
2171 std::is_standard_layout<T>::value && std::is_trivially_copyable<T>::value,
2172 "structs used for NVTX3 payload schema must be standard layout and trivially copyable");
2173 }
2174
2179 uint64_t as_ull_value() const noexcept
2180 {
2181 NVTX3_STATIC_ASSERT(
2182 (detail::is_safe_wrapper_of<payload_data, nvtxPayloadData_t>::value),
2183 "Internal error! payload_data is potentially unsafe.");
2184 return NVTX_POINTER_AS_PAYLOAD_ULLVALUE(&data_);
2185 }
2186
2187private:
2188 nvtxPayloadData_t data_;
2189};
2190
2250 public:
2251 using value_type = nvtxEventAttributes_t;
2252
2257 constexpr event_attributes() noexcept
2258 : attributes_{
2259 NVTX_VERSION, // version
2260 sizeof(nvtxEventAttributes_t), // size
2261 0, // category
2262 NVTX_COLOR_UNKNOWN, // color type
2263 0, // color value
2264 NVTX_PAYLOAD_UNKNOWN, // payload type
2265 0, // reserved 4B
2266 {0}, // payload value (union)
2267 NVTX_MESSAGE_UNKNOWN, // message type
2268 {nullptr} // message value (union)
2269 }
2270 {
2271 }
2272
2280 template <typename... Args>
2281 NVTX3_CONSTEXPR_IF_CPP14 explicit event_attributes(category const& c, Args const&... args) noexcept
2282 : event_attributes(args...)
2283 {
2284 attributes_.category = c.get_id();
2285 }
2286
2294 template <typename... Args>
2295 NVTX3_CONSTEXPR_IF_CPP14 explicit event_attributes(color const& c, Args const&... args) noexcept
2296 : event_attributes(args...)
2297 {
2298 attributes_.color = c.get_value();
2299 attributes_.colorType = c.get_type();
2300 }
2301
2309 template <typename... Args>
2310 NVTX3_CONSTEXPR_IF_CPP14 explicit event_attributes(payload const& p, Args const&... args) noexcept
2311 : event_attributes(args...)
2312 {
2313 attributes_.payload = p.get_value();
2314 attributes_.payloadType = p.get_type();
2315 }
2316
2324 template <typename... Args>
2325 NVTX3_CONSTEXPR_IF_CPP14 explicit event_attributes(payload_data const& pd, Args const&... args) noexcept
2326 : event_attributes(args...)
2327 {
2328 attributes_.payloadType = NVTX_PAYLOAD_TYPE_EXT;
2329 attributes_.reserved0 = 1;
2330 attributes_.payload.ullValue = pd.as_ull_value();
2331 }
2332
2340#ifndef NVTX3_ALLOW_RVALUE_CONSTRUCTORS
2341 template <typename... Args>
2342 NVTX3_CONSTEXPR_IF_CPP14 explicit event_attributes(payload_data&& pd, Args const&... args) = delete;
2343#endif
2344
2354 template <
2355 typename T,
2356 typename... Args,
2357 typename = typename std::enable_if<
2358 detail::has_data_member<T, payload_data>::value && detail::has_size_member<T>::value>::type>
2359 NVTX3_CONSTEXPR_IF_CPP20 explicit event_attributes(T&& pdc, Args const&... args) noexcept
2360 : event_attributes(args...)
2361 {
2362 NVTX3_STATIC_ASSERT(
2363 std::is_lvalue_reference<T>::value,
2364 "event_attributes requires an lvalue reference to the underlying data. "
2365 "Constructing from an rvalue is potentially unsafe and therefore forbidden.");
2366 attributes_.payloadType = NVTX_PAYLOAD_TYPE_EXT;
2367 attributes_.reserved0 = static_cast<int32_t>(pdc.size()); // Cast size to int32_t
2368 attributes_.payload.ullValue = pdc.data()->as_ull_value();
2369 }
2370
2378 template <typename... Args>
2379 NVTX3_CONSTEXPR_IF_CPP14 explicit event_attributes(message const& m, Args const&... args) noexcept
2380 : event_attributes(args...)
2381 {
2382 attributes_.message = m.get_value();
2383 attributes_.messageType = m.get_type();
2384 }
2385
2386 ~event_attributes() = default;
2387 event_attributes(event_attributes const&) = default;
2388 event_attributes& operator=(event_attributes const&) = default;
2390 event_attributes& operator=(event_attributes&&) = default;
2391
2396 constexpr value_type const* get() const noexcept { return &attributes_; }
2397
2398 private:
2399 value_type attributes_{};
2400};
2401
2449template <class D = domain::global>
2450class NVTX3_MAYBE_UNUSED scoped_range_in {
2451 public:
2466 explicit scoped_range_in(event_attributes const& attr) noexcept
2467 {
2468#ifndef NVTX_DISABLE
2469 nvtxDomainRangePushEx(domain::get<D>(), attr.get());
2470#else
2471 (void)attr;
2472#endif
2473 }
2474
2495 template <typename... Args>
2496 explicit scoped_range_in(Args const&... args) noexcept
2498 {
2499 }
2500
2507
2514 void* operator new(std::size_t) = delete;
2515
2516 scoped_range_in(scoped_range_in const&) = delete;
2517 scoped_range_in& operator=(scoped_range_in const&) = delete;
2518 scoped_range_in(scoped_range_in&&) = delete;
2519 scoped_range_in& operator=(scoped_range_in&&) = delete;
2520
2525 {
2526#ifndef NVTX_DISABLE
2527 nvtxDomainRangePop(domain::get<D>());
2528#endif
2529 }
2530};
2531
2537
2538namespace detail {
2539
2541template <typename D = domain::global>
2542class NVTX3_MAYBE_UNUSED optional_scoped_range_in
2543{
2544public:
2545 optional_scoped_range_in() = default;
2546
2547 void begin(event_attributes const& attr) noexcept
2548 {
2549#ifndef NVTX_DISABLE
2550 // This class is not meant to be part of the public NVTX C++ API and should
2551 // only be used in the `NVTX3_FUNC_RANGE_IF` and `NVTX3_FUNC_RANGE_IF_IN`
2552 // macros. However, to prevent developers from misusing this class, make
2553 // sure to not start multiple ranges.
2554 if (initialized) { return; }
2555
2556 nvtxDomainRangePushEx(domain::get<D>(), attr.get());
2557 initialized = true;
2558#else
2559 (void)attr;
2560#endif
2561 }
2562
2563 ~optional_scoped_range_in() noexcept
2564 {
2565#ifndef NVTX_DISABLE
2566 if (initialized) { nvtxDomainRangePop(domain::get<D>()); }
2567#endif
2568 }
2569
2570 void* operator new(std::size_t) = delete;
2571 optional_scoped_range_in(optional_scoped_range_in const&) = delete;
2572 optional_scoped_range_in& operator=(optional_scoped_range_in const&) = delete;
2573 optional_scoped_range_in(optional_scoped_range_in&&) = delete;
2574 optional_scoped_range_in& operator=(optional_scoped_range_in&&) = delete;
2575
2576private:
2577#ifndef NVTX_DISABLE
2578 bool initialized = false;
2579#endif
2580};
2582
2583} // namespace detail
2584
2593 using value_type = nvtxRangeId_t;
2594
2595
2600 constexpr explicit range_handle(value_type id) noexcept : _range_id{id} {}
2601
2609 constexpr range_handle() noexcept = default;
2610
2622 constexpr explicit operator bool() const noexcept { return get_value() != null_range_id; }
2623
2630 constexpr range_handle(std::nullptr_t) noexcept {}
2631
2637 constexpr value_type get_value() const noexcept { return _range_id; }
2638
2639 private:
2641 static constexpr value_type null_range_id = nvtxRangeId_t{0};
2642
2643 value_type _range_id{null_range_id};
2644};
2645
2652inline constexpr bool operator==(range_handle lhs, range_handle rhs) noexcept
2653{
2654 return lhs.get_value() == rhs.get_value();
2655}
2656
2663inline constexpr bool operator!=(range_handle lhs, range_handle rhs) noexcept { return !(lhs == rhs); }
2664
2694template <typename D = domain::global>
2695NVTX3_NO_DISCARD inline range_handle start_range_in(event_attributes const& attr) noexcept
2696{
2697#ifndef NVTX_DISABLE
2698 return range_handle{nvtxDomainRangeStartEx(domain::get<D>(), attr.get())};
2699#else
2700 (void)attr;
2701 return {};
2702#endif
2703}
2704
2735template <typename D = domain::global, typename... Args>
2736NVTX3_NO_DISCARD inline range_handle start_range_in(Args const&... args) noexcept
2737{
2738#ifndef NVTX_DISABLE
2739 return start_range_in<D>(event_attributes{args...});
2740#else
2741 detail::silence_unused(args...);
2742 return {};
2743#endif
2744}
2745
2772NVTX3_NO_DISCARD inline range_handle start_range(event_attributes const& attr) noexcept
2773{
2774#ifndef NVTX_DISABLE
2775 return start_range_in<domain::global>(attr);
2776#else
2777 (void)attr;
2778 return {};
2779#endif
2780}
2781
2809template <typename... Args>
2810NVTX3_NO_DISCARD inline range_handle start_range(Args const&... args) noexcept
2811{
2812#ifndef NVTX_DISABLE
2813 return start_range_in<domain::global>(args...);
2814#else
2815 detail::silence_unused(args...);
2816 return {};
2817#endif
2818}
2819
2835template <typename D = domain::global>
2836inline void end_range_in(range_handle r) noexcept
2837{
2838#ifndef NVTX_DISABLE
2839 nvtxDomainRangeEnd(domain::get<D>(), r.get_value());
2840#else
2841 (void)r;
2842#endif
2843}
2844
2858inline void end_range(range_handle r) noexcept
2859{
2860#ifndef NVTX_DISABLE
2861 end_range_in<domain::global>(r);
2862#else
2863 (void)r;
2864#endif
2865}
2866
2888template <typename D = domain::global>
2889class NVTX3_MAYBE_UNUSED unique_range_in {
2890 public:
2904 explicit unique_range_in(event_attributes const& attr) noexcept
2905 : handle_{start_range_in<D>(attr)}
2906 {
2907 }
2908
2928 template <typename... Args>
2929 explicit unique_range_in(Args const&... args) noexcept
2931 {
2932 }
2933
2940
2945 ~unique_range_in() noexcept = default;
2946
2953 unique_range_in(unique_range_in&& other) noexcept = default;
2954
2961 unique_range_in& operator=(unique_range_in&& other) noexcept = default;
2962
2966
2969 unique_range_in& operator=(unique_range_in const&) = delete;
2970
2971 private:
2972
2973 struct end_range_handle {
2974 using pointer = range_handle;
2975 void operator()(range_handle h) const noexcept { end_range_in<D>(h); }
2976 };
2977
2979 std::unique_ptr<range_handle, end_range_handle> handle_;
2980};
2981
2987
3011template <typename D = domain::global>
3012inline void mark_in(event_attributes const& attr) noexcept
3013{
3014#ifndef NVTX_DISABLE
3015 nvtxDomainMarkEx(domain::get<D>(), attr.get());
3016#else
3017 (void)(attr);
3018#endif
3019}
3020
3048template <typename D = domain::global, typename... Args>
3049inline void mark_in(Args const&... args) noexcept
3050{
3051#ifndef NVTX_DISABLE
3052 mark_in<D>(event_attributes{args...});
3053#else
3054 detail::silence_unused(args...);
3055#endif
3056}
3057
3078inline void mark(event_attributes const& attr) noexcept
3079{
3080#ifndef NVTX_DISABLE
3081 mark_in<domain::global>(attr);
3082#else
3083 (void)attr;
3084#endif
3085}
3086
3111template <typename... Args>
3112inline void mark(Args const&... args) noexcept
3113{
3114#ifndef NVTX_DISABLE
3115 mark_in<domain::global>(args...);
3116#else
3117 detail::silence_unused(args...);
3118#endif
3119}
3120
3121} // namespace NVTX3_MINOR_VERSION_NAMESPACE
3122} // namespace NVTX3_VERSION_NAMESPACE
3123} // namespace nvtx3
3124
3125#ifndef NVTX_DISABLE
3154#define NVTX3_V1_FUNC_RANGE_IN(D) \
3155 static ::nvtx3::v1::registered_string_in<D> const nvtx3_func_name__{__func__}; \
3156 static ::nvtx3::v1::event_attributes const nvtx3_func_attr__{nvtx3_func_name__}; \
3157 ::nvtx3::v1::scoped_range_in<D> const nvtx3_range__{nvtx3_func_attr__}
3158
3175#define NVTX3_V1_FUNC_RANGE_IF_IN(D, C) \
3176 ::nvtx3::v1::detail::optional_scoped_range_in<D> optional_nvtx3_range__; \
3177 if (C) { \
3178 static ::nvtx3::v1::registered_string_in<D> const nvtx3_func_name__{__func__}; \
3179 static ::nvtx3::v1::event_attributes const nvtx3_func_attr__{nvtx3_func_name__}; \
3180 optional_nvtx3_range__.begin(nvtx3_func_attr__); \
3181 } (void)0
3182#else /* NVTX_DISABLE */
3183#define NVTX3_V1_FUNC_RANGE_IN(D) (void)0
3184#define NVTX3_V1_FUNC_RANGE_IF_IN(D, C) (void)(C)
3185#endif /* NVTX_DISABLE */
3186
3209#define NVTX3_V1_FUNC_RANGE() NVTX3_V1_FUNC_RANGE_IN(::nvtx3::v1::domain::global)
3210
3222#define NVTX3_V1_FUNC_RANGE_IF(C) NVTX3_V1_FUNC_RANGE_IF_IN(::nvtx3::v1::domain::global, C)
3223
3224// We need another helper macro because the other one will get undefined
3225#if __has_cpp_attribute(nodiscard)
3226#define NVTX3_V1_NO_DISCARD [[nodiscard]]
3227#else
3228#define NVTX3_V1_NO_DISCARD
3229#endif
3262#define NVTX3_V1_DEFINE_SCHEMA_GET(dom, struct_id, schema_name, entries) \
3263 template <> \
3264 NVTX3_V1_NO_DISCARD inline nvtx3::v1::schema const& nvtx3::v1::schema::get<struct_id>() noexcept \
3265 { \
3266 static_assert( \
3267 std::is_standard_layout<struct_id>::value, \
3268 "structs used for NVTX3 payload schema must be standard layout"); \
3269 static_assert( \
3270 std::is_trivially_copyable<struct_id>::value, \
3271 "structs used for NVTX3 payload schema must be trivially copyable"); \
3272 using nvtx_struct_id = struct_id; /* avoids issues with namespaced struct_id */ \
3273 _NVTX_DEFINE_SCHEMA_FOR_STRUCT(nvtx_struct_id, schema_name, static constexpr, entries) \
3274 static const schema s{ \
3275 nvtxPayloadSchemaRegister(nvtx3::v1::domain::get<dom>(), &nvtx_struct_id##Attr)}; \
3276 return s; \
3277 }
3278
3279/* When inlining this version, versioned macros must have unversioned aliases.
3280 * For each NVTX3_Vx_ #define, make an NVTX3_ alias of it here.*/
3281#if defined(NVTX3_INLINE_THIS_VERSION)
3282/* clang format off */
3283#define NVTX3_FUNC_RANGE NVTX3_V1_FUNC_RANGE
3284#define NVTX3_FUNC_RANGE_IF NVTX3_V1_FUNC_RANGE_IF
3285#define NVTX3_FUNC_RANGE_IN NVTX3_V1_FUNC_RANGE_IN
3286#define NVTX3_FUNC_RANGE_IF_IN NVTX3_V1_FUNC_RANGE_IF_IN
3287#define NVTX3_DEFINE_SCHEMA_GET NVTX3_V1_DEFINE_SCHEMA_GET
3288/* clang format on */
3289#endif
3290
3291#endif // NVTX3_CPP_DEFINITIONS_V1_0
3292
3293/* Add functionality for new minor versions here, by copying the above section enclosed
3294 * in #ifndef NVTX3_CPP_DEFINITIONS_Vx_y, and incrementing the minor version. This code
3295 * is an example of how additions for version 1.2 would look, indented for clarity. Note
3296 * that the versioned symbols and macros are always provided, and the unversioned symbols
3297 * are only provided if NVTX3_INLINE_THIS_VERSION was defined at the top of this header.
3298 *
3299 * \code{.cpp}
3300 * #ifndef NVTX3_CPP_DEFINITIONS_V1_2
3301 * #define NVTX3_CPP_DEFINITIONS_V1_2
3302 * namespace nvtx3 {
3303 * NVTX3_INLINE_IF_REQUESTED namespace NVTX3_VERSION_NAMESPACE {
3304 * class new_class {};
3305 * inline void new_function() {}
3306 * }
3307 * }
3308 *
3309 * // Macros must have the major version in their names:
3310 * #define NVTX3_V1_NEW_MACRO_A() ...
3311 * #define NVTX3_V1_NEW_MACRO_B() ...
3312 *
3313 * // If inlining, make aliases for the macros with the version number omitted
3314 * #if defined(NVTX3_INLINE_THIS_VERSION)
3315 * #define NVTX3_NEW_MACRO_A NVTX3_V1_NEW_MACRO_A
3316 * #define NVTX3_NEW_MACRO_B NVTX3_V1_NEW_MACRO_B
3317 * #endif
3318 * #endif // NVTX3_CPP_DEFINITIONS_V1_2
3319 * \endcode
3320 */
3321
3322/* Undefine all temporarily-defined unversioned macros, which would conflict with
3323 * subsequent includes of different versions of this header. */
3324#undef NVTX3_CPP_VERSION_MAJOR
3325#undef NVTX3_CPP_VERSION_MINOR
3326#undef NVTX3_CONCAT
3327#undef NVTX3_NAMESPACE_FOR
3328#undef NVTX3_VERSION_NAMESPACE
3329#undef NVTX3_MINOR_NAMESPACE_FOR
3330#undef NVTX3_MINOR_VERSION_NAMESPACE
3331#undef NVTX3_INLINE_IF_REQUESTED
3332#undef NVTX3_CONSTEXPR_IF_CPP14
3333#undef NVTX3_MAYBE_UNUSED
3334#undef NVTX3_NO_DISCARD
3335
3336#if defined(NVTX3_INLINE_THIS_VERSION)
3337#undef NVTX3_INLINE_THIS_VERSION
3338#endif
3339
3340#if defined(NVTX3_USE_CHECKED_OVERLOADS_FOR_GET_DEFINED_HERE)
3341#undef NVTX3_USE_CHECKED_OVERLOADS_FOR_GET_DEFINED_HERE
3342#undef NVTX3_USE_CHECKED_OVERLOADS_FOR_GET
3343#endif
3344
3345#if defined(NVTX3_STATIC_ASSERT_DEFINED_HERE)
3346#undef NVTX3_STATIC_ASSERT_DEFINED_HERE
3347#undef NVTX3_STATIC_ASSERT
3348#endif
Object for intra-domain grouping of NVTX events.
Definition nvtx3.hpp:1282
constexpr category(id_type id) noexcept
Construct a category with the specified id.
Definition nvtx3.hpp:1296
constexpr id_type get_id() const noexcept
Returns the id of the category.
Definition nvtx3.hpp:1302
uint32_t id_type
Type used for categorys integer id.
Definition nvtx3.hpp:1285
Represents a custom color that can be associated with an NVTX event via its event_attributes.
Definition nvtx3.hpp:1175
uint32_t value_type
Type used for the color's value.
Definition nvtx3.hpp:1178
constexpr nvtxColorType_t get_type() const noexcept
Return the NVTX color type of the color.
Definition nvtx3.hpp:1233
constexpr color(argb argb_) noexcept
Construct a color using the alpha, red, green, blue components in argb.
Definition nvtx3.hpp:1205
constexpr color(rgb rgb_) noexcept
Construct a color using the red, green, blue components in rgb.
Definition nvtx3.hpp:1218
constexpr color(value_type hex_code) noexcept
Constructs a color using the value provided by hex_code.
Definition nvtx3.hpp:1197
constexpr value_type get_value() const noexcept
Returns the colors argb hex code.
Definition nvtx3.hpp:1227
domains allow for grouping NVTX events into a single scope to differentiate them from events in other...
Definition nvtx3.hpp:885
static domain const & get() noexcept
Returns reference to an instance of a function local static domain object.
Definition nvtx3.hpp:955
Describes the attributes of a NVTX event.
Definition nvtx3.hpp:2249
constexpr event_attributes() noexcept
Default constructor creates an event_attributes with no category, color, payload, nor message.
Definition nvtx3.hpp:2257
constexpr value_type const * get() const noexcept
Get raw pointer to underlying NVTX attributes object.
Definition nvtx3.hpp:2396
event_attributes(payload_data &&pd, Args const &... args)=delete
Deleted constructor for payload_data rvalue references.
event_attributes(message const &m, Args const &... args) noexcept
Variadic constructor where the first argument is a message.
Definition nvtx3.hpp:2379
event_attributes(T &&pdc, Args const &... args) noexcept
Variadic constructor template for containers of payload_data.
Definition nvtx3.hpp:2359
event_attributes(payload const &p, Args const &... args) noexcept
Variadic constructor where the first argument is a payload.
Definition nvtx3.hpp:2310
event_attributes(color const &c, Args const &... args) noexcept
Variadic constructor where the first argument is a color.
Definition nvtx3.hpp:2295
event_attributes(category const &c, Args const &... args) noexcept
Variadic constructor where the first argument is a category.
Definition nvtx3.hpp:2281
event_attributes(payload_data const &pd, Args const &... args) noexcept
Variadic constructor where the first argument is a single payload_data.
Definition nvtx3.hpp:2325
Allows associating a message string with an NVTX event via its EventAttributes.
Definition nvtx3.hpp:1788
message(nvtxStringHandle_t handle) noexcept
Construct a message from NVTX C API registered string handle.
Definition nvtx3.hpp:1883
constexpr nvtxMessageType_t get_type() const noexcept
Return the type information about the value the union holds.
Definition nvtx3.hpp:1899
message(std::string const &msg) noexcept
Construct a message whose contents are specified by msg.
Definition nvtx3.hpp:1807
message(std::wstring const &msg) noexcept
Construct a message whose contents are specified by msg.
Definition nvtx3.hpp:1836
message(registered_string_in< D > const &msg) noexcept
Construct a message from a registered_string_in.
Definition nvtx3.hpp:1859
constexpr value_type get_value() const noexcept
Return the union holding the value of the message.
Definition nvtx3.hpp:1893
message(wchar_t const *msg) noexcept
Construct a message whose contents are specified by msg.
Definition nvtx3.hpp:1826
message(std::string &&)=delete
Disallow construction for std::string r-value.
message(char const *msg) noexcept
Construct a message whose contents are specified by msg.
Definition nvtx3.hpp:1797
constexpr message(nvtxMessageType_t const &type, nvtxMessageValue_t const &value) noexcept
Construct a message from NVTX C API type and value.
Definition nvtx3.hpp:1871
message(std::wstring &&)=delete
Disallow construction for std::wstring r-value.
A category with an associated name string.
Definition nvtx3.hpp:1365
named_category_in(id_type id, wchar_t const *name) noexcept
Construct a named_category_in with the specified id and name.
Definition nvtx3.hpp:1501
static named_category_in const & get() noexcept
Returns a global instance of a named_category_in as a function-local static.
Definition nvtx3.hpp:1407
named_category_in(id_type id, char const *name) noexcept
Construct a named_category_in with the specified id and name.
Definition nvtx3.hpp:1481
Wrapper around the NVTX C API nvtxPayloadData_t struct.
Definition nvtx3.hpp:2106
payload_data(T const &t, schema s)
Constructs payload_data for a payload instance with a given schema.
Definition nvtx3.hpp:2167
payload_data(nvtxPayloadData_t const &pd)
Constructs payload_data from an existing NVTX C API struct.
Definition nvtx3.hpp:2115
uint64_t as_ull_value() const noexcept
Definition nvtx3.hpp:2179
payload_data(R &&t)
Constructs payload_data for a specific payload struct instance.
Definition nvtx3.hpp:2140
A numerical value that can be associated with an NVTX event via its event_attributes.
Definition nvtx3.hpp:1922
payload(uint32_t value) noexcept
Construct a payload from an unsigned, 4 byte integer.
Definition nvtx3.hpp:1964
payload(double value) noexcept
Construct a payload from a double-precision floating point value.
Definition nvtx3.hpp:1988
payload(uint64_t value) noexcept
Construct a payload from an unsigned, 8 byte integer.
Definition nvtx3.hpp:1953
payload(int64_t value) noexcept
Construct a payload from a signed, 8 byte integer.
Definition nvtx3.hpp:1931
constexpr payload(nvtxPayloadType_t const &type, value_type const &value) noexcept
Construct a payload from NVTX C API type and value.
Definition nvtx3.hpp:2000
constexpr value_type get_value() const noexcept
Return the union holding the value of the payload.
Definition nvtx3.hpp:2011
constexpr nvtxPayloadType_t get_type() const noexcept
Return the information about the type the union holds.
Definition nvtx3.hpp:2017
payload(float value) noexcept
Construct a payload from a single-precision floating point value.
Definition nvtx3.hpp:1976
payload(int32_t value) noexcept
Construct a payload from a signed, 4 byte integer.
Definition nvtx3.hpp:1942
A message registered with NVTX.
Definition nvtx3.hpp:1565
static registered_string_in const & get() noexcept
Returns a global instance of a registered_string_in as a function local static.
Definition nvtx3.hpp:1605
nvtxStringHandle_t get_handle() const noexcept
Returns the registered string's handle.
Definition nvtx3.hpp:1720
registered_string_in(std::wstring const &msg) noexcept
Constructs a registered_string_in from the specified msg string.
Definition nvtx3.hpp:1713
registered_string_in(char const *msg) noexcept
Constructs a registered_string_in from the specified msg string.
Definition nvtx3.hpp:1667
registered_string_in(std::string const &msg) noexcept
Constructs a registered_string_in from the specified msg string.
Definition nvtx3.hpp:1683
registered_string_in(wchar_t const *msg) noexcept
Constructs a registered_string_in from the specified msg string.
Definition nvtx3.hpp:1697
Represents the registered schema for a payload struct.
Definition nvtx3.hpp:2036
static schema const & get() noexcept
Gets the schema instance for a specific payload struct type.
Definition nvtx3.hpp:2076
uint64_t get_handle() const noexcept
Return the underlying C handle of the schema.
Definition nvtx3.hpp:2089
schema(uint64_t id)
Constructs a schema object directly from a schema ID.
Definition nvtx3.hpp:2061
A RAII object for creating a NVTX range local to a thread within a domain.
Definition nvtx3.hpp:2450
scoped_range_in(Args const &... args) noexcept
Constructs a scoped_range_in from the constructor arguments of an event_attributes.
Definition nvtx3.hpp:2496
~scoped_range_in() noexcept
Destroy the scoped_range_in, ending the NVTX range event.
Definition nvtx3.hpp:2524
scoped_range_in(event_attributes const &attr) noexcept
Construct a scoped_range_in with the specified event_attributes
Definition nvtx3.hpp:2466
scoped_range_in() noexcept
Default constructor creates a scoped_range_in with no message, color, payload, nor category.
Definition nvtx3.hpp:2506
A RAII object for creating a NVTX range within a domain that can be created and destroyed on differen...
Definition nvtx3.hpp:2889
unique_range_in(event_attributes const &attr) noexcept
Construct a new unique_range_in object with the specified event attributes.
Definition nvtx3.hpp:2904
~unique_range_in() noexcept=default
Destroy the unique_range_in ending the range.
unique_range_in(Args const &... args) noexcept
Constructs a unique_range_in from the constructor arguments of an event_attributes.
Definition nvtx3.hpp:2929
constexpr unique_range_in() noexcept
Default constructor creates a unique_range_in with no message, color, payload, nor category.
Definition nvtx3.hpp:2939
void mark_in(event_attributes const &attr) noexcept
Annotates an instantaneous point in time with a "marker", using the attributes specified by attr.
Definition nvtx3.hpp:3012
constexpr bool operator!=(range_handle lhs, range_handle rhs) noexcept
Compares two range_handles for inequality.
Definition nvtx3.hpp:2663
constexpr bool operator==(range_handle lhs, range_handle rhs) noexcept
Compares two range_handles for equality.
Definition nvtx3.hpp:2652
void mark(event_attributes const &attr) noexcept
Annotates an instantaneous point in time with a "marker", using the attributes specified by attr,...
Definition nvtx3.hpp:3078
range_handle start_range_in(event_attributes const &attr) noexcept
Manually begin an NVTX range.
Definition nvtx3.hpp:2695
void end_range(range_handle r) noexcept
Manually end the range associated with the handle r in the global domain.
Definition nvtx3.hpp:2858
range_handle start_range(event_attributes const &attr) noexcept
Manually begin an NVTX range in the global domain.
Definition nvtx3.hpp:2772
void end_range_in(range_handle r) noexcept
Manually end the range associated with the handle r in domain D.
Definition nvtx3.hpp:2836
Indicates the value of the alpha, red, green, and blue color channels for an ARGB color to use as an ...
Definition nvtx3.hpp:1141
constexpr argb(component_type alpha_, component_type red_, component_type green_, component_type blue_) noexcept
Construct an argb with alpha, red, green, and blue channels specified by alpha_, red_,...
Definition nvtx3.hpp:1154
Tag type for the "global" NVTX domain.
Definition nvtx3.hpp:903
Handle used for correlating explicit range start and end events.
Definition nvtx3.hpp:2591
nvtxRangeId_t value_type
Type used for the handle's value.
Definition nvtx3.hpp:2593
constexpr range_handle(value_type id) noexcept
Construct a range_handle from the given id.
Definition nvtx3.hpp:2600
constexpr value_type get_value() const noexcept
Returns the range_handle's value.
Definition nvtx3.hpp:2637
constexpr range_handle() noexcept=default
Constructs a null range handle.
constexpr range_handle(std::nullptr_t) noexcept
Implicit conversion from nullptr constructs a null handle.
Definition nvtx3.hpp:2630
Indicates the values of the red, green, and blue color channels for an RGB color to use as an event a...
Definition nvtx3.hpp:1109
constexpr rgb(component_type red_, component_type green_, component_type blue_) noexcept
Construct a rgb with red, green, and blue channels specified by red_, green_, and blue_,...
Definition nvtx3.hpp:1123
uint8_t component_type
Type used for component values.
Definition nvtx3.hpp:1111