aboutsummaryrefslogtreecommitdiffstats
path: root/lib/tools/doc/src/eprof.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/tools/doc/src/eprof.xml')
-rw-r--r--lib/tools/doc/src/eprof.xml150
1 files changed, 150 insertions, 0 deletions
diff --git a/lib/tools/doc/src/eprof.xml b/lib/tools/doc/src/eprof.xml
new file mode 100644
index 0000000000..ae1033f2d0
--- /dev/null
+++ b/lib/tools/doc/src/eprof.xml
@@ -0,0 +1,150 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1996</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>eprof</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ </header>
+ <module>eprof</module>
+ <modulesummary>A Time Profiling Tool for Erlang</modulesummary>
+ <description>
+ <p>The module <c>eprof</c> provides a set of functions for time
+ profiling of Erlang programs to find out how the execution time is
+ used. The profiling is done using the Erlang trace BIFs. Tracing of
+ local function calls for a specified set of processes is enabled when
+ profiling is begun, and disabled when profiling is stopped.</p>
+ <p>When using Eprof, expect a significant slowdown in program execution,
+ in most cases at least 100 percent.</p>
+ </description>
+ <funcs>
+ <func>
+ <name>start() -> {ok,Pid} | {error,Reason}</name>
+ <fsummary>Start Eprof.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Reason = {already_started,Pid}</v>
+ </type>
+ <desc>
+ <p>Starts the Eprof server which owns the Eprof internal database.</p>
+ </desc>
+ </func>
+ <func>
+ <name>start_profiling(Rootset) -> profiling | error</name>
+ <name>profile(Rootset) -> profiling | error</name>
+ <fsummary>Start profiling.</fsummary>
+ <type>
+ <v>Rootset = [atom() | pid()]</v>
+ </type>
+ <desc>
+ <p>Starts profiling for the processes in <c>Rootset</c> (and any new
+ processes spawned from them). Information about activity in any
+ profiled process is stored in the Eprof database.</p>
+ <p><c>Rootset</c> is a list of pids and registered names.</p>
+ <p>The function returns <c>profiling</c> if tracing could be enabled
+ for all processes in <c>Rootset</c>, or <c>error</c> otherwise.</p>
+ </desc>
+ </func>
+ <func>
+ <name>stop_profiling() -> profiling_stopped | profiling_already_stopped</name>
+ <fsummary>Stop profiling.</fsummary>
+ <desc>
+ <p>Stops profiling started with <c>start_profiling/1</c> or
+ <c>profile/1</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>profile(Rootset,Fun) -> {ok,Value} | {error,Reason} | error</name>
+ <name>profile(Rootset,Module,Function,Args) -> {ok,Value} | {error,Reason} | error</name>
+ <fsummary>Start profiling.</fsummary>
+ <type>
+ <v>Rootset = [atom() | pid()]</v>
+ <v>Fun = fun() -> term()</v>
+ <v>Module = Function = atom()</v>
+ <v>Args = [term()]</v>
+ <v>Value = Reason = term()</v>
+ </type>
+ <desc>
+ <p>This function first spawns a process <c>P</c> which evaluates
+ <c>Fun()</c> or <c>apply(Module,Function,Args)</c>. Then, it
+ starts profiling for <c>P</c> and the processes in <c>Rootset</c>
+ (and any new processes spawned from them). Information about
+ activity in any profiled process is stored in the Eprof database.</p>
+ <p><c>Rootset</c> is a list of pids and registered names.</p>
+ <p>If tracing could be enabled for <c>P</c> and all processes in
+ <c>Rootset</c>, the function returns <c>{ok,Value}</c> when
+ <c>Fun()</c>/<c>apply</c> returns with the value <c>Value</c>, or
+ <c>{error,Reason}</c> if <c>Fun()</c>/<c>apply</c> fails with
+ exit reason <c>Reason</c>. Otherwise it returns <c>error</c>
+ immediately.</p>
+ <p>The programmer must ensure that the function given as argument
+ is truly synchronous and that no work continues after
+ the function has returned a value.</p>
+ </desc>
+ </func>
+ <func>
+ <name>analyse()</name>
+ <fsummary>Display profiling results per process.</fsummary>
+ <desc>
+ <p>Call this function when profiling has been stopped to display
+ the results per process, that is:</p>
+ <list type="bulleted">
+ <item>how much time has been used by each process, and</item>
+ <item>in which function calls this time has been spent.</item>
+ </list>
+ <p>Time is shown as percentage of total time, not as absolute time.</p>
+ </desc>
+ </func>
+ <func>
+ <name>total_analyse()</name>
+ <fsummary>Display profiling results per function call.</fsummary>
+ <desc>
+ <p>Call this function when profiling has been stopped to display
+ the results per function call, that is in which function calls
+ the time has been spent.</p>
+ <p>Time is shown as percentage of total time, not as absolute time.</p>
+ </desc>
+ </func>
+ <func>
+ <name>log(File) -> ok</name>
+ <fsummary>Activate logging of <c>eprof</c>printouts.</fsummary>
+ <type>
+ <v>File = atom() | string()</v>
+ </type>
+ <desc>
+ <p>This function ensures that the results displayed by
+ <c>analyse/0</c> and <c>total_analyse/0</c> are printed both to
+ the file <c>File</c> and the screen.</p>
+ </desc>
+ </func>
+ <func>
+ <name>stop() -> stopped</name>
+ <fsummary>Stop Eprof.</fsummary>
+ <desc>
+ <p>Stops the Eprof server.</p>
+ </desc>
+ </func>
+ </funcs>
+</erlref>
+