da4671f6ac81f86cb3f6b0286f63829ca9475a05
[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> the Scilab function must have been prepared for
43             profiling (see exec).
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 //define function and prepare it for profiling
65 deff('x=foo(n)',['if n==0 then'
66                  '  x=[]'
67                  'else'
68                  '  x=0'
69                  '  for k=1:n'
70                  '    s=svd(rand(n+10,n+10))'
71                  '    x=x+s(1)'
72                  '  end'
73                  'end'],'p')
74
75 //call the function
76 foo(10)
77
78 //get execution profiles
79 profile(foo)
80
81 //call the function
82 foo(20)
83 profile(foo) //execution profiles are cumulated
84  ]]></programlisting>
85     </refsection>
86     <refsection role="see also">
87         <title>See Also</title>
88         <simplelist type="inline">
89             <member>
90                 <link linkend="exec">exec</link>
91             </member>
92             <member>
93                 <link linkend="deff">deff</link>
94             </member>
95             <member>
96                 <link linkend="plotprofile">plotprofile</link>
97             </member>
98             <member>
99                 <link linkend="showprofile">showprofile</link>
100             </member>
101         </simplelist>
102     </refsection>
103 </refentry>