Acts/Utilities/ScopedTimer.hpp

0001 // This file is part of the ACTS project.
0002 //
0003 // Copyright (C) 2016 CERN for the benefit of the ACTS project
0004 //
0005 // This Source Code Form is subject to the terms of the Mozilla Public
0006 // License, v. 2.0. If a copy of the MPL was not distributed with this
0007 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
0008
0009 #pragma once
0010
0011 #include "Acts/Utilities/Logger.hpp"
0012
0013 #include <chrono>
0014
0015 namespace Acts {
0016
0017 /// @brief A RAII timer class for measuring execution time of code blocks
0018 ///
0019 /// ScopedTimer provides automatic timing of code blocks using RAII principles.
0020 /// It starts timing when constructed and automatically logs the duration when
0021 /// destroyed. This makes it ideal for measuring execution time of functions
0022 /// or code blocks without manual start/stop calls.
0023 ///
0024 /// Example usage:
0025 /// @code
0026 /// {
0027 ///   ScopedTimer timer("myFunction");
0028 ///   // ... code to measure ...
0029 /// } // Timer automatically logs duration when block ends
0030 /// @endcode
0031 ///
0032 class ScopedTimer {
0033  public:
0034   /// Type alias for high resolution clock used for timing
0035   using clock_type = std::chrono::high_resolution_clock;
0036
0037   /// @brief Construct a new Scoped Timer
0038   ///
0039   /// @param name Identifier for the timed block
0040   /// @param logger Logger instance to use for output
0041   /// @param lvl Logging level for the timing output
0042   explicit ScopedTimer(const std::string& name, const Logger& logger,
0043                        Logging::Level lvl = Logging::Level::INFO);
0044
0045   /// @brief Destructor that logs the execution time
0046   ///
0047   /// Automatically calculates and logs the duration between construction
0048   /// and destruction using the specified logger and level.
0049   ~ScopedTimer();
0050
0051   ScopedTimer(const ScopedTimer&) = delete;
0052   ScopedTimer& operator=(const ScopedTimer&) = delete;
0053   ScopedTimer(ScopedTimer&&) = delete;
0054   ScopedTimer& operator=(ScopedTimer&&) = delete;
0055
0056  private:
0057   std::string m_name;              ///< Identifier for the timed block
0058   Logging::Level m_lvl;            ///< Logging level for output
0059   const Logger* m_logger;          ///< Logger instance for output
0060   clock_type::time_point m_start;  ///< Start time of the timer
0061 };
0062
0063 /// @brief A timer class that measures and averages execution times of multiple samples
0064 ///
0065 /// This class provides functionality to measure execution times of code blocks
0066 /// and calculate statistics (mean, standard deviation) across multiple samples.
0067 /// It uses RAII through the Sample class to automatically record timing
0068 /// information.
0069 class AveragingScopedTimer {
0070  public:
0071   /// Type alias for high resolution clock used for timing measurements
0072   using clock_type = std::chrono::high_resolution_clock;
0073
0074   /// @brief RAII wrapper class for measuring individual timing samples
0075   ///
0076   /// When constructed, starts a timer. When destroyed, automatically records
0077   /// the duration to the parent AveragingScopedTimer.
0078   class Sample {
0079    public:
0080     /// @brief Construct a new sample and start timing
0081     /// @param parent The parent averaging scoped timer to record to
0082     explicit Sample(AveragingScopedTimer& parent);
0083     /// @brief Record the duration when destroyed
0084     ~Sample();
0085     Sample(const Sample&) = delete;
0086     Sample& operator=(const Sample&) = delete;
0087     /// @brief Move constructor that transfers ownership of timing to new sample
0088     Sample(Sample&& /*other*/) noexcept;
0089     Sample& operator=(Sample&&) = delete;
0090
0091    private:
0092     AveragingScopedTimer* m_parent;
0093     clock_type::time_point m_start;
0094   };
0095
0096   /// @brief Construct a new AveragingScopedTimer
0097   ///
0098   /// @param name Name of the timer for logging
0099   /// @param logger Logger instance to use for output
0100   /// @param lvl Logging level for timing output
0101   explicit AveragingScopedTimer(const std::string& name, const Logger& logger,
0102                                 Logging::Level lvl = Logging::Level::INFO);
0103
0104   /// @brief Destroy the AveragingScopedTimer and log statistics
0105   ///
0106   /// Outputs total duration and per-sample statistics (mean ± stddev) if
0107   /// logging is enabled at the configured level.
0108   ~AveragingScopedTimer();
0109   AveragingScopedTimer(const AveragingScopedTimer&) = delete;
0110   AveragingScopedTimer& operator=(const AveragingScopedTimer&) = delete;
0111   AveragingScopedTimer(AveragingScopedTimer&&) = delete;
0112   AveragingScopedTimer& operator=(AveragingScopedTimer&&) = delete;
0113
0114   /// @brief Create a new timing sample
0115   ///
0116   /// @return Sample RAII wrapper for measuring a single timing sample
0117   Sample sample();
0118
0119   friend class Sample;
0120
0121  private:
0122   /// @brief Add a timing sample to the statistics
0123   ///
0124   /// @param duration Duration of the sample in nanoseconds
0125   void addSample(std::chrono::nanoseconds duration);
0126
0127   double m_sumDuration = 0;  ///< Sum of all sample durations
0128   double m_sumDurationSquared =
0129       0;  ///< Sum of squared durations for stddev calculation
0130   std::size_t m_nSamples = 0;  ///< Number of samples recorded
0131
0132   std::string m_name;      ///< Name of the timer for logging
0133   Logging::Level m_lvl;    ///< Logging level for output
0134   const Logger* m_logger;  ///< Logger instance for output
0135 };
0136 }  // namespace Acts