include/GaudiKernel/ChronoEntity.h

0001 /***********************************************************************************\
0002 * (c) Copyright 1998-2019 CERN for the benefit of the LHCb and ATLAS collaborations *
0003 *                                                                                   *
0004 * This software is distributed under the terms of the Apache version 2 licence,     *
0005 * copied verbatim in the file "LICENSE".                                            *
0006 *                                                                                   *
0007 * In applying this licence, CERN does not waive the privileges and immunities       *
0008 * granted to it by virtue of its status as an Intergovernmental Organization        *
0009 * or submit itself to any jurisdiction.                                             *
0010 \***********************************************************************************/
0011 #ifndef GAUDIKERNEL_CHRONOENTITY_H
0012 #define GAUDIKERNEL_CHRONOENTITY_H 1
0013 // ============================================================================
0014 // Include files
0015 // ============================================================================
0016 // GaudiKernel
0017 // ============================================================================
0018 #include "GaudiKernel/IChronoSvc.h"
0019 #include "GaudiKernel/StatEntity.h"
0020 #include "GaudiKernel/Timing.h"
0021 // ============================================================================
0022 /** @class ChronoEntity ChronoEntity.h GaudiKernel/ChronoEntity.h
0023  *
0024  *  a small helper class for
0025  *  implementation of ChronoStatSvc service,
0026  *  It also could be used as some local timer
0027  *
0028  *  @author   Vanya BELYAEV Ivan.Belyaev@itep.ru
0029  *  @date December 1, 1999
0030  */
0031 class GAUDI_API ChronoEntity {
0032 public:
0033   /// default constructor
0034   ChronoEntity() = default;
0035
0036 public:
0037   // ==========================================================================
0038   // The basic Chrono Operations
0039   // ==========================================================================
0040   /// start the current chrono
0041   IChronoSvc::ChronoStatus start();
0042   /// stop the chrono
0043   IChronoSvc::ChronoStatus stop();
0044   // ==========================================================================
0045   /// return the last delta-time of type "type"
0046   IChronoSvc::ChronoTime delta( IChronoSvc::ChronoType type ) const;
0047   /// return the status of chrono
0048   IChronoSvc::ChronoStatus status() const;
0049   // ==========================================================================
0050 public:
0051   // ==========================================================
0052   // Access to Chrono Statistics
0053   // ==========================================================
0054   /// number of chrono measurements
0055   unsigned long nOfMeasurements() const;
0056   // ==========================================================
0057   /// minimal measurement for user time
0058   double uMinimalTime() const;
0059   /// minimal measurement for kernel time
0060   double kMinimalTime() const;
0061   /// minimal measurement for elapsed time
0062   double eMinimalTime() const;
0063   /// maximal measurement for user time
0064   double uMaximalTime() const;
0065   /// maximal measurement for kernel time
0066   double kMaximalTime() const;
0067   /// maximal measurement for elapsed time
0068   double eMaximalTime() const;
0069   /// total user time
0070   double uTotalTime() const;
0071   /// total Kernel time
0072   double kTotalTime() const;
0073   /// total Elapsed time
0074   double eTotalTime() const;
0075   /// total time
0076   double totalTime() const;
0077   /// average Kernel Time
0078   double kMeanTime() const;
0079   /// average User   Time
0080   double uMeanTime() const;
0081   /// average Elapsed   Time
0082   double eMeanTime() const;
0083   /// r.m.s Kernel Time
0084   double kRMSTime() const;
0085   /// r.m.s User Time
0086   double uRMSTime() const;
0087   /// r.m.s Elapsed Time
0088   double eRMSTime() const;
0089   /// error in mean Kernel time
0090   double kMeanErrorTime() const;
0091   /// error in mean User   time
0092   double uMeanErrorTime() const;
0093   /// error in mean Elapsed   time
0094   double eMeanErrorTime() const;
0095   // ==========================================================================
0096 public:
0097   // ==========================================================================
0098   /// comparison operator
0099   friend bool operator<( ChronoEntity const& lhs, ChronoEntity const& rhs ) {
0100     return std::make_tuple( lhs.totalTime(), lhs.m_user, lhs.m_kernel, lhs.m_elapsed ) <
0101            std::make_tuple( rhs.totalTime(), rhs.m_user, rhs.m_kernel, rhs.m_elapsed );
0102   }
0103   // ==========================================================================
0104   /// Compound assignment operator
0105   ChronoEntity& operator+=( const ChronoEntity& entity );
0106   // ==========================================================================
0107 public:
0108   // ==========================================================================
0109   /// print the chrono ;
0110   std::string outputUserTime() const;
0111   /// print the chrono ;
0112   std::string outputSystemTime() const;
0113   /// print the chrono ;
0114   std::string outputElapsedTime() const;
0115   // ==========================================================================
0116 public:
0117   // ==========================================================================
0118   /** print the chrono according the format and units
0119    *  @param fmt  the format string
0120    *  @param unit the unit
0121    *  @return the string representations
0122    *  @see boost::format
0123    */
0124   std::string outputUserTime( std::string_view fmt, System::TimeType unit ) const;
0125   /** print the chrono according the format and units
0126    *  @param fmt  the format string
0127    *  @param unit the unit
0128    *  @return the string representations
0129    *  @see boost::format
0130    */
0131   std::string outputSystemTime( std::string_view fmt, System::TimeType unit ) const;
0132   /** print the chrono according the format and units
0133    *  @param fmt  the format string
0134    *  @param unit the unit
0135    *  @return the string representations
0136    *  @see boost::format
0137    */
0138   std::string outputElapsedTime( std::string_view fmt, System::TimeType unit ) const;
0139   // ==========================================================================
0140   /** print the chrono according the format and units
0141    *
0142    *  The format fields are:
0143    *
0144    *   -# number of entries
0145    *   -# total  time        (in the specified units)
0146    *   -# mean   time        (in the specified units)
0147    *   -# r.m.s. time        (in the specified units)
0148    *   -# error in mean time (in the specified units)
0149    *   -# minimal time       (in the specified units)
0150    *   -# maximal time       (in the specified units)
0151    *
0152    *  @param typ  the chrono type
0153    *  @param fmt  the format string
0154    *  @param unit the unit
0155    *  @return the string representations
0156    *  @see boost::format
0157    */
0158   std::string outputTime( IChronoSvc::ChronoType typ, std::string_view fmt, System::TimeType unit ) const;
0159   // ==========================================================================
0160 protected:
0161   // ==========================================================================
0162   /// format
0163   std::string format( const double total, const double minimal, const double mean, const double rms,
0164                       const double maximal, const unsigned long number ) const;
0165   // ==========================================================================
0166 private:
0167   // ==========================================================================
0168   /// current status of this chrono object;
0169   IChronoSvc::ChronoStatus m_status = IChronoSvc::UNKNOWN;
0170   /// delta process times
0171   System::ProcessTime m_delta;
0172   /// start stamp for current measurement of process times
0173   System::ProcessTime m_start;
0174   /// the actual storage of "user" time
0175   StatEntity m_user; // the actual storage of "user" time
0176   /// the actual storage of "kernel" time
0177   StatEntity m_kernel; // the actual storage of "kernel" time
0178   /// the actual storage of "elapsed" time
0179   StatEntity m_elapsed; // the actual storage of "elapsed" time
0180   /// internal unit used for the system time conversion (microseconds)
0181   static const System::TimeType TimeUnit = System::microSec;
0182   // ==========================================================================
0183 };
0184 // ============================================================================
0185 // return the status of chrono
0186 // ============================================================================
0187 inline IChronoSvc::ChronoStatus ChronoEntity::status() const { return m_status; }
0188 // ============================================================================
0189 // number of chrono measurements
0190 // ============================================================================
0191 inline unsigned long ChronoEntity::nOfMeasurements() const { return m_user.nEntries(); }
0192 // ============================================================================
0193 // minimal measurement for user time
0194 // ============================================================================
0195 inline double ChronoEntity::uMinimalTime() const { return m_user.flagMin(); }
0196 // ============================================================================
0197 // minimal measurement for kernel time
0198 // ============================================================================
0199 inline double ChronoEntity::kMinimalTime() const { return m_kernel.flagMin(); }
0200 // ============================================================================
0201 // minimal measurement for elapsed time
0202 // ============================================================================
0203 inline double ChronoEntity::eMinimalTime() const { return m_elapsed.flagMin(); }
0204 // ============================================================================
0205 // maximal measurement for user time
0206 // ============================================================================
0207 inline double ChronoEntity::uMaximalTime() const { return m_user.flagMax(); }
0208 // ============================================================================
0209 // maximal measurement for kernel time
0210 // ============================================================================
0211 inline double ChronoEntity::kMaximalTime() const { return m_kernel.flagMax(); }
0212 // ============================================================================
0213 // maximal measurement for ellapsed time
0214 // ============================================================================
0215 inline double ChronoEntity::eMaximalTime() const { return m_elapsed.flagMax(); }
0216 // ============================================================================
0217 // total user time
0218 // ============================================================================
0219 inline double ChronoEntity::uTotalTime() const { return m_user.flag(); }
0220 // ============================================================================
0221 // total Kernel time
0222 // ============================================================================
0223 inline double ChronoEntity::kTotalTime() const { return m_kernel.flag(); }
0224 // ============================================================================
0225 // total Elapsed time
0226 // ============================================================================
0227 inline double ChronoEntity::eTotalTime() const { return m_elapsed.flag(); }
0228 // ============================================================================
0229 // total time
0230 // ============================================================================
0231 inline double ChronoEntity::totalTime() const { return uTotalTime() + kTotalTime(); }
0232 // ============================================================================
0233 // average Kernel Time
0234 // ============================================================================
0235 inline double ChronoEntity::kMeanTime() const { return m_kernel.flagMean(); }
0236 // ============================================================================
0237 // average User   Time
0238 // ============================================================================
0239 inline double ChronoEntity::uMeanTime() const { return m_user.flagMean(); }
0240 // ============================================================================
0241 // average Elapsed   Time
0242 // ============================================================================
0243 inline double ChronoEntity::eMeanTime() const { return m_elapsed.flagMean(); }
0244 // ============================================================================
0245 // r.m.s Kernel Time
0246 // ============================================================================
0247 inline double ChronoEntity::kRMSTime() const { return m_kernel.flagRMS(); }
0248 // ============================================================================
0249 // r.m.s User Time
0250 // ============================================================================
0251 inline double ChronoEntity::uRMSTime() const { return m_user.flagRMS(); }
0252 // ============================================================================
0253 // r.m.s Elapsed Time
0254 // ============================================================================
0255 inline double ChronoEntity::eRMSTime() const { return m_elapsed.flagRMS(); }
0256 // ============================================================================
0257 // error in mean Kernel time
0258 // ============================================================================
0259 inline double ChronoEntity::kMeanErrorTime() const { return m_kernel.flagMeanErr(); }
0260 // ============================================================================
0261 // error in mean User   time
0262 // ============================================================================
0263 inline double ChronoEntity::uMeanErrorTime() const { return m_user.flagMeanErr(); }
0264 // ============================================================================
0265 // error in mean Elapsed   time
0266 // ============================================================================
0267 inline double ChronoEntity::eMeanErrorTime() const { return m_elapsed.flagMeanErr(); }
0268 // ============================================================================
0269 // return the last delta-time of type "type"
0270 // ============================================================================
0271 inline IChronoSvc::ChronoTime ChronoEntity::delta( IChronoSvc::ChronoType type ) const {
0272   const IChronoSvc::ChronoTime result = -1;
0273   switch ( type ) {
0274   case IChronoSvc::USER:
0275     return m_delta.userTime<TimeUnit>();
0276   case IChronoSvc::KERNEL:
0277     return m_delta.kernelTime<TimeUnit>();
0278   case IChronoSvc::ELAPSED:
0279     return m_delta.elapsedTime<TimeUnit>();
0280   default:
0281     return result;
0282   }
0283   // cannot reach this point
0284 }
0285 // ============================================================================
0286 /*  print the chrono according the format and units
0287  *  @param fmt  the format string
0288  *  @param unit the unit
0289  *  @return the string representations
0290  *  @see boost::format
0291  */
0292 // ============================================================================
0293 inline std::string ChronoEntity::outputUserTime( std::string_view fmt, System::TimeType unit ) const {
0294   return outputTime( IChronoSvc::USER, fmt, unit );
0295 }
0296 // ============================================================================
0297 /*  print the chrono according the format and units
0298  *  @param fmt  the format string
0299  *  @param unit the unit
0300  *  @return the string representations
0301  *  @see boost::format
0302  */
0303 // ============================================================================
0304 inline std::string ChronoEntity::outputSystemTime( std::string_view fmt, System::TimeType unit ) const {
0305   return outputTime( IChronoSvc::KERNEL, fmt, unit );
0306 }
0307 // ============================================================================
0308 /*  print the chrono according the format and units
0309  *  @param fmt  the format string
0310  *  @param unit the unit
0311  *  @return the string representations
0312  *  @see boost::format
0313  */
0314 // ============================================================================
0315 inline std::string ChronoEntity::outputElapsedTime( std::string_view fmt, System::TimeType unit ) const {
0316   return outputTime( IChronoSvc::ELAPSED, fmt, unit );
0317 }
0318 // ============================================================================
0319 // The END
0320 // ============================================================================
0321 #endif //  GAUDIKERNEL_CHRONOENTITY_H