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 <atomic>
0014 #include <chrono>
0015 #include <cstddef>
0016
0017 namespace Acts {
0018
0019 /// @brief A RAII timer class for measuring execution time of code blocks
0020 ///
0021 /// ScopedTimer provides automatic timing of code blocks using RAII principles.
0022 /// It starts timing when constructed and automatically logs the duration when
0023 /// destroyed. This makes it ideal for measuring execution time of functions
0024 /// or code blocks without manual start/stop calls.
0025 ///
0026 /// Example usage:
0027 /// @code
0028 /// {
0029 ///   ScopedTimer timer("myFunction");
0030 ///   // ... code to measure ...
0031 /// } // Timer automatically logs duration when block ends
0032 /// @endcode
0033 ///
0034 class ScopedTimer {
0035  public:
0036   /// Type alias for high resolution clock used for timing
0037   using clock_type = std::chrono::high_resolution_clock;
0038
0039   /// @brief Construct a new Scoped Timer
0040   ///
0041   /// @param name Identifier for the timed block
0042   /// @param logger Logger instance to use for output
0043   /// @param lvl Logging level for the timing output
0044   explicit ScopedTimer(const std::string& name, const Logger& logger,
0045                        Logging::Level lvl = Logging::Level::INFO);
0046
0047   /// @brief Destructor that logs the execution time
0048   ///
0049   /// Automatically calculates and logs the duration between construction
0050   /// and destruction using the specified logger and level.
0051   ~ScopedTimer();
0052
0053   ScopedTimer(const ScopedTimer&) = delete;
0054   ScopedTimer& operator=(const ScopedTimer&) = delete;
0055   ScopedTimer(ScopedTimer&&) = delete;
0056   ScopedTimer& operator=(ScopedTimer&&) = delete;
0057
0058  private:
0059   std::string m_name;              ///< Identifier for the timed block
0060   Logging::Level m_lvl;            ///< Logging level for output
0061   const Logger* m_logger;          ///< Logger instance for output
0062   clock_type::time_point m_start;  ///< Start time of the timer
0063 };
0064
0065 /// @brief A timer class that measures and averages execution times of multiple samples
0066 ///
0067 /// This class provides functionality to measure execution times of code blocks
0068 /// and calculate statistics (mean, standard deviation) across multiple samples.
0069 /// It uses RAII through the Sample class to automatically record timing
0070 /// information.
0071 class AveragingScopedTimer {
0072  public:
0073   /// Type alias for high resolution clock used for timing measurements
0074   using clock_type = std::chrono::high_resolution_clock;
0075
0076   /// @brief RAII wrapper class for measuring individual timing samples
0077   ///
0078   /// When constructed, starts a timer. When destroyed, automatically records
0079   /// the duration to the parent AveragingScopedTimer.
0080   class Sample {
0081    public:
0082     /// @brief Construct a new sample and start timing
0083     /// @param parent The parent averaging scoped timer to record to
0084     explicit Sample(AveragingScopedTimer& parent);
0085     /// @brief Record the duration when destroyed
0086     ~Sample();
0087     Sample(const Sample&) = delete;
0088     Sample& operator=(const Sample&) = delete;
0089     /// @brief Move constructor that transfers ownership of timing to new sample
0090     Sample(Sample&& /*other*/) noexcept;
0091     Sample& operator=(Sample&&) = delete;
0092
0093    private:
0094     AveragingScopedTimer* m_parent;
0095     clock_type::time_point m_start;
0096   };
0097
0098   /// @brief Construct a new AveragingScopedTimer
0099   ///
0100   /// @param name Name of the timer for logging
0101   /// @param logger Logger instance to use for output
0102   /// @param lvl Logging level for timing output
0103   explicit AveragingScopedTimer(const std::string& name, const Logger& logger,
0104                                 Logging::Level lvl = Logging::Level::INFO);
0105
0106   /// @brief Destroy the AveragingScopedTimer and log statistics
0107   ///
0108   /// Outputs total duration and per-sample statistics (mean ± stddev) if
0109   /// logging is enabled at the configured level.
0110   ~AveragingScopedTimer();
0111   AveragingScopedTimer(const AveragingScopedTimer&) = delete;
0112   AveragingScopedTimer& operator=(const AveragingScopedTimer&) = delete;
0113   AveragingScopedTimer(AveragingScopedTimer&&) = delete;
0114   AveragingScopedTimer& operator=(AveragingScopedTimer&&) = delete;
0115
0116   /// @brief Create a new timing sample
0117   ///
0118   /// @return Sample RAII wrapper for measuring a single timing sample
0119   Sample sample();
0120
0121   friend class Sample;
0122
0123  private:
0124   /// @brief Add a timing sample to the statistics
0125   ///
0126   /// @param duration Duration of the sample in nanoseconds
0127   void addSample(std::chrono::nanoseconds duration);
0128
0129   /// Accumulators are atomic so samples can be recorded concurrently from
0130   /// multiple threads. Relaxed ordering is sufficient since we only need
0131   /// correct aggregate values at the point the dtor reads them.
0132   std::atomic<double> m_sumDuration{0};  ///< Sum of all sample durations
0133   std::atomic<double> m_sumDurationSquared{
0134       0};  ///< Sum of squared durations for stddev calculation
0135   std::atomic<std::size_t> m_nSamples{0};  ///< Number of samples recorded
0136
0137   std::string m_name;      ///< Name of the timer for logging
0138   Logging::Level m_lvl;    ///< Logging level for output
0139   const Logger* m_logger;  ///< Logger instance for output
0140 };
0141 }  // namespace Acts