stopwatch.hpp

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of the \aliblong. It does not belong to an \alibmod and is
/// included in any \alibbuild.
///
/// Copyright 2013-2026 A-Worx GmbH, Germany.
/// Published under #"mainpage_license".
//==================================================================================================
ALIB_EXPORT namespace alib {  namespace time {
 
//==================================================================================================
/// This class encapsulates a system-dependent timer value of type #"Ticks" and provides
/// some simple interface for measuring multiple time spans and providing their sum, average,
/// minimum and maximum.
/// @see
///   For this class, a #"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, quantity of
    /// samples, minimum, and maximum values.
    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 / 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 minimum value storable
    /// in type #"%^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 #"%^Ticks::Duration".
    ///
    /// @return The maximum measured duration.
    Ticks::Duration  GetMaximum()                                              const { return max; }
};
 
} // namespace alib[::time]
 
/// Type alias in namespace #"%alib".
using     StopWatch=   time::StopWatch;
 
} // namespace [alib]