diff options
Diffstat (limited to 'lib/tools/doc/src/eprof.xml')
| -rw-r--r-- | lib/tools/doc/src/eprof.xml | 150 |
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> + |