* Bug #13377 fixed - showprofile() should display lines numbers
[scilab.git] / 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>