timer.h

Go to the documentation of this file.

// -----------------------------------------------------------------------------
//
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
// Copyright (C) 1998 - 2026 by the deal.II authors
//
// This file is part of the deal.II library.
//
// Detailed license information governing the source code and contributions
// can be found in LICENSE.md and CONTRIBUTING.md at the top level directory.
//
// -----------------------------------------------------------------------------
 
#ifndef dealii_timer_h
#define dealii_timer_h
 
#include <deal.II/base/config.h>
 
#include <deal.II/base/conditional_ostream.h>
#include <deal.II/base/mpi.h>
#include <deal.II/base/mutex.h>
 
#include <chrono>
#include <list>
#include <map>
#include <optional>
#include <string>
 
DEAL_II_NAMESPACE_OPEN

struct CPUClock
{
  using duration = std::chrono::microseconds;

  using rep = duration::rep;

  using period = duration::period;

  using time_point = std::chrono::time_point<CPUClock, duration>;

  static const bool is_steady = true;

  static time_point
  now() noexcept;
};

class Timer
{
public:
  Timer();

  Timer(const MPI_Comm mpi_communicator, const bool sync_lap_times = false);

  const Utilities::MPI::MinMaxAvg &
  get_last_lap_wall_time_data() const;

  const Utilities::MPI::MinMaxAvg &
  get_accumulated_wall_time_data() const;

  template <typename StreamType>
  void
  print_last_lap_wall_time_data(StreamType &stream) const;

  template <typename StreamType>
  void
  print_accumulated_wall_time_data(StreamType &stream) const;

  void
  start();

  void
  stop();

  void
  reset();

  void
  restart();

  bool
  is_running() const;

  double
  wall_time() const;

  double
  last_wall_time() const;

  double
  cpu_time() const;

  double
  last_cpu_time() const;

  unsigned int
  n_laps() const;
 
private:
  template <class clock_type_>
  struct ClockMeasurements
  {
    using clock_type = clock_type_;

    using time_point_type = typename clock_type::time_point;

    using duration_type = typename clock_type::duration;

    time_point_type current_lap_start_time;

    duration_type accumulated_time;

    duration_type last_lap_time;

    ClockMeasurements();

    void
    reset();
  };

  using wall_clock_type = std::chrono::steady_clock;

  using cpu_clock_type = CPUClock;

  mutable ClockMeasurements<wall_clock_type> wall_times;

  mutable ClockMeasurements<cpu_clock_type> cpu_times;

  bool running;

  void
  synchronize_and_update() const;

  mutable bool is_synchronized;

  MPI_Comm mpi_communicator;

  bool sync_lap_times;

  mutable Utilities::MPI::MinMaxAvg last_lap_wall_time_data;

  mutable Utilities::MPI::MinMaxAvg accumulated_wall_time_data;

  unsigned int n_timed_laps;

  mutable Threads::Mutex mutex;
};
 
 
 
// TODO: The following class is not thread-safe
class TimerOutput
{
public:
  class Scope
  {
  public:
    Scope(::TimerOutput &timer_, const std::string &section_name);

    ~Scope();

    void
    stop();
 
  private:
    ::TimerOutput &timer;

    const std::string section_name;

    bool in;
  };

  enum OutputFrequency
  {
    every_call,
    summary,
    every_call_and_summary,
    never
  };

  enum OutputData
  {
    total_cpu_time,
    total_wall_time,
    n_calls
  };

  enum OutputType
  {
    cpu_times,
    wall_times,
    cpu_and_wall_times,
    cpu_and_wall_times_grouped
  };

  TimerOutput(std::ostream         &stream,
              const OutputFrequency output_frequency,
              const OutputType      output_type);

  TimerOutput(ConditionalOStream   &stream,
              const OutputFrequency output_frequency,
              const OutputType      output_type);

  TimerOutput(const MPI_Comm        mpi_communicator_timing,
              std::ostream         &stream,
              const OutputFrequency output_frequency,
              const OutputType      output_type);

  TimerOutput(const MPI_Comm        mpi_communicator_timing,
              ConditionalOStream   &stream,
              const OutputFrequency output_frequency,
              const OutputType      output_type);

  ~TimerOutput();

  void
  enter_subsection(const std::string &section_name);

  void
  leave_subsection(const std::string &section_name = "");

  std::map<std::string, double>
  get_summary_data(const OutputData kind) const;

  void
  print_summary() const;

  void
  print_wall_time_statistics(const MPI_Comm mpi_communicator_statistics,
                             const double   print_quantile = 0.) const;

  void
  disable_output();

  void
  enable_output();

  void
  reset();
 
private:
  OutputFrequency output_frequency;

  OutputType output_type;
 

  Timer timer_all;

  std::map<std::string, Timer> sections;

  ConditionalOStream out_stream;

  bool output_is_enabled;

  std::list<std::string> active_sections;

  std::optional<MPI_Comm> mpi_communicator_timing;

  Threads::Mutex mutex;
};
 
 
 
/* ---------------- inline functions ----------------- */
 
 
inline void
Timer::restart()
{
  reset();
  start();
}
 
 
 
inline const Utilities::MPI::MinMaxAvg &
Timer::get_last_lap_wall_time_data() const
{
  if (running == false)
    synchronize_and_update();
 
  return last_lap_wall_time_data;
}
 
 
 
inline const Utilities::MPI::MinMaxAvg &
Timer::get_accumulated_wall_time_data() const
{
  if (running == false)
    synchronize_and_update();
 
  return accumulated_wall_time_data;
}
 
 
 
template <typename StreamType>
inline void
Timer::print_last_lap_wall_time_data(StreamType &stream) const
{
  const Utilities::MPI::MinMaxAvg &statistic = get_last_lap_wall_time_data();
  stream << statistic.max << " wall,"
         << " max @" << statistic.max_index << ", min=" << statistic.min << " @"
         << statistic.min_index << ", avg=" << statistic.avg << std::endl;
}
 
 
 
template <typename StreamType>
inline void
Timer::print_accumulated_wall_time_data(StreamType &stream) const
{
  const Utilities::MPI::MinMaxAvg &statistic = get_accumulated_wall_time_data();
  stream << statistic.max << " wall,"
         << " max @" << statistic.max_index << ", min=" << statistic.min << " @"
         << statistic.min_index << ", avg=" << statistic.avg << std::endl;
}
 
 
 
inline TimerOutput::Scope::Scope(::TimerOutput &timer_,
                                 const std::string   &section_name_)
  : timer(timer_)
  , section_name(section_name_)
  , in(true)
{
  timer.enter_subsection(section_name);
}
 
 
 
inline void
TimerOutput::Scope::stop()
{
  if (!in)
    return;
  in = false;
 
  timer.leave_subsection(section_name);
}
 
 
DEAL_II_NAMESPACE_CLOSE
 
#endif