profiler.h

Go to the documentation of this file.

////////////////////////////////////////////////////////////////////////
//
// Copyright (C) 2012-2026 The Octave Project Developers
//
// See the file COPYRIGHT.md in the top-level directory of this
// distribution or <https://octave.org/copyright/>.
//
// This file is part of Octave.
//
// Octave 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 3 of the License, or
// (at your option) any later version.
//
// Octave 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 Octave; see the file COPYING.  If not, see
// <https://www.gnu.org/licenses/>.
//
////////////////////////////////////////////////////////////////////////
 
#if ! defined (octave_profiler_h)
#define octave_profiler_h 1
 
#include "octave-config.h"
 
#include <cstddef>
#include <map>
#include <set>
#include <string>
#include <vector>
 
class octave_value;
 
OCTAVE_BEGIN_NAMESPACE(octave)
 
class OCTINTERP_API profiler
{
public:
 
  // This is a utility class that can be used to call the enter/exit
  // functions in a manner protected from stack unwinding.
  template <typename T> class enter
  {
  public:
 
    enter (profiler& p, const T& t) : m_profiler (p)
    {
      // A profiling block cannot be active if the profiler is not
      m_enabled = m_profiler.enabled ();
 
      if (m_enabled)
        {
          m_fcn = t.profiler_name ();
 
          // NOTE: The test f != "" must be kept to prevent a blank
          // line showing up in profiler statistics.  See bug
          // #39524.  The root cause is that the function name is
          // not set for the recurring readline hook function.
          if (m_fcn == "")
            m_enabled = false;  // Inactive profiling block
          else
            m_profiler.enter_function (m_fcn);
        }
    }
 
    OCTAVE_DISABLE_CONSTRUCT_COPY_MOVE (enter)
 
    ~enter ()
    {
      if (m_enabled)
        m_profiler.exit_function (m_fcn);
    }
 
  private:
 
    profiler& m_profiler;
    std::string m_fcn;
    bool m_enabled;
  };
 
  profiler ();
 
  OCTAVE_DISABLE_COPY_MOVE (profiler)
 
  virtual ~profiler ();
 
  bool enabled () const { return m_enabled; }
  void set_active (bool);
 
  void reset ();
 
  octave_value get_flat () const;
  octave_value get_hierarchical () const;
 
private:
 
  // One entry in the flat profile (i.e., a collection of data for a single
  // function).  This is filled in when building the flat profile from the
  // hierarchical call tree.
  struct stats
  {
  public:
 
    stats ();
 
    OCTAVE_DEFAULT_COPY_MOVE_DELETE (stats)
 
    typedef std::set<octave_idx_type> function_set;
 
    // Convert a function_set list to an Octave array of indices.
    static octave_value function_set_value (const function_set&);
 
    //--------
 
    double m_time;
    std::size_t m_calls;
 
    bool m_recursive;
 
    function_set m_parents;
    function_set m_children;
  };
 
  typedef std::vector<stats> flat_profile;
 
  // Store data for one node in the call-tree of the hierarchical profiler
  // data we collect.
  class tree_node
  {
  public:
 
    tree_node (tree_node *, octave_idx_type);
 
    virtual ~tree_node ();
 
    OCTAVE_DISABLE_CONSTRUCT_COPY_MOVE (tree_node)
 
    void add_time (double dt) { m_time += dt; }
 
    // Enter a child function.  It is created in the list of children if it
    // wasn't already there.  The now-active child node is returned.
    tree_node * enter (octave_idx_type);
 
    // Exit function.  As a sanity-check, it is verified that the currently
    // active function actually is the one handed in here.  Returned is the
    // then-active node, which is our parent.
    tree_node * exit (octave_idx_type);
 
    void build_flat (flat_profile&) const;
 
    // Get the hierarchical profile for this node and its children.  If total
    // is set, accumulate total time of the subtree in that variable as
    // additional return value.
    octave_value get_hierarchical (double *total = nullptr) const;
 
  private:
 
    tree_node *m_parent;
    octave_idx_type m_fcn_id;
 
    typedef std::map<octave_idx_type, tree_node *> child_map;
    child_map m_children;
 
    // This is only time spent *directly* on this level, excluding children!
    double m_time;
 
    std::size_t m_calls;
  };
 
  // These are private as only the unwind-protecting inner class enter
  // should be allowed to call them.
  void enter_function (const std::string&);
  void exit_function (const std::string&);
 
  // Query a timestamp, used for timing calls (obviously).
  // This is not static because in the future, maybe we want a flag
  // in the profiler or something to choose between cputime, wall-time,
  // user-time, system-time, ...
  double query_time () const;
 
  // Add the time elapsed since last_time to the function we're currently in.
  // This is called from two different positions, thus it is useful to have
  // it as a separate function.
  void add_current_time ();
 
  //--------
 
  // Each function we see in the profiler is given a unique index (which
  // simply counts starting from 1).  We thus have to map profiler-names to
  // those indices.  For all other stuff, we identify functions by their
  // index.
 
  typedef std::vector<std::string> function_set;
  typedef std::map<std::string, octave_idx_type> fcn_index_map;
 
  function_set m_known_functions;
  fcn_index_map m_fcn_index;
 
  bool m_enabled;
 
  tree_node *m_call_tree;
  tree_node *m_active_fcn;
 
  // Store last timestamp we had, when the currently active function was
  // called.
  double m_last_time;
};
 
OCTAVE_END_NAMESPACE(octave)
 
#endif