octave_packages/m/general/profile.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  {Command} {} profile on
  21 ## @deftypefnx {Command} {} profile off
  22 ## @deftypefnx {Command} {} profile resume
  23 ## @deftypefnx {Command} {} profile clear
  24 ## @deftypefnx {Function File} {@var{S} =} profile ('status')
  25 ## @deftypefnx {Function File} {@var{T} =} profile ('info')
  26 ## Control the built-in profiler.
  27 ##
  28 ## @table @code
  29 ## @item profile on
  30 ## Start the profiler, clearing all previously collected data if there
  31 ## is any.
  32 ##
  33 ## @item profile off
  34 ## Stop profiling.  The collected data can later be retrieved and examined
  35 ## with calls like @code{S = profile ('info')}.
  36 ##
  37 ## @item profile clear
  38 ## Clear all collected profiler data.
  39 ##
  40 ## @item profile resume
  41 ## Restart profiling without cleaning up the old data and instead
  42 ## all newly collected statistics are added to the already existing ones.
  43 ##
  44 ## @item @var{S} = profile ('status')
  45 ## Return a structure filled with certain information about the current status
  46 ## of the profiler.  At the moment, the only field is @code{ProfilerStatus}
  47 ## which is either 'on' or 'off'.
  48 ##
  49 ## @item @var{T} = profile ('info')
  50 ## Return the collected profiling statistics in the structure @var{T}.
  51 ## The flat profile is returned in the field @code{FunctionTable} which is an
  52 ## array of structures, each entry corresponding to a function which was called
  53 ## and for which profiling statistics are present.  Furthermore, the field
  54 ## @code{Hierarchical} contains the hierarchical call-tree.  Each node
  55 ## has an index into the @code{FunctionTable} identifying the function it
  56 ## corresponds to as well as data fields for number of calls and time spent
  57 ## at this level in the call-tree.
  58 ## @seealso{profshow, profexplore}
  59 ## @end table
  60 ## @end deftypefn
  61
  62 ## Built-in profiler.
  63 ## Author: Daniel Kraft <d@domob.eu>
  64
  65 function retval = profile (option)
  66
  67   if (nargin != 1)
  68     print_usage ();
  69   endif
  70
  71   switch (option)
  72     case 'on'
  73       __profiler_reset__ ();
  74       __profiler_enable__ (true);
  75
  76     case 'off'
  77       __profiler_enable__ (false);
  78
  79     case 'clear'
  80       __profiler_reset__ ();
  81
  82     case 'resume'
  83       __profiler_enable__ (true);
  84
  85     case 'status'
  86       enabled = __profiler_enable__ ();
  87       if (enabled)
  88         enabled = 'on';
  89       else
  90         enabled = 'off';
  91       endif
  92       retval = struct ('ProfilerStatus', enabled);
  93
  94     case 'info'
  95       [flat, tree] = __profiler_data__ ();
  96       retval = struct ('FunctionTable', flat, 'Hierarchical', tree);
  97
  98     otherwise
  99       warning ("profile: Unrecognized option '%s'", option);
 100       print_usage ();
 101
 102   endswitch
 103
 104 endfunction
 105
 106
 107 %!demo
 108 %! profile ('on');
 109 %! A = rand (100);
 110 %! B = expm (A);
 111 %! profile ('off');
 112 %! profile ('resume');
 113 %! C = sqrtm (A);
 114 %! profile ('off');
 115 %! T = profile ('info');
 116 %! profshow (T);
 117
 118 %!error profile ();
 119 %!error profile ('on', 2);
 120
 121 %!test
 122 %! on_struct.ProfilerStatus = "on";
 123 %! off_struct.ProfilerStatus = "off";
 124 %! profile ('on');
 125 %! result = logm (rand (200) + 10 * eye (200));
 126 %! assert (profile ('status'), on_struct);
 127 %! profile ('off');
 128 %! assert (profile ('status'), off_struct);
 129 %! profile ('resume');
 130 %! result = logm (rand (200) + 10 * eye (200));
 131 %! profile ('off');
 132 %! assert (profile ('status'), off_struct);
 133 %! info = profile ('info');
 134 %! assert (isstruct (info));
 135 %! assert (size (info), [1, 1]);
 136 %! assert (fieldnames (info), {'FunctionTable'; 'Hierarchical'});
 137 %! ftbl = info.FunctionTable;
 138 %! assert (fieldnames (ftbl), {'FunctionName'; 'TotalTime'; 'NumCalls'; 'IsRecursive'; 'Parents'; 'Children'});
 139 %! hier = info.Hierarchical;
 140 %! assert (fieldnames (hier), {'Index'; 'SelfTime'; 'TotalTime'; 'NumCalls'; 'Children'});
 141 %! profile ('clear');
 142 %! info = profile ('info');
 143 %! assert (isstruct (info));
 144 %! assert (size (info), [1, 1]);
 145 %! assert (fieldnames (info), {'FunctionTable'; 'Hierarchical'});
 146 %! ftbl = info.FunctionTable;
 147 %! assert (size (ftbl), [0, 1]);
 148 %! assert (fieldnames (ftbl), {'FunctionName'; 'TotalTime'; 'NumCalls'; 'IsRecursive'; 'Parents'; 'Children'});
 149 %! hier = info.Hierarchical;
 150 %! assert (size (hier), [0, 1]);
 151 %! assert (fieldnames (hier), {'Index'; 'SelfTime'; 'NumCalls'; 'Children'});