← Back to branch summary

~rdoering/ubuntu/karmic/erlang/fix-535090

« back to all changes in this revision

Viewing changes to lib/tools/doc/src/eprof.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sergei Golovan
  • Date: 2009-02-15 16:42:52 UTC
  • mfrom: (3.1.2 squeeze)
  • Revision ID: james.westby@ubuntu.com-20090215164252-q5x4rcf8a5pbesb1
Tags: 1:12.b.5-dfsg-2
Upload to unstable after lenny is released.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/tools/doc/src/eprof.xml
 
1
<?xml version="1.0" encoding="latin1" ?>
 
2
<!DOCTYPE erlref SYSTEM "erlref.dtd">
 
3
 
 
4
<erlref>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>1996</year>
 
8
      <year>2007</year>
 
9
      <holder>Ericsson AB, All Rights Reserved</holder>
 
10
    </copyright>
 
11
    <legalnotice>
 
12
  The contents of this file are subject to the Erlang Public License,
 
13
  Version 1.1, (the "License"); you may not use this file except in
 
14
  compliance with the License. You should have received a copy of the
 
15
  Erlang Public License along with this software. If not, it can be
 
16
  retrieved online at http://www.erlang.org/.
 
17
 
 
18
  Software distributed under the License is distributed on an "AS IS"
 
19
  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 
20
  the License for the specific language governing rights and limitations
 
21
  under the License.
 
22
 
 
23
  The Initial Developer of the Original Code is Ericsson AB.
 
24
    </legalnotice>
 
25
 
 
26
    <title>eprof</title>
 
27
    <prepared></prepared>
 
28
    <docno></docno>
 
29
    <date></date>
 
30
    <rev></rev>
 
31
  </header>
 
32
  <module>eprof</module>
 
33
  <modulesummary>A Time Profiling Tool for Erlang</modulesummary>
 
34
  <description>
 
35
    <p>The module <c>eprof</c> provides a set of functions for time
 
36
      profiling of Erlang programs to find out how the execution time is
 
37
      used. The profiling is done using the Erlang trace BIFs. Tracing of
 
38
      local function calls for a specfied set of processes is enabled when
 
39
      profiling is begun, and disabled when profiling is stopped.</p>
 
40
    <p>When using Eprof, expect a significant slowdown in program execution,
 
41
      in most cases at least 100 percent.</p>
 
42
  </description>
 
43
  <funcs>
 
44
    <func>
 
45
      <name>start() -> {ok,Pid} | {error,Reason}</name>
 
46
      <fsummary>Start Eprof.</fsummary>
 
47
      <type>
 
48
        <v>Pid = pid()</v>
 
49
        <v>Reason = {already_started,Pid}</v>
 
50
      </type>
 
51
      <desc>
 
52
        <p>Starts the Eprof server which owns the Eprof internal database.</p>
 
53
      </desc>
 
54
    </func>
 
55
    <func>
 
56
      <name>start_profiling(Rootset) -> profiling | error</name>
 
57
      <name>profile(Rootset) -> profiling | error</name>
 
58
      <fsummary>Start profiling.</fsummary>
 
59
      <type>
 
60
        <v>Rootset = [atom() | pid()]</v>
 
61
      </type>
 
62
      <desc>
 
63
        <p>Starts profiling for the processes in <c>Rootset</c> (and any new
 
64
          processes spawned from them). Information about activity in any
 
65
          profiled process is stored in the Eprof database.</p>
 
66
        <p><c>Rootset</c> is a list of pids and registered names.</p>
 
67
        <p>The function returns <c>profiling</c> if tracing could be enabled
 
68
          for all processes in <c>Rootset</c>, or <c>error</c> otherwise.</p>
 
69
      </desc>
 
70
    </func>
 
71
    <func>
 
72
      <name>stop_profiling() -> profiling_stopped | profiling_already_stopped</name>
 
73
      <fsummary>Stop profiling.</fsummary>
 
