scilab/modules/functions/help/en_US/profiling/showprofile.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!--
   3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
   4  * Copyright (C) ????-2008 - INRIA
   5  * Copyright (C) 2013 - Scilab Enterprises - Simon MARCHETTO
   6  *
   7  * This file must be used under the terms of the CeCILL.
   8  * This source file is licensed as described in the file COPYING, which
   9  * you should have received as part of this distribution.  The terms
  10  * are also available at
  11  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
  12  *
  13  -->
  14 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="showprofile">
  15     <refnamediv>
  16         <refname>showprofile</refname>
  17         <refpurpose>Outputs the function profiling results to the console</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv>
  20         <title>Calling Sequence</title>
  21         <synopsis>showprofile(fun)</synopsis>
  22     </refsynopsisdiv>
  23     <refsection>
  24         <title>Arguments</title>
  25         <variablelist>
  26             <varlistentry>
  27                 <term>fun</term>
  28                 <listitem>
  29                     <para>a Scilab function</para>
  30                 </listitem>
  31             </varlistentry>
  32         </variablelist>
  33     </refsection>
  34     <refsection>
  35         <title>Description</title>
  36         <para>
  37             To use <literal>showprofile</literal> on a function, the profiling of this function must have been first activated:
  38             <itemizedlist>
  39                 <listitem>
  40                     <para>
  41                         either by using the <link linkend="add_profiling">add_profiling</link> command.
  42                     </para>
  43                 </listitem>
  44                 <listitem>
  45                     <para>
  46                         or if the function has beed defined with the <link linkend="deff">deff</link> command, by setting the optional argument of <link linkend="deff">deff</link> to "p".
  47                     </para>
  48                 </listitem>
  49             </itemizedlist>
  50         </para>
  51         <para>
  52             Once the function has been executed, calling <literal>showprofile</literal> outputs to the console the profiling results.
  53         </para>
  54         <para>For each function line (including the header of function), are printed the following informations, in order:
  55             <itemizedlist>
  56                 <listitem><para>the total number of times the line was called</para></listitem>
  57                 <listitem><para>the total CPU time spent in the line (in seconds)</para></listitem>
  58                 <listitem><para>a measurement of the interpretor effort to interpret the line</para></listitem>
  59                 <listitem><para>the number and source code of the line</para></listitem>
  60             </itemizedlist>
  61         </para>
  62         <para>
  63             An example of output:
  64         </para>
  65         <screen>
  66             |1  |0   |0| 1: function x=fun(n)
  67             |1  |0   |0| 2:   if n > 0 then
  68             |1  |0   |2| 3:     x = 0;
  69             |200|0.01|0| 4:     for k = 1:n
  70             |200|3.99|5| 5:       s = svd(rand(n, n));
  71             |...|... |.| ...
  72         </screen>
  73         <para>
  74             Here we can see that the 5th line of the function has been called 200 times, for a total CPU time of 3.99 seconds (and an effort of 5 to interpret the line).
  75         </para>
  76         <para>
  77             <literal>show_profile</literal> looks like to <link linkend="profile">profile</link>, but <link linkend="profile">profile</link> returns a matrix with the profiling results, while <literal>show_profile</literal> only prints that results to the console.
  78         </para>
  79         <para>
  80             Note: due to the precision limit of CPU time measure (typically one micro second), some executed lines which execution is very fast may appear with a CPU total time of 0.
  81         </para>
  82     </refsection>
  83     <refsection>
  84         <title>Examples</title>
  85         <programlisting role="example"><![CDATA[
  86 // Function to be profiled
  87 function x = foo(n)
  88   if n > 0 then
  89     x = 0;
  90     for k = 1:n
  91       s = svd(rand(n, n));
  92       x = x + s(1);
  93     end
  94   else
  95     x = [];
  96   end
  97 endfunction
  98
  99 // Enables the profiling of the function
 100 add_profiling("foo");
 101
 102 // Executes the function
 103 foo(200);
 104
 105 // Prints the function profiling results to console
 106 showprofile(foo)
 107  ]]></programlisting>
 108     </refsection>
 109     <refsection role="see also">
 110         <title>See Also</title>
 111         <simplelist type="inline">
 112             <member>
 113                 <link linkend="add_profiling">add_profiling</link>
 114             </member>
 115             <member>
 116                 <link linkend="profile">profile</link>
 117             </member>
 118             <member>
 119                 <link linkend="plotprofile">plotprofile</link>
 120             </member>
 121             <member>
 122                 <link linkend="reset_profiling">reset_profiling</link>
 123             </member>
 124         </simplelist>
 125     </refsection>
 126 </refentry>