The R13B03 release.OTP_R13B03

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>
+