74
      <desc>
 
75
        <p>Stops profiling started with <c>start_profiling/1</c> or
 
76
          <c>profile/1</c>.</p>
 
77
      </desc>
 
78
    </func>
 
79
    <func>
 
80
      <name>profile(Rootset,Fun) -> {ok,Value} | {error,Reason} | error</name>
 
81
      <name>profile(Rootset,Module,Function,Args) -> {ok,Value} | {error,Reason} | error</name>
 
82
      <fsummary>Start profiling.</fsummary>
 
83
      <type>
 
84
        <v>Rootset = [atom() | pid()]</v>
 
85
        <v>Fun = fun() -> term()</v>
 
86
        <v>Module = Function = atom()</v>
 
87
        <v>Args = [term()]</v>
 
88
        <v>Value = Reason = term()</v>
 
89
      </type>
 
90
      <desc>
 
91
        <p>This function first spawns a process <c>P</c> which evaluates
 
92
          <c>Fun()</c> or <c>apply(Module,Function,Args)</c>. Then, it
 
93
          starts profiling for <c>P</c> and the processes in <c>Rootset</c>
 
94
          (and any new processes spawned from them). Information about
 
95
          activity in any profiled process is stored in the Eprof database.</p>
 
96
        <p><c>Rootset</c> is a list of pids and registered names.</p>
 
97
        <p>If tracing could be enabled for <c>P</c> and all processes in
 
98
          <c>Rootset</c>, the function returns <c>{ok,Value}</c> when
 
99
          <c>Fun()</c>/<c>apply</c> returns with the value <c>Value</c>, or
 
100
          <c>{error,Reason}</c> if <c>Fun()</c>/<c>apply</c> fails with
 
101
          exit reason <c>Reason</c>. Otherwise it returns <c>error</c>
 
102
          immediately.</p>
 
103
        <p>The programmer must ensure that the function given as argument
 
104
          is truly synchronous and that no work continues after
 
105
          the function has returned a value.</p>
 
106
      </desc>
 
107
    </func>
 
108
    <func>
 
109
      <name>analyse()</name>
 
110
      <fsummary>Display profiling results per process.</fsummary>
 
111
      <desc>
 
112
        <p>Call this function when profiling has been stopped to display
 
113
          the results per process, that is:</p>
 
114
        <list type="bulleted">
 
115
          <item>how much time has been used by each process, and</item>
 
116
          <item>in which function calls this time has been spent.</item>
 
117
        </list>
 
118
        <p>Time is shown as percentage of total time, not as absolute time.</p>
 
119
      </desc>
 
120
    </func>
 
121
    <func>
 
122
      <name>total_analyse()</name>
 
123
      <fsummary>Display profiling results per function call.</fsummary>
 
124
      <desc>
 
125
        <p>Call this function when profiling has been stopped to display
 
126
          the results per function call, that is in which function calls
 
127
          the time has been spent.</p>
 
128
        <p>Time is shown as percentage of total time, not as absolute time.</p>
 
129
      </desc>
 
130
    </func>
 
131
    <func>
 
132
      <name>log(File) -> ok</name>
 
133
      <fsummary>Activate logging of <c>eprof</c>printouts.</fsummary>
 
134
      <type>
 
135
        <v>File = atom() | string()</v>
 
136
      </type>
 
137
      <desc>
 
138
        <p>This function ensures that the results displayed by
 
139
          <c>analyse/0</c> and <c>total_analyse/0</c> are printed both to
 
140
          the file <c>File</c> and the screen.</p>
 
141
      </desc>
 
142
    </func>
 
143
    <func>
 
144
      <name>stop() -> stopped</name>
 
145
      <fsummary>Stop Eprof.</fsummary>
 
146
      <desc>
 
147
        <p>Stops the Eprof server.</p>
 
148
      </desc>
 
149
    </func>
 
150
  </funcs>
 
151
</erlref>
 
152