stopwatch.hpp

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header file is part of module \alib_time of the \aliblong.
///
/// \emoji :copyright: 2013-2024 A-Worx GmbH, Germany.
/// Published under \ref mainpage_license "Boost Software License".
//==================================================================================================
#ifndef HPP_ALIB_TIME_STOPWATCH
#define HPP_ALIB_TIME_STOPWATCH 1
#pragma once
#include "alib/time/ticks.hpp"
 
namespace alib {  namespace time {
 
//==================================================================================================
/// This class encapsulates a system dependent timer value of type \alib{time;Ticks} and provides
/// some simple interface for measuring multiple time spans and providing their sum, average, minimum
/// and maximum.
/// @see
///   For this class, a \ref alibtools_debug_helpers_gdb "pretty printer" for the
///   GNU debugger is provided.
//==================================================================================================
class StopWatch
{
    protected:
 
        /// The current start time.
        Ticks           startTime;
 
        /// The number of samples performed.
        int             cntSamples                                                               =0;
 
        /// The sum of the samples times.
        Ticks::Duration sum;
 
        /// The minimum duration probed.
        Ticks::Duration min;
 
        /// The maximum duration probed.
        Ticks::Duration max;
 
 
    public:
        //==========================================================================================
        ///  Creates a started StopWatch.
        //==========================================================================================
        StopWatch  ()
        : startTime()
        , sum()
        {}
 
    public:
        //==========================================================================================
        /// Provides access to the internal start time.
        /// @return    The start time
        //==========================================================================================
        Ticks&       GetStartTime()
        {
            return startTime;
        }
 
        //==========================================================================================
        /// Sets the start time to now.
        /// This affects both, the reference value for the calculation of this StopWatch's age in
        /// subsequent calls, as well as subsequent sample time spans.
        //==========================================================================================
        void         Start()
        {
            startTime= Ticks::Now();
        }
 
        //==========================================================================================
        ///  Sets the internal value to current system time and clears existing sum and quantity of
        ///  samples.
        //==========================================================================================
        void         Reset()
        {
            sum= Ticks::Duration::FromNanoseconds(0);
            cntSamples= 0;
            min= (std::numeric_limits<Ticks::Duration>::max)();
            max= (std::numeric_limits<Ticks::Duration>::min)();
 
            Start();
        }
 
        //==========================================================================================
        /// Returns the time span between the current system time and the internal start value.
        /// In addition this value is added to the sum of sample times and the sample counter is
        /// increased by one. Lastly the internal reference value is set to now. Therefore, a
        /// subsequent call to this function would measure the time span from this call to this
        /// subsequent call (if the internal start time value was not set differently meanwhile).
        ///
        /// @return The time difference between the current system time and the internal
        ///         reference value.
        //==========================================================================================
        Ticks::Duration Sample()
        {
            Ticks::Duration sample= startTime.Age();
            sum+= sample;
            if( min > sample ) min= sample;
            if( max < sample ) max= sample;
            ++cntSamples;
            startTime= Ticks::Now();
 
            return sample;
        }
 
        //==========================================================================================
        /// Returns the number of calls to #Sample since this instance was created or #Reset was
        /// invoked.
        /// @return    The number of samples.
        //==========================================================================================
        int              GetSampleCnt()                                                        const
        {
            return cntSamples;
        }
 
        //==========================================================================================
        /// Returns the cumulated time of all samples taken since this instance was created or
        /// cleared.
        ///
        /// @return  The cumulated measured time.
        //==========================================================================================
        Ticks::Duration  GetCumulated()                                                        const
        {
            return sum;
        }
 
        //==========================================================================================
        /// Returns the average time of all samples since this instance was created or reset.
        /// If no measurement was performed, the result value will be set to \c 0.
        ///
        /// @return  The cumulated measured time.
        //==========================================================================================
        Ticks::Duration  GetAverage()                                                          const
        {
            return cntSamples== 0 ? Ticks::Duration()
                                  : ( sum / static_cast<int64_t>(cntSamples) );
        }
 
        //==========================================================================================
        /// Returns the minimum duration of all samples since this instance was created or reset.
        /// If no measurement was performed, the value evaluates to the minmum value storable
        /// in type \b Ticks::Duration.
        ///
        /// @return  The minimum measured duration.
        //==========================================================================================
        Ticks::Duration  GetMinimum()                                                          const
        {
            return min;
        }
 
        //==========================================================================================
        /// Returns the maximum duration of all samples since this instance was created or reset.
        /// If no measurement was performed, the value evaluates to the maximum value storable
        /// in type \b Ticks::Duration.
        ///
        /// @return  The maximum measured duration.
        //==========================================================================================
        Ticks::Duration  GetMaximum()                                                          const
        {
            return max;
        }
};
 
} // namespace alib[::time]
 
/// Type alias in namespace \b alib.
using     StopWatch=            time::StopWatch;
 
} // namespace [alib]
 
#endif // HPP_ALIB_TIME_STOPWATCH