stopwatch.h

Go to the documentation of this file.

/*
 *  stopwatch.h
 *
 *  This file is part of NEST.
 *
 *  Copyright (C) 2004 The NEST Initiative
 *
 *  NEST is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  NEST is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with NEST.  If not, see <http://www.gnu.org/licenses/>.
 *
 */
 
#ifndef STOPWATCH_H
#define STOPWATCH_H
 
// C includes:
#include <sys/time.h>
 
// C++ includes:
#include <chrono>
#include <iostream>
#include <vector>
 
// Includes from libnestutil:
#include "dictionary.h"
 
// Includes from nestkernel:
#include "exceptions.h"
 
namespace nest
{
 
#ifdef TIMER_DETAILED
constexpr bool use_detailed_timers = true;
#else
constexpr bool use_detailed_timers = false;
#endif
 
#ifdef THREADED_TIMERS
constexpr bool use_threaded_timers = true;
#else
constexpr bool use_threaded_timers = false;
#endif
 
enum class StopwatchGranularity
{
  Normal,   
  Detailed  
};
 
enum class StopwatchParallelism
{
  MasterOnly,  
  Threaded     
};
 
/********************************************************************************
 * Stopwatch                                                                    *
 *   Accumulates time between start and stop, and provides the elapsed time     *
 *   with different time units. Either runs multi-threaded or only on master.   *
 *                                                                              *
 *   Usage example:                                                             *
 *     Stopwatch< StopwatchGranularity::Normal,                                 *
 *                StopwatchParallelism::MasterOnly > x;                         *
 *     x.start();                                                               *
 *     // ... do computations for 15.34 sec                                     *
 *     x.stop(); // only pauses stopwatch                                       *
 *     x.print("Time needed "); // > Time needed 15.34 sec.                     *
 *     x.start(); // resumes stopwatch                                          *
 *     // ... next computations for 11.22 sec                                   *
 *     x.stop();                                                                *
 *     x.print("Time needed "); // > Time needed 26,56 sec.                     *
 *     x.reset(); // reset to default values                                    *
 *     x.start(); // starts the stopwatch from 0                                *
 *     // ... computation 5.7 sec                                               *
 *     x.print("Time "); // > Time 5.7 sec.                                     *
 *     // ^ intermediate timing without stopping the stopwatch                  *
 *     // ... more computations 1.7643 min                                      *
 *     x.stop();                                                                *
 *     x.print("Time needed ", timeunit_t::MINUTES, std::cerr);                 *
 *     // > Time needed 1,8593 min. (on cerr)                                   *
 *     // other units and output streams possible                               *
 ********************************************************************************/
 
namespace timers
{
 
enum class timeunit_t : size_t
{
  NANOSEC = 1,
  MICROSEC = NANOSEC * 1000,
  MILLISEC = MICROSEC * 1000,
  SECONDS = MILLISEC * 1000,
  MINUTES = SECONDS * 60,
  HOURS = MINUTES * 60,
  DAYS = HOURS * 24
};
 
template < clockid_t clock_type >
class StopwatchTimer
{
public:
  StopwatchTimer()
  {
    reset();
  }
 
  void start();
 
  void stop();
 
  double elapsed( timeunit_t timeunit = timeunit_t::SECONDS ) const;
 
  void reset();
 
  void
  print( const std::string& msg = "", timeunit_t timeunit = timeunit_t::SECONDS, std::ostream& os = std::cout ) const;
 
private:
  size_t beg_;           
  size_t end_;           
  size_t prev_elapsed_;  
  bool is_running_;      
 
