corecel/sys/ScopedProfiling.hh

0001 //------------------------------- -*- C++ -*- -------------------------------//
0002 // Copyright Celeritas contributors: see top-level COPYRIGHT file for details
0003 // SPDX-License-Identifier: (Apache-2.0 OR MIT)
0004 //---------------------------------------------------------------------------//
0005 //! \file corecel/sys/ScopedProfiling.hh
0006 //---------------------------------------------------------------------------//
0007 #pragma once
0008
0009 #include <cstdint>
0010 #include <string>
0011
0012 #include "corecel/Config.hh"
0013
0014 #include "corecel/Macros.hh"
0015 #include "corecel/io/Logger.hh"
0016
0017 #include "Environment.hh"
0018
0019 namespace celeritas
0020 {
0021 //---------------------------------------------------------------------------//
0022 // Whether profiling is enabled
0023 bool use_profiling();
0024
0025 //---------------------------------------------------------------------------//
0026 /*!
0027  * Input arguments for the nvtx implementation.
0028  */
0029 struct ScopedProfilingInput
0030 {
0031     std::string_view name;  //!< Name of the range
0032     uint32_t color{};  //!< ARGB
0033     int32_t payload{};  //!< User data
0034     uint32_t category{};  //!< Category, used to group ranges together
0035
0036     ScopedProfilingInput(std::string_view n) : name{n} {}
0037 };
0038
0039 //---------------------------------------------------------------------------//
0040 /*!
0041  * RAII class for scoped profiling.
0042  *
0043  * Implementations should support multithreaded context where each thread have
0044  * one or more alive instance of this class.
0045  *
0046  * This is useful for wrapping specific code fragment in a range for profiling,
0047  * e.g. ignoring of VecGeom instantiation kernels, profiling a specific action
0048  * or loop on the CPU.
0049  *
0050  * \note The nvtx implementation of \c ScopedProfiling only does something when
0051  * the application using Celeritas is ran through a tool that supports nvtx,
0052  * e.g. nsight compute with the --nvtx argument. If this is not the case, API
0053  * calls to nvtx are no-ops.
0054  *
0055  * \note The AMD roctx implementation requires the roctx library, which may not
0056  * be available on all systems.
0057  *
0058  * \note The CPU implementation requires Perfetto. It is not supported when
0059  * Celeritas is built with device support (CUDA/HIP)
0060  */
0061 class ScopedProfiling
0062 {
0063   public:
0064     //!@{
0065     //! \name Type aliases
0066     using Input = ScopedProfilingInput;
0067     //!@}
0068
0069   public:
0070     // Activate profiling with options
0071     explicit inline ScopedProfiling(Input const& input);
0072     // Activate profiling with just a name
0073     explicit inline ScopedProfiling(std::string_view name);
0074
0075     // Deactivate profiling
0076     inline ~ScopedProfiling();
0077
0078     //!@{
0079     //! Prevent copying and moving for RAII class
0080     CELER_DELETE_COPY_MOVE(ScopedProfiling);
0081     //!@}
0082
0083   private:
0084     bool activated_;
0085
0086     void activate(Input const& input) noexcept;
0087     void deactivate() noexcept;
0088 };
0089
0090 //---------------------------------------------------------------------------//
0091 // INLINE DEFINITIONS
0092 //---------------------------------------------------------------------------//
0093 /*!
0094  * Activate device profiling with options.
0095  */
0096 ScopedProfiling::ScopedProfiling(Input const& input)
0097     : activated_{use_profiling()}
0098 {
0099     if (activated_)
0100     {
0101         this->activate(input);
0102     }
0103 }
0104
0105 //---------------------------------------------------------------------------//
0106 /*!
0107  * Activate device profiling with just a name.
0108  */
0109 ScopedProfiling::ScopedProfiling(std::string_view name)
0110     : ScopedProfiling{Input{name}}
0111 {
0112 }
0113
0114 //---------------------------------------------------------------------------//
0115 /*!
0116  * Deactivate a profiling scope.
0117  */
0118 ScopedProfiling::~ScopedProfiling()
0119 {
0120     if (activated_)
0121     {
0122         this->deactivate();
0123     }
0124 }
0125
0126 #if !CELER_USE_DEVICE && !CELERITAS_USE_PERFETTO
0127 inline void ScopedProfiling::activate(Input const&) noexcept
0128 {
0129     CELER_UNREACHABLE;
0130 }
0131 inline void ScopedProfiling::deactivate() noexcept
0132 {
0133     CELER_UNREACHABLE;
0134 }
0135 #endif
0136 //---------------------------------------------------------------------------//
0137 }  // namespace celeritas