* Bug #12087 fixed - profile help page did not mention add_profiling.
[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  *
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at
10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
11  *
12  -->
13 <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">
14     <refnamediv>
15         <refname>profile</refname>
16         <refpurpose>extract execution profiles of a Scilab function</refpurpose>
17     </refnamediv>
18     <refsynopsisdiv>
19         <title>Calling Sequence</title>
20         <synopsis>c=profile(fun)</synopsis>
21     </refsynopsisdiv>
22     <refsection>
23         <title>Arguments</title>
24         <variablelist>
25             <varlistentry>
26                 <term>fun</term>
27                 <listitem>
28                     <para>a Scilab function</para>
29                 </listitem>
30             </varlistentry>
31             <varlistentry>
32                 <term>c</term>
33                 <listitem>
34                     <para>a nx3 matrix containig the execution profiles</para>
35                 </listitem>
36             </varlistentry>
37         </variablelist>
38     </refsection>
39     <refsection>
40         <title>Description</title>
41         <para>
42             To use <literal>profile</literal>, profiling instructions need to be added to the Scilab function
43             function by <link linkend="add_profiling">add_profiling</link>.
44         </para>
45         <para>
46             For such function, When such a function is executed the systems counts
47             how many time each line is executed and how may cpu time is spend for
48             each line execution. These data are stored within the function data
49             structure.  The profile function allows to extract these data and
50             return them in the two first columns of <literal>c</literal>. The <literal>c</literal> third
51             column gives a measure of interpetor effort for one execution of
52             corresponding line. Ith line of <literal>c</literal> corresponds to Ith line of the
53             function (included first)
54         </para>
55         <para>
56             Note that, due to the precision of the processor clock (typically one
57             micro second), some executed lines may appear with 0 cpu time even if
58             total cpu time really spend in their execution is large.
59         </para>
60     </refsection>
61     <refsection>
62         <title>Examples</title>
63         <programlisting role="example"><![CDATA[
64 function x=foo(a, n)
65  x=0;
66  for i=1:n
67    if x<10 then
68      x=x+a
69    else
70      x=x+1
71    end
72  end
73  x=x^2+1
74 endfunction
75
76 add_profiling("foo")
77 foo(0.1,100) //run the function
78 profile(foo) //extract profile information
79  ]]></programlisting>
80     </refsection>
81     <refsection role="see also">
82         <title>See Also</title>
83         <simplelist type="inline">
84             <member>
85                 <link linkend="add_profiling">add_profiling</link>
86             </member>
87             <member>
88                 <link linkend="deff">deff</link>
89             </member>
90             <member>
91                 <link linkend="plotprofile">plotprofile</link>
92             </member>
93             <member>
94                 <link linkend="showprofile">showprofile</link>
95             </member>
96         </simplelist>
97     </refsection>
98 </refentry>