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   using clock_type = std::chrono::high_resolution_clock;
0035
0036   /// @brief Construct a new Scoped Timer
0037   ///
0038   /// @param name Identifier for the timed block
0039   /// @param logger Logger instance to use for output
0040   /// @param lvl Logging level for the timing output
0041   explicit ScopedTimer(const std::string& name, const Logger& logger,
0042                        Logging::Level lvl = Logging::Level::INFO);
0043
0044   /// @brief Destructor that logs the execution time
0045   ///
0046   /// Automatically calculates and logs the duration between construction
0047   /// and destruction using the specified logger and level.
0048   ~ScopedTimer();
0049
0050   ScopedTimer(const ScopedTimer&) = delete;
0051   ScopedTimer& operator=(const ScopedTimer&) = delete;
0052   ScopedTimer(ScopedTimer&&) = delete;
0053   ScopedTimer& operator=(ScopedTimer&&) = delete;
0054
0055  private:
0056   std::string m_name;              ///< Identifier for the timed block
0057   Logging::Level m_lvl;            ///< Logging level for output
0058   const Logger* m_logger;          ///< Logger instance for output
0059   clock_type::time_point m_start;  ///< Start time of the timer
0060 };
0061
0062 /// @brief A timer class that measures and averages execution times of multiple samples
0063 ///
0064 /// This class provides functionality to measure execution times of code blocks
0065 /// and calculate statistics (mean, standard deviation) across multiple samples.
0066 /// It uses RAII through the Sample class to automatically record timing
0067 /// information.
0068 class AveragingScopedTimer {
0069  public:
0070   using clock_type = std::chrono::high_resolution_clock;
0071
0072   /// @brief RAII wrapper class for measuring individual timing samples
0073   ///
0074   /// When constructed, starts a timer. When destroyed, automatically records
0075   /// the duration to the parent AveragingScopedTimer.
0076   class Sample {
0077    public:
0078     /// @brief Construct a new sample and start timing
0079     explicit Sample(AveragingScopedTimer& parent);
0080     /// @brief Record the duration when destroyed
0081     ~Sample();
0082     Sample(const Sample&) = delete;
0083     Sample& operator=(const Sample&) = delete;
0084     /// @brief Move constructor that transfers ownership of timing to new sample
0085     Sample(Sample&& /*other*/);
0086     Sample& operator=(Sample&&) = delete;
0087
0088    private:
0089     AveragingScopedTimer* m_parent;
0090     clock_type::time_point m_start;
0091   };
0092
0093   /// @brief Construct a new AveragingScopedTimer
0094   ///
0095   /// @param name Name of the timer for logging
0096   /// @param logger Logger instance to use for output
0097   /// @param lvl Logging level for timing output
0098   explicit AveragingScopedTimer(const std::string& name, const Logger& logger,
0099                                 Logging::Level lvl = Logging::Level::INFO);
0100
0101   /// @brief Destroy the AveragingScopedTimer and log statistics
0102   ///
0103   /// Outputs total duration and per-sample statistics (mean ± stddev) if
0104   /// logging is enabled at the configured level.
0105   ~AveragingScopedTimer();
0106   AveragingScopedTimer(const AveragingScopedTimer&) = delete;
0107   AveragingScopedTimer& operator=(const AveragingScopedTimer&) = delete;
0108   AveragingScopedTimer(AveragingScopedTimer&&) = delete;
0109   AveragingScopedTimer& operator=(AveragingScopedTimer&&) = delete;
0110
0111   /// @brief Create a new timing sample
0112   ///
0113   /// @return Sample RAII wrapper for measuring a single timing sample
0114   Sample sample();
0115
0116   friend class Sample;
0117
0118  private:
0119   /// @brief Add a timing sample to the statistics
0120   ///
0121   /// @param duration Duration of the sample in nanoseconds
0122   void addSample(std::chrono::nanoseconds duration);
0123
0124   double m_sumDuration = 0;  ///< Sum of all sample durations
0125   double m_sumDurationSquared =
0126       0;  ///< Sum of squared durations for stddev calculation
0127   std::size_t m_nSamples = 0;  ///< Number of samples recorded
0128
0129   std::string m_name;      ///< Name of the timer for logging
0130   Logging::Level m_lvl;    ///< Logging level for output
0131   const Logger* m_logger;  ///< Logger instance for output
0132 };
0133 }  // namespace Acts