* Bug #6638 - The profiler output is incorrect by a factor of 1000
[scilab.git] / scilab / modules / functions / help / en_US / profiling / profile.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 - Samuel GOUGEON : Specify unit of CPU time. Presentation of results c improved
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-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="profile">
15     <refnamediv>
16         <refname>profile</refname>
17         <refpurpose>extract execution profiles of a Scilab function</refpurpose>
18     </refnamediv>
19     <refsynopsisdiv>
20         <title>Calling Sequence</title>
21         <synopsis>c=profile(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             <varlistentry>
33                 <term>c</term>
34                 <listitem>
35                     <para>a nx3 matrix containing the execution profiles
36                         <itemizedlist>
37                             <listitem>
38                                 <para>
39                                     <literal>c(i,1)</literal> : number of times the line #i of the function has been run
40                                 </para>
41                             </listitem>
42                             <listitem>
43                                 <para>
44                                     <literal>c(i,2)</literal> : cumulated CPU time [in seconds] spent to run the line #i
45                                 </para>
46                             </listitem>
47                             <listitem>
48                                 <para>
49                                     <literal>c(i,3)</literal> : Measurement of the interpreter effort to execute once the line #i [arbitrary unit]
50                                 </para>
51                             </listitem>
52                         </itemizedlist>
53                     </para>
54                 </listitem>
55             </varlistentry>
56         </variablelist>
57     </refsection>
58     <refsection>
59         <title>Description</title>
60         <para>
61             To use <literal>profile</literal>, profiling instructions need to be added to the Scilab function
62             function by <link linkend="add_profiling">add_profiling</link>.
63         </para>
64         <para>
65             For such function, When such a function is executed the systems counts
66             how many time each line is executed and how may cpu time is spend [in s]for
67             each line execution. These data are stored within the function data
68             structure.  The profile function allows to extract these data and
69             return them in the two first columns of <literal>c</literal>. The <literal>c</literal> third
70             column gives a measure of interpetor effort for one execution of
71             corresponding line. Ith line of <literal>c</literal> corresponds to Ith line of the
72             function (included first)
73         </para>
74         <para>
75             Note that, due to the precision of the processor clock (typically one
76             micro second), some executed lines may appear with 0 cpu time even if
77             total cpu time really spend in their execution is large.
78         </para>
79     </refsection>
80     <refsection>
81         <title>Examples</title>
82         <programlisting role="example"><![CDATA[
83 function x=foo(a, n)
84  x=0;
85  for i=1:n
86    if x<10 then
87      x=x+a
88    else
89      x=x+1
90    end
91  end
92  x=x^2+1
93 endfunction
94
95 add_profiling("foo")
96 foo(0.1,100) //run the function
97 profile(foo) //extract profile information
98  ]]></programlisting>
99     </refsection>
100     <refsection role="see also">
101         <title>See Also</title>
102         <simplelist type="inline">
103             <member>
104                 <link linkend="add_profiling">add_profiling</link>
105             </member>
106             <member>
107                 <link linkend="deff">deff</link>
108             </member>
109             <member>
110                 <link linkend="plotprofile">plotprofile</link>
111             </member>
112             <member>
113                 <link linkend="showprofile">showprofile</link>
114             </member>
115         </simplelist>
116     </refsection>
117 </refentry>