octave_packages/m/general/profexplore.m

   1 ## Copyright (C) 2012 Daniel Kraft
   2 ##
   3 ## This file is part of Octave.
   4 ##
   5 ## Octave is free software; you can redistribute it and/or modify it
   6 ## under the terms of the GNU General Public License as published by
   7 ## the Free Software Foundation; either version 3 of the License, or (at
   8 ## your option) any later version.
   9 ##
  10 ## Octave is distributed in the hope that it will be useful, but
  11 ## WITHOUT ANY WARRANTY; without even the implied warranty of
  12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 ## General Public License for more details.
  14 ##
  15 ## You should have received a copy of the GNU General Public License
  16 ## along with Octave; see the file COPYING.  If not, see
  17 ## <http://www.gnu.org/licenses/>.
  18
  19 ## -*- texinfo -*-
  20 ## @deftypefn {Function File} {} profexplore (@var{data})
  21 ## Interactively explore hierarchical profiler output.
  22 ##
  23 ## Assuming @var{data} is the structure with profile data returned by
  24 ## @code{profile ('info')}, this command opens an interactive prompt
  25 ## that can be used to explore the call-tree.  Type @kbd{help} to get a list
  26 ## of possible commands.
  27 ## @seealso{profile, profshow}
  28 ## @end deftypefn
  29
  30 ## Built-in profiler.
  31 ## Author: Daniel Kraft <d@domob.eu>
  32
  33 function profexplore (data)
  34
  35   if (nargin ~= 1)
  36     print_usage ();
  37   endif
  38
  39   ## The actual work is done by a recursive worker function, since that
  40   ## is an easy way to traverse the tree datastructure.  Here, we just check
  41   ## the arguments (already done) and give over to it.
  42
  43   __profexplore_worker (data.FunctionTable, data.Hierarchical, "Top\n", "  ");
  44
  45 endfunction
  46
  47 ## This is the worker function.  tree is the current subtree we want to
  48 ## display / explore.  parents is a string containing the already 'rendered'
  49 ## data for the parents which is displayed on top of the list of current
  50 ## children.  prefix is the prefix to add to each line rendered; this
  51 ## is just a string of spaces to get indentation right.
  52 ##
  53 ## Returning 0 indicates that the user requested to totally exit the
  54 ## explorer, thus also all higher levels should exit immediately.  An integer
  55 ## greater zero indicates to exit that many levels since the user wants to go
  56 ## up (but not necessarily quit).
  57
  58 function rv = __profexplore_worker (fcn_table, tree, parents, prefix)
  59
  60   ## Sort children by total time.
  61   times = -[ tree.TotalTime ];
  62   [~, p] = sort (times);
  63   tree = tree(p);
  64
  65   while (true)
  66
  67     printf ("\n%s", parents);
  68     strings = cell (length (tree), 1);
  69     for i = 1 : length (tree)
  70       strings{i} = sprintf ("%s: %d calls, %.3f total, %.3f self", ...
  71                             fcn_table(tree(i).Index).FunctionName, ...
  72                             tree(i).NumCalls, ...
  73                             tree(i).TotalTime, tree(i).SelfTime);
  74       printf ("%s%d) %s\n", prefix, i, strings{i});
  75     endfor
  76     printf ("\n");
  77
  78     cmd = input ("profexplore> ", "s");
  79     option = fix (str2double (cmd));
  80
  81     if (strcmp (cmd, "exit"))
  82       rv = 0;
  83       return;
  84     elseif (strcmp (cmd, "help"))
  85       printf ("\nCommands for profile explorer:\n\n");
  86       printf ("exit   Return to Octave prompt.\n");
  87       printf ("help   Display this help message.\n");
  88       printf ("up [N] Go up N levels, where N is an integer.  Default is 1.\n");
  89       printf ("N      Go down a level into option N.\n");
  90     elseif (~isnan (option))
  91       if (option < 1 || option > length (tree))
  92         printf ("The chosen option is out of range!\n");
  93       else
  94         newParents = sprintf ("%s%s%s\n", parents, prefix, strings{option});
  95         newPrefix = sprintf ("%s  ", prefix);
  96
  97         rv = __profexplore_worker (fcn_table, tree(option).Children, ...
  98                                    newParents, newPrefix);
  99
 100         if (rv == 0)
 101           return;
 102         elseif (rv > 1)
 103           rv = rv - 1;
 104           return;
 105         else
 106           assert (rv == 1);
 107           ## It was requested to return to this level, so just stay.
 108         endif
 109       endif
 110     elseif (length (cmd) >= 2 && strcmp (substr (cmd, 1, 2), "up"))
 111       if (length (cmd) == 2)
 112         rv = 1;
 113         return;
 114       endif
 115
 116       if (length (cmd) > 3 && cmd(3) == ' ')
 117         opt = fix (str2double (substr (cmd, 3)));
 118         if (~isnan (opt) && opt > 0)
 119           rv = opt;
 120           return;
 121         endif
 122       endif
 123
 124       printf ("Invalid 'up' command.  Type 'help' for further");
 125       printf (" information.\n");
 126     else
 127       printf ("Unrecognized input.  Type 'help' to get a list of possible");
 128       printf (" commands.\n");
 129     endif
 130
 131   endwhile
 132 endfunction