corecel/sys/ScopedProfiling.hh

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