  static size_t get_current_time();
};
 
template < clockid_t clock_type >
inline void
StopwatchTimer< clock_type >::start()
{
  if ( not is_running_ )
  {
    prev_elapsed_ += end_ - beg_;      // store prev. time, if we resume
    end_ = beg_ = get_current_time();  // invariant: end_ >= beg_
    is_running_ = true;                // we start running
  }
}
 
template < clockid_t clock_type >
inline void
StopwatchTimer< clock_type >::stop()
{
  if ( is_running_ )
  {
    end_ = get_current_time();  // invariant: end_ >= beg_
    is_running_ = false;        // we stopped running
  }
}
 
template < clockid_t clock_type >
inline double
StopwatchTimer< clock_type >::elapsed( timeunit_t timeunit ) const
{
  size_t time_elapsed;
  if ( is_running_ )
  {
    // get intermediate elapsed time; do not change end_, to be const
    time_elapsed = get_current_time() - beg_ + prev_elapsed_;
  }
  else
  {
    // stopped before, get time of current measurement + last measurements
    time_elapsed = end_ - beg_ + prev_elapsed_;
  }
  return static_cast< double >( time_elapsed ) / static_cast< double >( timeunit );
}
 
template < clockid_t clock_type >
inline void
StopwatchTimer< clock_type >::reset()
{
  beg_ = 0;  // invariant: end_ >= beg_
  end_ = 0;
  prev_elapsed_ = 0;    // erase all prev. measurements
  is_running_ = false;  // of course not running.
}
 
template < clockid_t clock_type >
inline void
StopwatchTimer< clock_type >::print( const std::string& msg, timeunit_t timeunit, std::ostream& os ) const
{
  os << msg << elapsed( timeunit );
  switch ( timeunit )
  {
  case timeunit_t::NANOSEC:
    os << " nanosec.";
  case timeunit_t::MICROSEC:
    os << " microsec.";
    break;
  case timeunit_t::MILLISEC:
    os << " millisec.";
    break;
  case timeunit_t::SECONDS:
    os << " sec.";
    break;
  case timeunit_t::MINUTES:
    os << " min.";
    break;
  case timeunit_t::HOURS:
    os << " h.";
    break;
  case timeunit_t::DAYS:
    os << " days.";
    break;
  default:
    throw BadParameter( "Invalid timeunit provided to stopwatch." );
  }
  os << std::endl;
}
 
template < clockid_t clock_type >
inline size_t
StopwatchTimer< clock_type >::get_current_time()
{
  timespec now;
  clock_gettime( clock_type, &now );
  return now.tv_nsec + now.tv_sec * static_cast< long >( timeunit_t::SECONDS );
}
 
template < clockid_t clock_type >
inline std::ostream&
operator<<( std::ostream& os, const StopwatchTimer< clock_type >& stopwatch )
{
  stopwatch.print( "", timeunit_t::SECONDS, os );
  return os;
}
 
}  // namespace timers
 
struct NoOpStopwatch
{
  constexpr void
  start() noexcept
  {
  }
  constexpr void
  stop() noexcept
  {
  }
  constexpr void
  reset() noexcept
  {
  }
  constexpr bool
  is_running_() const noexcept
  {
    return false;
  }
  void
  print( const std::string&, timers::timeunit_t, std::ostream& ) const
  {
  }
  constexpr double
  elapsed() const noexcept
  {
    return std::numeric_limits< double >().quiet_NaN();
  }
  constexpr double
  elapsed( timers::timeunit_t ) const noexcept
  {
    return std::numeric_limits< double >().quiet_NaN();
  }
};
 
template < StopwatchGranularity detailed_timer, StopwatchParallelism threaded_timer >
class Stopwatch
{
  static constexpr bool enable_timer = detailed_timer == StopwatchGranularity::Normal or use_detailed_timers;
  static constexpr bool use_timer_array = threaded_timer == StopwatchParallelism::Threaded and use_threaded_timers;
 
  // Define StopwatchTimerType< ClockType > depending on timer compilation switches
  template < clockid_t ClockType >
  using InternalTimerType = std::conditional_t< use_timer_array,
    std::vector< timers::StopwatchTimer< ClockType > >,
    timers::StopwatchTimer< ClockType > >;
  // If enabled, use InternalTimerType, otherwise use NoOpStopwatch.
  template < clockid_t ClockType >
  using StopwatchTimerType = std::conditional_t< enable_timer, InternalTimerType< ClockType >, NoOpStopwatch >;
 
public:
  void start();
 
  void stop();
 
  double elapsed( timers::timeunit_t timeunit = timers::timeunit_t::SECONDS ) const;
 
  void reset();
 
  void print( const std::string& msg = "",
    timers::timeunit_t timeunit = timers::timeunit_t::SECONDS,
    std::ostream& os = std::cout ) const;
 
  void get_status( Dictionary& d, const std::string& walltime_name, const std::string& cputime_name ) const;
 
private:
  bool is_running_() const;
 
  // We use a monotonic timer to make sure the stopwatch is not influenced by time jumps (e.g. summer/winter time).
  // [[no_unique_address]] ensures these take up 0 bytes in case the NoOp version is used.
  [[no_unique_address]] StopwatchTimerType< CLOCK_MONOTONIC > walltime_timer_;
  [[no_unique_address]] StopwatchTimerType< CLOCK_THREAD_CPUTIME_ID > cputime_timer_;
};
 
} /* namespace nest */
#endif /* STOPWATCH_H */